docs: align rag-api with the portfolio docs standard

[Go-Santiago-Go]

Brings this repo onto the same documentation shape as inference-gateway, so the two read as one body of work rather than two projects that happen to share an author. Two commits, docs only, no code changes.

docs: align the repo with the portfolio README spine and docs layout

README follows the fixed spine: descriptive title, capability bullets, Contents, Demo, The problem, How it works, Quickstart, Trade-offs, Results, What I'd do differently, Known gaps, Repo layout, Documentation, License. Measurements leave the opener for the Results table, since that section is scanned rather than read.

docs/ becomes the standard six files. DEPLOY.md is renamed DEPLOYMENT.md and gains What gets provisioned, the topology diagram, and inline troubleshooting. ARCHITECTURE.md drops the cloud topology and its headings now mirror the README's How it works lead-ins one for one. API.md and CONVENTIONS.md are new.

CONVENTIONS.md is the load-bearing addition. It records the spine, the docs layout, and this repo's accuracy guards, so the standard is enforced in-repo rather than from a gitignored checklist. The drift between the two repos happened because that file did not exist.

Mermaid diagrams drop every classDef and style block so they inherit the reader's light or dark theme instead of rendering as white boxes in dark mode. The AWS topology goes from 74 lines to 19 and keeps the security group rules as edge labels, since those are what make public-subnet tasks defensible.

docs: cut CLAUDE.md down to getting the repo running

CLAUDE.md had become a second architecture document, restating ARCHITECTURE.md, CONVENTIONS.md and the deployment docs, which guarantees the copies drift. It now does one job, matching inference-gateway's file section for section: get the repo running and verify a change.

Nothing unique was deleted. The design conventions were already in ARCHITECTURE.md, including the constraint that both sides embed with the same model and that the pgvector column dimension is pinned to match. The naming exception and accuracy guards were already in CONVENTIONS.md.

The gotcha list is the part that was not written down anywhere:

• a native Postgres shadowing the container on :5432
• /health staying green while Bedrock returns AccessDenied, because the probe touches neither Bedrock nor the database
• go test ./... skipping the store without TEST_DATABASE_URL
• the two identities a fork has to change: the go.mod module path and the OIDC sub claim IDs

Verification

go build ./... and go vet ./... pass. Quickstart request bodies were read off the handler structs rather than carried over, which caught /ingest taking text and not content.