Soften the tone of the docs and comments written today

README.md

@@ -12,15 +12,37 @@ book and any similarly-structured PDF), and
 [docs/progress-log.md](docs/progress-log.md) for a running log of what's
 been done and what's next.
 
-> **Status**: directory scaffold only — no business logic implemented yet.
-> See the build roadmap in `docs/architecture.md` for the phased plan.
+Dated planning and audit documents (`docs/v1-delivery-plan.md`,
+`docs/rag-rebuild-plan.md`, `docs/current-rag-pipeline-audit.md`,
+`docs/answer-experience-implementation-plan.md`) record what was known on
+their date and are kept for their reasoning rather than as current status —
+this README and `git log` are the better reference for where things stand
+today.
+
+> **Status** (2026-08-11): **live in production at
+> [realvuxbaro.me](https://realvuxbaro.me)** — a real RAG chatbot over the
+> whole formulary, not a scaffold. What exists and what does not:
+>
+> | Part | State |
+> |---|---|
+> | `ingestion/` | Done — 15,100 chunks embedded and loaded into Qdrant `duocthu_v1` |
+> | `apps/ai-service/` | Done — live grounded RAG (retrieval, generation, grounding, abstention, citations, traces) |
+> | `apps/web/` | Done — chat UI with citation/evidence panel |
+> | `apps/api-gateway`, `auth-service`, `user-service`, `chat-service` | **Not built** — `README.md` + `package.json` only |
+> | `apps/mobile/` | **Not built** — reserved |
+> | `infra/docker/` | Done — this is what production actually runs |
+> | `infra/k8s`, `helm`, `terraform`, `argocd` | **Not built yet** — empty scaffold. Still the target (ADR 0002), not abandoned: the plan is the team's self-hosted Gitea + ArgoCD; the current EC2/Compose setup is an interim stopgap |
+>
+> Because the gateway and auth services do not exist, `apps/web` talks
+> **directly** to `apps/ai-service`; there is no authentication layer. See
+> the build roadmap in `docs/architecture.md`.
 
 ## Directory map
 
 ```
 apps/
-  web/            Next.js frontend
-  ai-service/     Python FastAPI — RAG orchestration + OpenAI calls
+  web/            Next.js frontend (also hosts the BFF route the browser calls)
+  ai-service/     Python FastAPI — RAG orchestration + AWS Bedrock calls
   api-gateway/    NestJS — public entry point, routes to internal services
   auth-service/   NestJS — signup/login/JWT
   user-service/   NestJS — profile/preferences
@@ -36,9 +58,59 @@ infra/            docker-compose, k8s/Helm, Terraform, CI
 docs/             architecture docs and ADRs
 ```
 
-## Prerequisites (once implementation starts)
+## Prerequisites
 
-- Node.js + pnpm (JS workspace: `apps/web`, `apps/api-gateway`, `apps/auth-service`,
-  `apps/user-service`, `apps/chat-service`, `packages/*`)
+- Node.js + pnpm (JS workspace: `apps/web`, `packages/*`; the NestJS service
+  directories are unbuilt placeholders)
 - Python 3.11+ (`apps/ai-service`, `ingestion`)
-- Docker (local Postgres/Qdrant/Redis via `infra/docker/docker-compose.yml`)
+- Docker (local Postgres + Qdrant via `infra/docker/docker-compose.yml`)
+- AWS credentials with Bedrock invoke permission, for anything that generates
+  an answer. Without them `ai-service` still starts, but every answer abstains
+  rather than falling back to raw source text.
+
+## Running it locally
+
+```powershell
+docker compose -f infra\docker\docker-compose.yml up -d postgres qdrant
+cd apps\ai-service
+python -m migrate
+python -m uvicorn main:app --port 8079     # NOT --reload, see below
+```
+
+```powershell
+pnpm install
+pnpm --filter web dev                      # http://localhost:3000
+```
+
+`ai-service` needs a populated Qdrant collection to serve answers: it verifies
+a `duocthu_v1__manifest` sidecar at startup and refuses to run against a corpus
+whose sha/model/dimensions do not match. A fresh machine either restores a
+Qdrant snapshot or re-runs `ingestion/` (the latter costs real Bedrock spend).
+
+> **Prefer a plain restart over `uvicorn --reload` on Windows here.** The
+> reloader has been observed serving the previous code after an edit on this
+> project, which makes it hard to tell whether a change took effect.
+
+Tests: `cd apps/ai-service && python -m pytest -q` — 230 pass. `test_api.py` and
+`test_live_datastores.py` need Postgres and Qdrant actually running; skip them
+with `--ignore` when the stack is down. `apps/web` has **no test setup at all**,
+so a green suite says nothing about the frontend — drive it in a browser.
+
+## Production
+
+Live at [realvuxbaro.me](https://realvuxbaro.me): a single EC2 `t3.large`
+running `infra/docker/docker-compose.prod.yml` (postgres, qdrant, ai-service,
+web, Caddy for automatic Let's Encrypt TLS). Bedrock is reached through an IAM
+instance role — there are no long-lived AWS keys on the box or in any env file.
+
+Pushing to `master` deploys: `.github/workflows/deploy.yml` SSHes in, resets to
+the pushed commit, rebuilds only `ai-service`/`web`, runs migrations and
+health-checks both. Postgres/Qdrant/Caddy are left untouched, so the vector
+data survives deploys (it lives in a named volume, not the container).
+
+This is **interim infrastructure**, not the end state. The intended target is
+still the team's self-hosted **Gitea** (company domain) plus their **ArgoCD**
+instance, per `docs/adr/0002-argocd-gitops.md` — that work is *not started*,
+not cancelled. Until it is deliberately started, the project stays on private
+GitHub, and the team's existing `git.vinmec.tech/ai-team/gitops` repository is
+reference-only: never push this project into it.