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

docs/adr/README.md

@@ -0,0 +1,44 @@
+# Architecture Decision Records (ADR)
+
+ADRs are short, versioned documents that capture **why** we made a major architectural/product decision.
+They prevent “tribal knowledge” and make reversals/migrations explicit.
+
+---
+**Last Updated:** 2025-12-12  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft — adopt in Phase 1  
+**Owner:** Tech Leads  
+---
+
+## When to write an ADR
+Create an ADR whenever a decision is:
+- hard to reverse later,
+- affects multiple modules/teams,
+- has meaningful trade‑offs,
+- changes default recommendations in `/docs`.
+
+Examples:
+- modular monolith vs microservices,
+- Postgres + `pgvector` vs external vector DB,
+- billing model (subscription vs usage),
+- RAG vs non‑RAG architecture,
+- auth provider choice.
+
+## Where ADRs live
+One file per decision in `docs/adr/`.
+
+Naming convention:
+- `0001-short-title.md`
+- `0002-another-decision.md`
+
+Status lifecycle:
+`proposed` → `accepted` → (`superseded` | `rejected`)
+
+## How ADRs relate to `RECOMMENDATIONS.md`
+- `RECOMMENDATIONS.md` is the **current snapshot** of locked decisions and constraints.
+- ADRs are the **history and rationale** behind those decisions.
+Link every ADR from `RECOMMENDATIONS.md` once accepted.
+
+## Template
+Start from `docs/adr/0000-template.md`.
+