feat(ragctl): consolidated control-plane CLI scaffold (Step 0.10)

TRACKER.md

@@ -9,8 +9,8 @@
 > CI matrix always includes `ubuntu-22.04`, `macos-14`, and `windows-latest`.
 
 **Last updated:** 2026-05-24
-**Current phase:** Phase 0 — Foundation
-**Next action:** Phase 0 Step 0.10 — ragctl CLI scaffold
+**Current phase:** Phase 1 — Ingestion + Knowledge Store
+**Next action:** Phase 1 Step 1.1 — Storage backends
 
 ---
 
@@ -29,15 +29,15 @@
 
 | Phase | Title | Steps | ✅ Done | Remaining |
 |-------|-------|------:|-------:|----------:|
-| 0 | Foundation | 13 | **12** | 1 |
+| 0 | Foundation | 13 | **13** | 0 |
 | 1 | Ingestion + Knowledge Store | 10 | 0 | 10 |
 | 2 | Retrieval Engine | 10 | 0 | 10 |
 | 3 | Gateway & Agent Runtime | 11 | 0 | 11 |
 | 4 | Reliability | 6 | 0 | 6 |
 | 5 | Eval & Observability | 7 | 0 | 7 |
 | 6 | Governance & Tenancy | 10 | 0 | 10 |
 | 7 | Pilot, Harden, GA | 10 | 0 | 10 |
-| **Total** | | **77** | **12** | **65** |
+| **Total** | | **77** | **13** | **64** |
 
 ---
 
