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

docs/adr/0000-template.md

@@ -0,0 +1,32 @@
+# ADR-0000: <Decision Title>
+
+---
+**Status:** proposed | accepted | superseded | rejected  
+**Date:** YYYY-MM-DD  
+**Owners:** <names/roles>  
+**Related:** <links to other ADRs / docs>  
+---
+
+## Context
+What problem are we solving?  
+What constraints matter (scale, compliance, team, timeline, cost)?
+
+## Decision
+State the decision clearly and specifically.
+
+## Alternatives Considered
+List viable alternatives with short pros/cons.
+
+## Consequences
+### Positive
+- …
+
+### Negative / Risks
+- …
+
+## Migration / Rollback Plan
+If we change our mind later, how do we move safely?
+
+## References
+- Links to relevant docs, benchmarks, vendor docs, or prototypes.
+

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`.
+