officialCodeWork · officialCodeWork · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/README.md b/README.md
@@ -1,87 +1,181 @@
 # AgentContextOS
 
-**One-stop RAG platform for enterprise AI** — pluggable retrieval, multi-tenancy, agent loops, full observability.
+**Production-grade, multi-tenant RAG platform** — pluggable retrieval, enterprise governance, agent loops, and full observability behind one API. **v1.0.0 GA.**
 
-## Quick start
+Four API surfaces — REST, gRPC, MCP, and OpenAI-compatible — over one engine: hybrid retrieval (dense + sparse + graph) with reranking, hallucination guarding, signed per-query provenance, tenant isolation with ACL/PII enforcement, quotas, drift monitoring, eval gates, and billing. Every backend (vector store, embedder, LLM, …) is a swappable plugin behind an SPI, and `rag.yaml` is the portability contract — the same code runs on a laptop, a VM, and Kubernetes.
+
+## What's running once it's up
+
+| Component | Where | What you get |
+|-----------|-------|--------------|
+| **Gateway** | `http://localhost:8000` | REST (`/v1/query`, `/v1/retrieve`, `/v1/ingest/document`, `/v1/feedback`, …), OpenAI-compatible (`/v1/chat/completions`, `/v1/embeddings`, `/v1/models`), gRPC, and MCP — plus `/v1/status/*` (health / metrics / logs) and Swagger UI at `/docs` |
+| **Admin console** | `http://localhost:3100` | Operator GUI: live status, metrics, log tail, tenants, corpora, connectors |
+| **`ragctl`** | your terminal | Control-plane CLI — 37 commands + 13 groups (config, eval, drift, pilots, billing, …); see the [command reference](docs/reference/ragctl.md) |
+
+## Prerequisites
+
+- [`uv`](https://docs.astral.sh/uv/) — manages Python 3.12+ and all server dependencies (**required**)
+- Docker — only needed to run real backends locally (the demo needs none)
+- Node 20 + `pnpm` — only for the admin console and the docs site
+
+## 1. Try it in 5 minutes — demo mode
+
+Zero credentials, zero infrastructure. The gateway starts against an in-memory noop wiring that still exercises the full real pipeline (understand → route → retrieve → rerank → pack):
+
+```bash
+git clone https://github.com/officialCodeWork/AgentContextOS.git
+cd AgentContextOS && uv sync
+
+# Terminal 1 — start the gateway
+uv run uvicorn rag_gateway.app:app --port 8000
+
+# Terminal 2 — check it's up
+curl -s http://localhost:8000/healthz        # → {"status":"ok"}
+```
+
+Ingest a document, then query:
+
+```bash
+curl -s -X POST http://localhost:8000/v1/ingest/document \
+  -F 'tenant_id=demo' -F 'corpus_id=docs' -F 'principal_id=me' \
+  -F 'file=@README.md' | jq '{document_id, status, chunk_count}'
+
+curl -s http://localhost:8000/v1/query \
+  -H 'content-type: application/json' \
+  -d '{"tenant_id":"demo","principal_id":"me","query":"what is AgentContextOS?","top_k":3}' \
+  | jq '{chunks: (.chunks|length), citations: (.citations|length), timings}'
+```
+
+Or run the whole ingest-and-query loop in one process with the CLI:
+
+```bash
+uv run ragctl query "what is RAG?" --top-k 3
+```
+
+Heads-up: in demo mode the two terminals don't share the in-memory store, so cross-process queries come back empty — use `ragctl query` for a populated demo, or wire real backends (next section). Full walkthrough with expected outputs: **[curl quickstart](docs/guides/curl-quickstart.md)**.
+
+## 2. Run with real backends
+
+**Start the backing services** (Postgres + pgvector, Qdrant, Redis, Elasticsearch, MinIO):
 
 ```bash
-# Prerequisites: uv, pnpm, docker
-./scripts/bootstrap.sh   # or: make bootstrap
+make dev          # or: task dev
+make dev-full     # + OTel collector, Jaeger, Prometheus, Grafana, Loki
+```
 
-make dev        # start postgres + redis + qdrant
-make dev-full   # + otel-collector, jaeger, prometheus, grafana, loki
+**Configure `rag.yaml`** — change providers here, nothing else changes:
 
-make lint       # ruff + mypy
-make test       # full test suite
-make help       # all targets
+```yaml
+backends:
+  vector_store:  { provider: qdrant }
+  keyword_store: { provider: elasticsearch }
+  embedder:      { provider: openai, model: text-embedding-3-large }
+  llm:           { provider: anthropic, model: claude-sonnet-4-6 }
+  cache:         { provider: redis }
+```
+
+Ready-made profiles for each deployment shape live in [`examples/configs/`](examples/configs/) — `laptop.yaml`, `single-vm.yaml`, `k8s-onprem.yaml`, `saas.yaml`, `airgap.yaml`. Validate any config with:
+
+```bash
+uv run ragctl config validate rag.yaml
+```
+
+**Serve the configured app.** The gateway builds its wiring from config via `build_app_from_config`:
+
+```python
+# serve.py
+from rag_config import load
+from rag_gateway.wiring import build_app_from_config
+
+app = build_app_from_config(load("rag.yaml"))
+```
+
+```bash
+uv run uvicorn serve:app --host 0.0.0.0 --port 8000
+```
+
+For fully programmatic wiring — injecting backend instances directly instead of via config — see [production wiring](docs/reference/gateway.md#production-wiring).
+
+## 3. Open the admin console
+
+```bash
+pnpm install
+NEXT_PUBLIC_GATEWAY_URL=http://localhost:8000 pnpm --filter @ragplatform/admin-ui dev
+# → http://localhost:3100
+```
+
+Without a gateway URL it renders seed data (every page carries a "Demo data" badge), so you can preview the console standalone. Guide: [admin-ui quickstart](docs/guides/admin-ui-quickstart.md) · live-data tour: [operator console](docs/guides/operator-console-live.md).
+
+## 4. Deploy to production
+
+| Channel | Install | Notes |
+|---------|---------|-------|
+| **Container** | `docker run -p 8000:8000 ghcr.io/officialcodework/agentcontextos/rag-gateway:v1.0.0 uvicorn rag_gateway.app:app --host 0.0.0.0 --port 8000` | cosign-signed, SBOM-attested |
+| **Helm** | `helm install rag oci://ghcr.io/officialcodework/agentcontextos/charts/rag-platform` | chart source in [`infra/helm/rag-platform/`](infra/helm/rag-platform/); wire backends via `values.yaml` |
+| **PyPI** | `pip install rag-platform` | meta-package pins all components to a reproducible server stack |
+| **Air-gapped** | signed offline bundle + `install.sh` | [air-gap install guide](docs/guides/airgap-install.md) |
+
+> **Known gap at v1.0.0:** the published image's *default* CMD prints the version instead of starting the server — pass the `uvicorn` serve command explicitly as shown above. The Helm chart inherits the same gap (its pods rely on the image default), so review the chart against your serve command before first install. A config-driven serve entrypoint is tracked for v1.0.1.
+
+One `vX.Y.Z` tag publishes every channel — signed (cosign keyless) with SBOMs. Details: [packaging & distribution](docs/guides/packaging-distribution.md).
+
+## Talk to it from your stack
+
+| Surface | Guide |
+|---------|-------|
+| REST + curl | [curl-quickstart](docs/guides/curl-quickstart.md) |
+| Python / TypeScript SDKs | [sdk-quickstart](docs/guides/sdk-quickstart.md) |
+| OpenAI-compatible (drop-in `chat/completions`) | [openai-quickstart](docs/guides/openai-quickstart.md) |
+| MCP — Claude Desktop, Cursor, VS Code | [mcp-quickstart](docs/guides/mcp-quickstart.md) |
+| gRPC | [grpcurl-quickstart](docs/guides/grpcurl-quickstart.md) |
+| LangChain / LlamaIndex / Semantic Kernel adapters | [integrations-quickstart](docs/guides/integrations-quickstart.md) |
+| Webhooks (ingest / drift / feedback events) | [webhooks-quickstart](docs/guides/webhooks-quickstart.md) |
+| Agent loop (`POST /v1/agent`) | [agent-quickstart](docs/guides/agent-quickstart.md) |
+
+## Developing on the platform
+
+```bash
+./scripts/bootstrap.sh   # uv sync + pnpm install + pre-commit hooks (or: make bootstrap)
+
+make lint                # ruff + mypy --strict
+make test                # full test suite
+make help                # all targets
 ```
 
 ## Repository layout
 
 ```
 AgentContextOS/
-├── packages/
-│   └── core/              # Domain types, errors, plugin SPIs (Step 0.2–0.3)
+├── packages/              # 30 Python packages: rag-core (types, SPIs), rag-config,
+│                          # rag-observability, rag-policy, rag-backends, per-stage
+│                          # pipeline packages (parsers, chunker, embedders, …),
+│                          # governance (guard, quota, pii, sso, …), and ragctl
 ├── apps/
-│   ├── gateway/           # FastAPI HTTP/gRPC gateway (Phase 3)
-│   └── admin-ui/          # Next.js operator GUI (Phase 3)
-├── tests/
-│   ├── contract/          # SPI conformance suites (Step 0.3)
-│   ├── eval/              # Golden set, baselines, thresholds (Phase 5)
-│   └── logs/              # Log schema + PII gates (Step 0.7b)
-├── proto/                 # Protobuf definitions (Step 0.2)
-├── infra/
-│   ├── otel/              # OTel collector config
-│   └── prometheus/        # Prometheus scrape config
-├── docs/
-│   ├── adr/               # Architecture Decision Records
-│   ├── architecture/      # HLD + architecture diagram
-│   └── research/          # RAG problems catalog
-├── scripts/
-│   └── bootstrap.sh       # One-shot setup for a fresh clone
+│   ├── gateway/           # rag-gateway — REST + gRPC + MCP + OpenAI-compatible service
+│   └── admin-ui/          # Next.js operator console
+├── sdks/                  # Generated Python / TypeScript / Go / Java / .NET clients
+├── website/               # Docusaurus documentation site (sources docs/ directly)
+├── eval/                  # Golden-set eval harness + CI eval gate runner
+├── tests/                 # Cross-package suites: contract, logs, policy, docs, eval
+├── proto/                 # core.proto — canonical cross-language schema
+├── dist/                  # Generated + committed + drift-gated: OpenAPI, JSON schemas
+├── infra/                 # Helm chart, Terraform, OTel / Prometheus / Grafana configs
+├── packaging/             # Docker image + air-gapped bundle build
+├── marketplace/           # Cloud marketplace listing artifacts + pricing model
+├── planning/              # The 8-phase execution plan the build followed
+├── docs/                  # ADRs, architecture, guides, reference, runbooks, compliance
 ├── docker-compose.yml     # Local dev stack (core + observability profiles)
-├── rag.yaml               # Platform config contract (Step 0.4)
-├── pyproject.toml         # Python uv workspace root
-├── pnpm-workspace.yaml    # JS/TS pnpm workspace
-└── Makefile               # All developer commands
+├── rag.yaml               # Platform config contract
+├── Taskfile.yml           # Cross-platform task runner (Makefile wraps it on Unix)
+└── TRACKER.md             # The 84-step build record (all complete)
 ```
 
 ## Documentation
 
-- [High-Level Design](docs/architecture/RAG-Platform-HLD.md) — architecture, components, KPIs
-- [Execution Plan](planning/README.md) — 8-phase build plan with testable steps
-- [Logging Standard](planning/LOGGING-STANDARD.md) — mandatory structured-logging contract
-- [GUI Specification](planning/GUI-SPECIFICATION.md) — operator dashboard spec
-- [ADR-0001](docs/adr/ADR-0001-monorepo-and-tech-stack.md) — monorepo and tech stack decisions
-├── docs/
-│   ├── architecture/          # Design documents
-│   │   ├── RAG-Platform-HLD.md          — High-Level Design (architecture, components, KPIs)
-│   │   └── high-level-architecture.svg  — Layered architecture diagram
-│   └── research/              # Problem analysis and research
-│       ├── enterprise-rag-problems.md   — 22+ catalogued RAG problems with severity ratings
-│       ├── enterprise-rag-problems.pdf  — PDF export of the problem catalog
-│       └── rag-problems-world.html      — Interactive HTML problem explorer
-└── planning/                  # V1 execution plan
-    ├── README.md                        — Planning index and how-to-use guide
-    ├── EXECUTION-PLAN.md                — Master build order, principles, DoD
-    ├── TESTING-STRATEGY.md              — Test pyramid, eval gates, red-team layers
-    ├── LOGGING-STANDARD.md              — Mandatory structured-logging contract
-    ├── GUI-SPECIFICATION.md             — Operator Status & Metrics GUI spec (12 pages)
-    ├── PROBLEM-TRACEABILITY.md          — RAG problem → primary step + gate test
-    ├── RISK-REGISTER.md                 — Tracked risks, owners, mitigations
-    └── phases/
-        ├── phase-0-foundation.md        — Monorepo, plugin SPI, CI/CD, observability
-        ├── phase-1-ingestion.md         — Connectors, parsers, chunker, embedder
-        ├── phase-2-retrieval.md         — Vector, BM25, graph, hybrid RRF, reranker
-        ├── phase-3-gateway-agent.md     — REST/gRPC/MCP, agent loop, SDKs, GUI MVP
-        ├── phase-4-reliability.md       — Semantic cache, fallback chain, guard, breakers
-        ├── phase-5-eval-observability.md — Eval harness, CI gate, drift monitors, full GUI
-        ├── phase-6-governance.md        — Multi-tenancy, ACL, audit log, BYOK, SSO
-        └── phase-7-pilot-ga.md          — Load testing, chaos, partners, GA cutover
-```
-
-## Quick start
-
-1. Read [docs/architecture/RAG-Platform-HLD.md](docs/architecture/RAG-Platform-HLD.md) for the full architecture.
-2. Read [docs/research/enterprise-rag-problems.md](docs/research/enterprise-rag-problems.md) for the problem space.
-3. Open [planning/README.md](planning/README.md) to navigate the execution plan.
+- [docs/README.md](docs/README.md) — full documentation index (published as the docs site)
+- [High-Level Design](docs/architecture/RAG-Platform-HLD.md) — architecture, components, problem → capability map
+- [REST API reference](docs/reference/rest-api.md) — generated from the drift-gated OpenAPI contract
+- [v1.0.0 release notes](docs/release-notes/v1.0.0.md) — what shipped at GA
+- [Support & SLAs](docs/guides/support-sla.md) — support tiers, SLA targets, runbooks
+- [Problem catalog](docs/research/enterprise-rag-problems.md) — the 22+ enterprise RAG failure modes this platform addresses
+- [Execution plan](planning/README.md) — the 8-phase build plan, now complete ([TRACKER.md](TRACKER.md) is the step-by-step record)
diff --git a/docs/README.md b/docs/README.md
@@ -230,17 +230,19 @@ broken, and what to fix before committing to the next phase.
 Design-partner pilot program (Step 7.4) — the operator runbook is
 [guides/design-partner-pilots.md](guides/design-partner-pilots.md); this area
 holds the fill-in templates, per-vertical kits, and published case studies.
+Internal program material — kept on GitHub only, not published on the docs site
+(links below point at GitHub).
 
 | File | Description |
 |------|-------------|
-| [README.md](pilots/README.md) | Pilots index — layout, the five templates, the per-vertical kit registry, the active/graduated-pilot table |
-| [templates/onboarding-checklist.md](pilots/templates/onboarding-checklist.md) | Per-partner onboarding: tenant + governance + corpus + surfaces + measurement + sign-off (scripted by `ragctl pilot onboard`) |
-| [templates/success-criteria.md](pilots/templates/success-criteria.md) | Signed-before-kickoff criteria across quality / latency / integration / security, each with a threshold + the platform signal that proves it |
-| [templates/weekly-kpi.md](pilots/templates/weekly-kpi.md) | One-per-week KPI dashboard (volume / quality / satisfaction / drift / latency / cost / reliability) filled by `ragctl pilot report` |
-| [templates/feedback-log.md](pilots/templates/feedback-log.md) | The intake → triage → incorporate → close loop + the roadmap fold-back for the lessons-learned doc |
-| [templates/case-study.md](pilots/templates/case-study.md) | The referenceable customer story — challenge / solution / reference architecture / results (auditable KPI numbers) / quote |
-| [customer-support/README.md](pilots/customer-support/README.md) | Customer-support / internal-KB pilot kit (Step 7.4b) — sample corpus (PII handbook + product FAQ + a planted injection probe), domain-calibrated success criteria (deflection), the `ragctl pilot` seed-and-demo flow, the PII + injection security demonstration |
-| [customer-support/case-study.md](pilots/customer-support/case-study.md) | Worked case study (Step 7.4d) — the framework run end-to-end on the kit; real `ragctl pilot report` KPIs (satisfaction +0.733 · 0/5 drift · cost ok → PASS) + the PII + injection security demonstration |
+| [README.md](https://github.com/officialCodeWork/AgentContextOS/blob/main/docs/pilots/README.md) | Pilots index — layout, the five templates, the per-vertical kit registry, the active/graduated-pilot table |
+| [templates/onboarding-checklist.md](https://github.com/officialCodeWork/AgentContextOS/blob/main/docs/pilots/templates/onboarding-checklist.md) | Per-partner onboarding: tenant + governance + corpus + surfaces + measurement + sign-off (scripted by `ragctl pilot onboard`) |
+| [templates/success-criteria.md](https://github.com/officialCodeWork/AgentContextOS/blob/main/docs/pilots/templates/success-criteria.md) | Signed-before-kickoff criteria across quality / latency / integration / security, each with a threshold + the platform signal that proves it |
+| [templates/weekly-kpi.md](https://github.com/officialCodeWork/AgentContextOS/blob/main/docs/pilots/templates/weekly-kpi.md) | One-per-week KPI dashboard (volume / quality / satisfaction / drift / latency / cost / reliability) filled by `ragctl pilot report` |
+| [templates/feedback-log.md](https://github.com/officialCodeWork/AgentContextOS/blob/main/docs/pilots/templates/feedback-log.md) | The intake → triage → incorporate → close loop + the roadmap fold-back for the lessons-learned doc |
+| [templates/case-study.md](https://github.com/officialCodeWork/AgentContextOS/blob/main/docs/pilots/templates/case-study.md) | The referenceable customer story — challenge / solution / reference architecture / results (auditable KPI numbers) / quote |
+| [customer-support/README.md](https://github.com/officialCodeWork/AgentContextOS/blob/main/docs/pilots/customer-support/README.md) | Customer-support / internal-KB pilot kit (Step 7.4b) — sample corpus (PII handbook + product FAQ + a planted injection probe), domain-calibrated success criteria (deflection), the `ragctl pilot` seed-and-demo flow, the PII + injection security demonstration |
+| [customer-support/case-study.md](https://github.com/officialCodeWork/AgentContextOS/blob/main/docs/pilots/customer-support/case-study.md) | Worked case study (Step 7.4d) — the framework run end-to-end on the kit; real `ragctl pilot report` KPIs (satisfaction +0.733 · 0/5 drift · cost ok → PASS) + the PII + injection security demonstration |
 
 ## runbooks/
 

diff --git a/docs/adr/ADR-0041-airgap-bundle.md b/docs/adr/ADR-0041-airgap-bundle.md
@@ -3,7 +3,7 @@
 **Status:** Accepted
 **Date:** 2026-06-08
 **Step:** 6.9 — Air-gapped install bundle (Phase 6 — Governance & Tenancy)
-**Related:** [ADR-0038](ADR-0038-immutable-audit-log.md) (content-hash + optional-signature pattern), [ADR-0003](ADR-0003-iac-foundation.md) (Helm chart), [architecture/airgap-bundle.md](../architecture/airgap-bundle.md), [reference/airgap.md](../reference/airgap.md), [guides/airgap-install.md](../guides/airgap-install.md)
+**Related:** [ADR-0038](ADR-0038-immutable-audit-log.md) (content-hash + optional-signature pattern), [ADR-0003](ADR-0003-iac-kubernetes-native.md) (Helm chart), [architecture/airgap-bundle.md](../architecture/airgap-bundle.md), [reference/airgap.md](../reference/airgap.md), [guides/airgap-install.md](../guides/airgap-install.md)
 
 ## Context