Wire the guarded conversational RAG answer layer end-to-end

apps/ai-service/README.md

@@ -1,5 +1,23 @@
 # ai-service
 
-Python/FastAPI. RAG orchestration: embed query -> vector search in Qdrant ->
-build grounded prompt -> call OpenAI chat completion -> return answer +
-citations. Stateless — does not own chat history itself.
+FastAPI service for drug resolution, guarded retrieval, printed-page citations,
+and PostgreSQL retrieval traces.
+
+Local infrastructure:
+
+```powershell
+docker compose -f ..\..\infra\docker\docker-compose.yml up -d postgres qdrant
+python -m migrate
+uvicorn main:app --reload
+```
+
+`GET /health` is always available. `POST /v1/rag/query` requires structured
+`subject_scope` and `intent`; unknown/non-human/recommendation requests fail
+closed. The default `EMBEDDING_PROVIDER=disabled` intentionally leaves the RAG
+backend unavailable until the collection and matching query embedder are
+configured.
+
+`EMBEDDING_PROVIDER=local-smoke` is only for local plumbing checks. Its hashing
+vectors are deterministic but not semantic and must not be used for retrieval
+quality claims. Bedrock is not called by this service and no IAM change is
+required.