@@ -57,7 +57,7 @@
 | 0.7c | Audit log skeleton | ✅ | `build/phase-0/step-0.7c-audit-log-skeleton` | [#31](https://github.com/officialCodeWork/AgentContextOS/pull/31) | `AuditStore` SPI (append/events/verify_chain), `NoopAuditStore` (SHA-256 hash chain), `AuditWriter` facade (store + structured log), 14 conformance tests |
 | 0.8 | Eval skeleton | ✅ | `build/phase-0/step-0.8-eval-skeleton` | [#33](https://github.com/officialCodeWork/AgentContextOS/pull/33) | `rag_core.eval` domain types (GoldenSample, EvalMetrics, EvalReport), `rag_config.eval` metric functions (recall@k, MRR, citation_precision), RagasAdapter spike, `ragctl eval run/show`, 5-sample golden JSONL fixture, `tests/eval/` harness (39 tests) |
 | 0.9 | IaC foundation | ✅ | `build/phase-0/step-0.9-iac-foundation` | [#34](https://github.com/officialCodeWork/AgentContextOS/pull/34) | Terraform modules for Postgres/pgvector, Redis, Qdrant, Elasticsearch (Kubernetes-native, Helm provider); `rag-platform` Helm chart (Deployment, Service, ConfigMap, ServiceAccount, HPA, PDB, Ingress); dev + prod environments; `task infra:*` + `task helm:*` targets; ADR-0003 |
-| 0.10 | `ragctl` CLI scaffold | ⏳ | — | — | `packages/ragctl/` CLI (Typer), `ragctl ingest/query/eval/logs/traces/config` top-level commands, shell completion |
+| 0.10 | `ragctl` CLI scaffold | ✅ | `build/phase-0/step-0.10-ragctl-cli-scaffold` | — | `packages/ragctl/` package (Typer 0.12+), root `ragctl` entry point, working `config`/`eval`/`traces`/`version` groups, scaffolded `ingest`/`query`/`logs`/`tenant`/`plugin`/`secret` groups (announce target step + exit 0), shell completion via `--install-completion`/`--show-completion`; 19 ragctl tests; docs/reference/ragctl.md + docs/guides/ragctl-quickstart.md; py.typed markers added to rag-config + rag-observability |
 
 ---
 

docs/README.md

@@ -9,6 +9,18 @@
 | [eval-skeleton.md](architecture/eval-skeleton.md) | Eval framework architecture: golden-set schema, metric functions, RAGAS spike, `ragctl eval` CLI, extension points |
 | [iac.md](architecture/iac.md) | IaC overview: Terraform module design, Helm chart structure, dev/prod environments, extension points |
 
+## reference/
+
+| File | Description |
+|------|-------------|
+| [ragctl.md](reference/ragctl.md) | Full `ragctl` command reference — public usage, internals, extension points |
+
+## guides/
+
+| File | Description |
+|------|-------------|
+| [ragctl-quickstart.md](guides/ragctl-quickstart.md) | Five-minute tour of the `ragctl` CLI |
+
 ## adr/
 
 | File | Description |

docs/guides/ragctl-quickstart.md

@@ -0,0 +1,104 @@
+# `ragctl` quickstart
+
+A five-minute tour of the control-plane CLI shipped in Step 0.10.
+
+## Install
+
+`ragctl` is part of the AgentContextOS uv workspace. Once you've bootstrapped
+the repo, the command is on your PATH inside the workspace virtualenv:
+
+```bash
+task bootstrap            # one-time: uv sync + pnpm install + pre-commit
+uv run ragctl --help
+```
+
+If you only want the binary outside the workspace (e.g. on an operator
+workstation), install the published package once it lands on PyPI:
+
+```bash
+pip install rag-ragctl
+ragctl --help
+```
+
+## Verify your `rag.yaml`
+
+The most useful command on day one. Run it before applying a config change to
+any environment:
+
+```bash
+ragctl config validate ops/configs/dev.yaml
+# VALID    ops/configs/dev.yaml
+#   version=v1  env=dev  tenants=2
+#   embedder=openai  llm=openai  vector_store=qdrant
+```
+
+`--json` is the form you want from CI or pre-deploy scripts:
+
+```bash
+ragctl config validate ops/configs/dev.yaml --json
+```
+
+To inspect what differs between two configs:
+
+```bash
+ragctl config diff ops/configs/dev.yaml ops/configs/prod.yaml
+```
+
+## Run a golden-set evaluation
+
+The eval harness ships with a 5-sample fixture so you can verify the pipeline
+end-to-end without setting up real backends:
+
+```bash
+ragctl eval run tests/eval/golden/ --top-k 10 --output eval-report.json
+ragctl eval show eval-report.json --verbose
+```
+
+To enable RAGAS faithfulness scoring:
+
+```bash
+pip install 'rag-config[eval]'
+ragctl eval run tests/eval/golden/ --ragas
+```
+
+## Query traces
+
+With the local dev stack running (`task dev-full`), Jaeger is available at
+`http://localhost:16686`:
+
+```bash
+ragctl traces                                # last 20 traces for rag-platform
+ragctl traces --service gateway --limit 50
+```
+
+## Set up shell completion
+
+Pick whichever line matches your shell:
+
+```bash
+ragctl --install-completion       # auto-detect from $SHELL
+ragctl --show-completion zsh > ~/.zfunc/_ragctl   # manual install for zsh
+```
+
+## What's *not* there yet
+
+The following groups are scaffolded — they accept `--help`, exit cleanly,
+and announce which build step delivers the real implementation:
+
+| Command          | Lands in   |
+|------------------|------------|
+| `ragctl plugin`  | Step 1.1   |
+| `ragctl ingest`  | Step 1.10  |
+| `ragctl query`   | Step 3.1   |
+| `ragctl logs`    | Step 5.6   |
+| `ragctl tenant`  | Step 6.1   |
+| `ragctl secret`  | Step 6.7   |
+
+If you script against them today, your script will keep working — the
+exit code and command shape will not change when the real implementation lands.
+
+## See also
+
+- [Command reference](../reference/ragctl.md) — full surface, internals,
+  extension points
+- [TRACKER.md](../../TRACKER.md) — current build status and what's coming next

docs/reference/ragctl.md

@@ -0,0 +1,151 @@
+# `ragctl` — command reference
+
+## Overview
+
+`ragctl` is the operator-facing control-plane CLI for AgentContextOS. It bundles
+configuration, retrieval, evaluation, observability, and tenant-management
+commands into a single binary that talks to local files, the gateway service,
+and the supporting infrastructure (Jaeger, etc.).
+
+Step 0.10 delivers the consolidated CLI scaffold. Each sub-command group is
+wired into the root `ragctl` app so the surface area is discoverable today,
+even where the underlying functionality has yet to land.
+
+## Usage
+
+```bash
+# discover the surface
+ragctl --help
+
+# print the installed version
+ragctl version
+```
+
+## Command groups
+
+| Group     | Step    | Status   | What it does |
+|-----------|---------|----------|--------------|
+| `config`  | 0.4     | working  | Validate and diff `rag.yaml` files. |
+| `traces`  | 0.7     | working  | Query distributed traces from Jaeger. |
+| `eval`    | 0.8     | working  | Run and inspect golden-set evaluations. |
+| `version` | 0.10    | working  | Print the installed `ragctl` version. |
+| `plugin`  | 1.1     | scaffold | Manage SPI plugin registration. |
+| `ingest`  | 1.10    | scaffold | Trigger ingestion pipelines via the gateway. |
+| `query`   | 3.1     | scaffold | Run a query against the gateway. |
+| `logs`    | 5.6     | scaffold | Tail structured logs from the platform. |
+| `tenant`  | 6.1     | scaffold | Manage tenants. |
+| `secret`  | 6.7     | scaffold | Manage tenant secrets. |
+
+Scaffold commands exit `0` and print a one-line "delivered in Step X.Y"
+notice so operators can probe the planned interface without surprise.
+
+### `ragctl config`
+
+```bash
+ragctl config validate path/to/rag.yaml         # exits 0 on success, 1 otherwise
+ragctl config validate path/to/rag.yaml --json  # machine-readable result
+ragctl config diff path/a.yaml path/b.yaml      # show backend differences
+```
+
+### `ragctl eval`
+
+```bash
+ragctl eval run tests/eval/golden/ --top-k 10 --output report.json
+ragctl eval show report.json --verbose
+ragctl eval run tests/eval/golden/ --ragas       # optional faithfulness scoring
+```
+
+`--ragas` requires the optional `ragas` extra:
+
+```bash
+pip install 'rag-config[eval]'
+```
+
+### `ragctl traces`
+
+```bash
+ragctl traces                                                # default service, 20 traces
+ragctl traces --service gateway --limit 50
+ragctl traces --url http://jaeger.observability.svc:16686    # remote Jaeger
+```
+
+### `ragctl version`
+
+```bash
+ragctl version           # → ragctl 0.1.0
+```
+
+## Shell completion
+
+`ragctl` ships with Typer-powered completion for bash, zsh, fish, and
+PowerShell:
+
+```bash
+ragctl --install-completion        # install for the detected shell
+ragctl --show-completion           # print the completion script to stdout
+ragctl --show-completion zsh > _ragctl
+```
+
+## Internals
+
+The CLI lives in [`packages/ragctl/`](../../packages/ragctl/). The Typer app
+is constructed once in `ragctl.main` and exposed as the `ragctl` entry point
+via `[project.scripts]` in `pyproject.toml`.
+
+### Layout
+
+```
+packages/ragctl/
+├── pyproject.toml          # rag-ragctl, depends on rag-core/config/observability
+├── README.md               # short package overview
+└── src/ragctl/
+    ├── __init__.py         # exports app, main, __version__
+    ├── main.py             # root Typer app + all sub-command groups
+    └── py.typed            # type marker for downstream consumers
+```
+
+### Dependencies
+
+`rag-ragctl` depends on:
+- `rag-core` — domain types and errors
+- `rag-config` — `rag.yaml` loader and eval metrics (powers `config` + `eval` groups)
+- `rag-observability` — pulled in transitively for log context
+- `typer>=0.12` — CLI framework
+
+The CLI keeps **no business logic** of its own. Each command is a thin
+adapter over a function exported from the corresponding domain package.
+
+### Scaffold sub-apps
+
+Sub-apps that aren't implemented yet are constructed by the local helper
+`_scaffold_app(group, step, help_text)`. The helper creates a Typer sub-app
+whose default callback prints a "delivered in Step X.Y" notice and exits 0.
+This keeps the published command shape stable from day one — operators can
+script against `ragctl ingest ...` today and the same script will keep
+working when Step 1.10 lands the real implementation.
+
+## Extension points
+
+To add a new sub-command group:
+
+1. Create or import the domain logic in the appropriate package
+   (`rag-core`, `rag-config`, future `rag-retrieval`, etc.).
+2. In `ragctl/main.py`, build a new `typer.Typer()` sub-app, register
+   commands on it, and attach it to the root `app` with `app.add_typer(...)`.
+3. Update the **Command groups** table in this file and the README.
+4. Add tests under `packages/ragctl/tests/`.
+
+To replace a scaffold with a real implementation:
+
+1. Remove the `_scaffold_app(...)` call for that group from `main.py`.
+2. Build the real sub-app the same way you would for a new group.
+3. Update the **Command groups** table — change Status from `scaffold` to
+   `working` and link to the deeper reference page.
+
+## See also
+
+- [Quickstart](../guides/ragctl-quickstart.md) — getting started in 5 minutes
+- [Eval framework architecture](../architecture/eval-skeleton.md) — what
+  drives `ragctl eval`
+- [IaC overview](../architecture/iac.md) — infra surfaces the CLI will
+  manage in later steps

packages/config/pyproject.toml

@@ -28,9 +28,6 @@ eval = [
 rag-core = { workspace = true }
 rag-observability = { workspace = true }
 
-[project.scripts]
-ragctl = "rag_config.cli:app"
-
 [tool.hatch.build.targets.wheel]
 packages = ["src/rag_config"]
 

packages/ragctl/README.md

@@ -0,0 +1,46 @@
+# rag-ragctl
+
+The **`ragctl`** control-plane CLI for AgentContextOS.
+
+## Install
+
+`ragctl` is part of the AgentContextOS uv workspace. Once the workspace is bootstrapped
+(`task bootstrap`), the command is available on your PATH:
+
+```bash
+ragctl --help
+```
+
+## Command groups
+
+| Group | Status | Purpose |
+|-------|--------|---------|
+| `config`  | ✅ available | Validate and diff `rag.yaml` files (Step 0.4). |
+| `eval`    | ✅ available | Run and inspect golden-set evaluations (Step 0.8). |
+| `traces`  | ✅ available | Query distributed traces from Jaeger (Step 0.7). |
+| `version` | ✅ available | Print the installed `ragctl` version. |
+| `ingest`  | 🚧 scaffold  | Trigger ingestion via the gateway (lands in Step 1.10). |
+| `query`   | 🚧 scaffold  | Run a query against the gateway (lands in Step 3.1). |
+| `logs`    | 🚧 scaffold  | Tail structured logs (lands in Step 5.6). |
+| `tenant`  | 🚧 scaffold  | Manage tenants (lands in Step 6.1). |
+| `plugin`  | 🚧 scaffold  | Manage SPI plugins (lands in Step 1.1). |
+| `secret`  | 🚧 scaffold  | Manage tenant secrets (lands in Step 6.7). |
+
+Scaffold commands exit `0` and print which step delivers the real implementation.
+
+## Shell completion
+
+`ragctl` ships with Typer-powered shell completion for bash, zsh, fish, and PowerShell:
+
+```bash
+# install completion for the current shell
+ragctl --install-completion
+
+# print the completion script (e.g. to inspect or pipe into a file)
+ragctl --show-completion
+```
+
+## See also
+
+- [docs/reference/ragctl.md](../../docs/reference/ragctl.md) — full command reference
+- [docs/guides/ragctl-quickstart.md](../../docs/guides/ragctl-quickstart.md) — operator quickstart