Update documentation to align terminology, clarify project stages, and improve consistency; add RECOMMENDATIONS.md for project-specific guidance.

RECOMMENDATIONS.md

@@ -0,0 +1,59 @@
+# Project-Specific Recommendations & Overrides
+
+This file is the project-specific layer on top of the generic template.  
+Humans and AI agents should treat it as the **single place to record locked decisions, non‑negotiable constraints, and intentional deviations** from `docs/` guidance.
+
+Update this file whenever you make a decision that changes the stack, scope, constraints, or any recommendation in `docs/`.
+
+---
+
+## 1. Project Context (fill in)
+- **Domain / product type:** _[e.g., customer support AI, compliance assistant, content classifier]_  
+- **Primary users:** _[roles/personas]_  
+- **Key success metrics:** _[latency, accuracy, cost, adoption, etc.]_  
+- **Current phase:** _Phase 0 / 1 / 2 / 3 / 4_  
+- **Repos/services in scope:** _[monorepo, separate FE/BE, workers, etc.]_
+
+## 2. Locked Stack Decisions (override template here)
+If a choice is not listed here, the default recommendations in `docs/` apply.
+
+**Frontend**
+- **Framework:** _Next.js (App Router)_ / _other_  
+- **Language:** _TypeScript_ / _other_  
+- **Styling:** _Tailwind CSS_ / _other_  
+- **Server/Client data layer:** _React Query / SWR / other_  
+- **Forms & validation:** _React Hook Form + Zod_ / _other_  
+- **Auth client:** _Clerk / Auth.js / other_
+
+**Backend**
+- **Runtime/language:** _Node.js (LTS) + TypeScript_ / _other_  
+- **Framework:** _Express / Fastify / other_  
+- **Database:** _Postgres_ / _other_ (vector search: _pgvector_ / _other_)  
+- **Queues/workers:** _BullMQ (Redis)_ / _other_  
+- **LLM provider & helper:** _Single abstraction (e.g., `callLLM()`)_, provider _[fill in]_  
+- **File/storage:** _S3/Supabase Storage/local_ / _other_
+
+**Infra / DevOps**
+- **Hosting/deploy:** _[Vercel/Fly/K8s/etc.]_  
+- **CI/CD:** _[GitHub Actions/GitLab/etc.]_  
+- **Observability:** _[Sentry/OTel/Prometheus/etc.]_  
+- **Environments:** _dev/stage/prod_ (or specify)
+
+## 3. Non‑Negotiable Constraints (add to RULES scope)
+- **Compliance/regulation:** _[PII/PHI/PCI, SOC2, GDPR, etc.]_  
+- **Data residency/retention:** _[regions, retention window]_  
+- **Performance/SLOs:** _[e.g., p95 < X ms, batch window]_  
+- **Cost limits:** _[monthly LLM budget, infra cap]_  
+- **Target platforms:** _[browsers/devices, locales]_  
+- **Repository constraints:** _[additional forbidden commands, branching rules, etc.]_
+
+## 4. Deviations From Template (explicit trade-offs)
+List any intentional departures from `docs/` recommendations and why.
+
+- _[Decision]_ → _[Why]_ → _[Migration/rollback plan if relevant]_
+
+## 5. Open Questions / To Confirm
+- _[Unresolved item]_ → _[owner]_ → _[ETA]_
+
+## 6. Change Log (optional)
+- _YYYY‑MM‑DD_: _[decision summary]_