Add foundational documentation templates to support product design and architecture planning, including ADR, archetypes, LLM systems, dev setup, and shared modules.

docs/archetypes.md

@@ -0,0 +1,86 @@
+# Product Archetypes & Optional Modules (Starter Template)
+
+This template is intentionally **modular**. It contains a set of reusable building blocks and an example “pipeline‑based AI SaaS” path.  
+To keep it universal, **choose an archetype first**, then keep only the modules that apply to your product.
+
+---
+**Last Updated:** 2025-12-11  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft  
+**Owner:** Product + Tech Leads  
+---
+
+## 1. Choose a Product Archetype
+
+Pick the closest archetype and adapt terminology/screens/modules accordingly.
+
+### A) Chat‑first Assistant
+Typical products: customer support assistant, internal copilot, personal agent.
+- Primary surface: chat / conversational UI, or API chat endpoint.
+- Data: conversation history + optional knowledge/RAG sources.
+- Feedback: thumbs up/down, corrections, or escalation to humans.
+- Optional modules: multi‑tenancy, integrations, billing, audit/events.
+
+### B) Workflow / Generation Tool
+Typical products: content generation studio, design assistant, coding tool.
+- Primary surface: forms + iterative generation, drafts, versions.
+- Data: artifacts (drafts, assets), prompts, evaluations.
+- Feedback: edit‑and‑retry loops, version diffing, human review optional.
+- Optional modules: billing, audit/events, integrations for input/output.
+
+### C) Classification / Decision Support Pipeline
+Typical products: document labeling, risk scoring, compliance triage.
+- Primary surface: list/review UI for items; batch processing.
+- Data: items/records, rules, embeddings, traces.
+- Feedback: approvals/overrides, rule creation.
+- Optional modules: multi‑tenancy, billing, integrations, events feed.
+
+### D) Agentic Automation / Orchestration
+Typical products: multi‑step agents, task executors, ops automation.
+- Primary surface: tasks/jobs + progress, optional chat.
+- Data: tasks, tools/integrations, execution logs, policies.
+- Feedback: human checkpoints, rollback, audit.
+- Optional modules: queues/workers, events feed, multi‑tenancy, billing.
+
+### E) Internal / One‑off AI Tool
+Typical products: internal dashboards, research tools, prototypes.
+- Primary surface: lightweight UI or scripts.
+- Data: domain‑specific, usually single‑tenant.
+- Feedback: simple review loops.
+- Optional modules: keep only what you truly need.
+
+## 2. Optional Modules (Mix & Match)
+
+These are reusable “lego blocks”. Rename entities to your domain.
+
+1. **Core AI capability**
+   - Chat, generation, classification, RAG, or automation.
+2. **Integrations / Ingestion**
+   - OAuth2, webhooks, file uploads, connector SDKs.
+3. **Processing pipeline**
+   - Rules → embeddings → LLM fallback (or any staged flow).
+4. **Human feedback loop**
+   - Approvals, edits, corrections, escalation.
+5. **Artifacts / Items store**
+   - Messages, drafts, tasks, records — whatever your domain produces.
+6. **Events / Audit log**
+   - `EventLog`, trace IDs, optional `reasoning_trace`.
+7. **Multi‑tenancy & RBAC**
+   - Tenants, roles, isolation (optional for single‑tenant/internal tools).
+8. **Billing**
+   - Provider‑hosted subscriptions/usage (optional).
+9. **Reporting / Analytics**
+   - Dashboards, exports, evaluation metrics.
+10. **Queues / Workers**
+   - For long‑running jobs, retries, backoff (optional).
+
+## 3. How to Adapt the Template Quickly
+
+1. In `RECOMMENDATIONS.md`, write:
+   - chosen archetype (A–E),
+   - which modules you keep/remove,
+   - locked stack decisions and constraints.
+2. Rename “records/rules/approvals” to your domain terms.
+3. Delete or archive irrelevant docs/modules early to reduce drift.
+4. Update `DOCS.md` navigation and phase status after decisions.
+