docs: deep documentation refresh

changelog.d/786-docs-deep-refresh.md

@@ -0,0 +1,7 @@
+Changed
+Deep documentation refresh: one documentation map with the three supported paths
+and the product surfaces, current main-path tables (tenant registry/report,
+release verification, platform status, ops history, harness approvals), a module
+map for the CLI/MCP surfaces, stale "on main" markers removed, the experimental
+status updated for the persistent registry, and the navigation grouped into a
+product-surfaces section. Docs only; no runtime behavior changes.

docs/capabilities.md

@@ -61,7 +61,8 @@ See [evolution](evolution.md), [architecture](architecture.md),
   split-conformal bounds, anytime-valid e-processes and continuous evaluation.
 
 See [verifier](verifier.md), [statistical evidence](stats-eval.md) and
-[budget](budget.md).
+[budget](budget.md). Release receipts are verified independently with
+`release verify`; see [release](release.md).
 
 ## Trusted promotion
 
@@ -74,7 +75,8 @@ See [verifier](verifier.md), [statistical evidence](stats-eval.md) and
   binding applies when `artifact_hash` is supplied. See
   [trusted promotion](trusted-promotion.md).
 - `promotion_ledger`: an accepted promotion becomes a signed `ArtifactManifest`
-  and a lineage node carrying evidence and decision hashes.
+  and a lineage node carrying evidence and decision hashes. See
+  [release](release.md) and `release verify`.
 - `policy_release`, `proofs`, `safe_selfmod`, `capability_guard`, `risk_policy`,
   `approval`, `leakage`: policy-as-code, signed manifests, invariant
   certificates, capability gates, risk actions, human approval and leakage
@@ -86,24 +88,29 @@ See [verifier](verifier.md), [statistical evidence](stats-eval.md) and
 - `controller`, `runtime`, `campaign`, `tournament`: bounded sessions,
   `run_guarded`, multi-session campaigns and algorithm tournaments.
 - `durable_runs`: SQLite event log, leases, idempotency, retries, resume.
-- `workspaces`: tenant/workspace RBAC, quota reservations, scoped audit.
+- `workspaces`, `workspace_store`, `tenant_platform`: tenant/workspace RBAC,
+  quota reservations, scoped audit and a durable registry snapshot. See
+  [tenant](tenant.md) and `tenant report`.
 - `rsi_metrics`, `rsi_telemetry`: Prometheus samples and OTel-shaped spans.
-- `ops_console`: the read model for runs, approvals, QD, lineage and cost.
-- `ops_fabric` (on main): write one `LoopReport` into console, lineage,
+- `trace_digest`: a layered, sourced trajectory digest a reflector can consume;
+  see [trajectory evidence](traces.md) and `traces digest|show`.
+- `ops_console`: the read model for runs, approvals, QD, lineage and cost. See
+  [operations](ops.md), including `ops history`.
+- `ops_fabric`: write one `LoopReport` into console, lineage,
   telemetry and a QD snapshot.
-- `platform.RSIPlatform` (on main): one cycle of compute → loop → promote →
+- `platform.RSIPlatform`: one cycle of compute → loop → promote →
   foundry → experience, with `complete=False` when a configured layer produces
   no decision. See [platform](platform.md).
 
-See [runtime](runtime.md), [controller](controller.md) and
-[execution](execution.md).
+See [runtime](runtime.md), [controller](controller.md),
+[execution](execution.md), [platform](platform.md) and [ops](ops.md).
 
 ## Tasks, capabilities and archives
 
 - `data_flywheel`: traces → filtered, redacted, deduplicated dataset candidates.
 - `task_foundry`: failure seeds → validated, deduplicated, contamination-checked
   train/holdout tasks.
-- `task_pipeline` (on main): the hand-off between those two, respecting the
+- `task_pipeline`: the hand-off between those two, respecting the
   foundry's own verdict.
 - `tool_synthesis`: generate, validate and select tools; the generator sees
   earlier rejection reasons.

docs/docs.md

@@ -9,14 +9,68 @@ Choose the route that matches what you want to do. Each guide links to the deepe
 <div class="ad-doc-paths">
   <a href="../install/"><span>01 / START</span><strong>Use it in your agent</strong><small>Install AgentDescent, connect Claude Code, Codex, OpenCode or DeepSeek Harness, and review your first change.</small><b>Open Quickstart ↗</b></a>
   <a href="../#demo"><span>02 / TRY</span><strong>See the interaction</strong><small>Walk through a sample agent conversation in the interactive demo on the homepage.</small><b>Try the demo ↗</b></a>
-  <a href="../modules/"><span>03 / BUILD</span><strong>Compose an evolution loop</strong><small>Find strategies, actors, rewards, policies, workers, and the replaceable optimizer.</small><b>Explore the module map ↗</b></a>
+  <a href="../main-path/"><span>03 / MAP</span><strong>Read the supported path</strong><small>Three paths, the advanced layers, and the canonical module for each concept.</small><b>Open the main path ↗</b></a>
   <a href="../self-evolution-examples/"><span>04 / STUDY</span><strong>Browse 23 algorithm ports</strong><small>See how published methods fit different artifact types and algorithm choices.</small><b>Browse methods ↗</b></a>
 </div>
 
+## The three supported paths
+
+| path | you have | the product surface |
+|---|---|---|
+| **A — evolve one artifact** | tasks, a reward, an actor | `agentdescent plan/evolve/status/show/apply` |
+| **B — governed release** | paired held-out scores | `agentdescent release` + `release verify` |
+| **C — continuous platform** | a run database and callbacks | `agentdescent platform` + `platform status` |
+
+Read [the main path](main-path.md) first if you are deciding where a new
+capability belongs; it is the design contract, not another module list.
+
+## Product surfaces
+
+| surface | verbs | guide |
+|---|---|---|
+| release | `release`, `release verify` | [Release a candidate](release.md) |
+| traces | `traces digest/show` | [Trajectory evidence](traces.md) |
+| governed harness | `governed-harness plan/run/approvals/approve/reject` | [Governed harness](governed-harness.md) |
+| tenant | `tenant plan/run/report` | [Tenant cycle](tenant.md) |
+| operations | `ops plan/publish/history` | [Operations console](ops.md) |
+| platform | `platform init/plan/run/status` | [The RSI platform cycle](platform.md) |
+| capability growth | `capability init/plan/run` | [Capability loop](capability-loop.md) |
+
+These are product surfaces over the same `evolve()` engine, not separate
+algorithms. Each returns `schema_version: 1` and fails closed under `--json`.
+
 ## Go deeper
 
-- **Understand the model:** [Core concepts](concepts.md), [architecture](architecture.md), and the [data model](data-model.md).
-- **Make an artifact evolvable:** [Strategies](strategies.md), [directory evolution](directory-evolution.md), and the [`evolve()` method](evolution.md).
-- **Choose an algorithm:** [Policy slots](policies.md), the [policy guide](policy-guide.md), and [custom aggregators](aggregator-factory.md).
-- **Run with control:** [Parallelism](parallelism.md), [async execution](async.md), [verification](verifier.md), and [governance](governance.md).
-- **Look up an interface:** [API reference](api.md) and [agent integration details](plugins.md).
+**Understand the model.**
+[Core concepts](concepts.md) · [Architecture](architecture.md) ·
+[Data model](data-model.md) · [Governance](governance.md) ·
+[Capability map](capabilities.md) · [Main path](main-path.md).
+
+**Build an evolution loop.**
+[The `evolve()` method](evolution.md) · [Strategies](strategies.md) ·
+[Policies](policies.md) · [Policy guide](policy-guide.md) ·
+[Aggregators](aggregator-factory.md) · [Directory evolution](directory-evolution.md).
+
+**Run and operate it.**
+[Parallelism](parallelism.md) · [Async](async.md) · [Execution](execution.md) ·
+[Sandboxes](sandboxes.md) · [Budget](budget.md) · [Loop kernel](loop-kernel.md) ·
+[Runtime](runtime.md) · [Controller](controller.md) · [Diagnose](diagnose.md) ·
+[Trajectory evidence](traces.md) · [Metrics](metrics.md) · [Module audit](module-audit.md).
+
+**Trust, release and govern.**
+[Verifier](verifier.md) · [Sparse audit](audit.md) ·
+[Statistical evidence](stats-eval.md) · [Trusted promotion](trusted-promotion.md) ·
+[Trusted evidence](trust-evidence.md) · [Release](release.md) ·
+[Approval](approval.md) · [Safety](safety.md) · [Risk policy](risk-policy.md) ·
+[Decision log](decisions.md) · [Manifest](manifest.md).
+
+**Study the methods and measurements.**
+[23 self-evolution ports](self-evolution-examples.md) · [Results](results.md) ·
+[Efficiency](efficiency.md) · [Runtime matrix](matrix-overview.md) ·
+[Harness composition](harness-composition.md) · [Consolidation](consolidation.md) ·
+[Self-improvement](self-improve.md) · [Longitudinal RSI](rsi.md).
+
+**Reference and host integration.**
+[API reference](api.md) · [Agents](agents.md) · [Plugins](plugins.md) ·
+[Plugin quickstart](plugin-quickstart.md) · [Testing guide](testing-guide.md) ·
+[Testing the plugins](testing-the-plugins.md) · [Usage](usage.md).

docs/experimental.md

@@ -44,6 +44,7 @@ These are no longer isolated; keep them out of the "unwired" list.
 | `agentdescent.adaptive_experience` | `experience cycle` / MCP `experience_cycle` (#711) |
 | `agentdescent.budgeted_loop` | `platform` `step.budgeted` (#712) |
 | `agentdescent.tenant_platform` + `agentdescent.workspaces` | `tenant` one quota-checked platform cycle (#715) |
+| `agentdescent.workspace_store` | `tenant` durable registry: quota/audit across runs, read by `tenant report` (#733, #740) |
 
 ## What this means
 

docs/main-path.md

@@ -79,14 +79,31 @@ it only inspects the durable run store.
 | layer | canonical modules | surface |
 |---|---|---|
 | capability growth | `task_pipeline`, `capability_scout`, `capability_foundry`, `capability_archive`, `capability_loop` | `agentdescent capability` |
-| tenancy | `workspaces`, `tenant_platform` | `agentdescent tenant` (`plan`, `run`) |
+| tenancy | `workspaces`, `tenant_platform`, `workspace_store` | `agentdescent tenant` (`plan`, `run`, `report`) |
 | operations | `ops_fabric` (write), `ops_console` (read), `rsi_metrics`, `rsi_telemetry`, `campaign_ops` | `agentdescent ops` (`plan`, `publish`, `history`) |
 | meta-learning | `meta` (including `continuous_meta_run`), `meta_curriculum`, `meta_population`, `meta_campaign`, `meta_audit`, `meta_exam`, `verified_seed` | `agentdescent meta-campaign`, `exam`, `audit` |
 | governed harness | `safe_selfmod`, `proofs`, `approval`, `safety_controller`, `governed_harness` | `agentdescent governed-harness` (`plan`, `run`, `approvals`, `approve`, `reject`) |
 
 These are not “extra algorithms”; they are the control, evidence and memory
 layers around the three paths.
 
+## Product surfaces at a glance
+
+| surface | verbs | guide |
+|---|---|---|
+| release | `release`, `release verify` | [release.md](release.md) |
+| traces | `traces digest/show` | [traces.md](traces.md) |
+| governed harness | `governed-harness plan/run/approvals/approve/reject` | [governed-harness.md](governed-harness.md) |
+| tenant | `tenant plan/run/report` | [tenant.md](tenant.md) |
+| operations | `ops plan/publish/history` | [ops.md](ops.md) |
+| platform | `platform init/plan/run/status` | [platform.md](platform.md) |
+| capability growth | `capability init/plan/run` | [capability-loop.md](capability-loop.md) |
+
+Every surface is a wrapper over the same `evolve()` engine or a durable run
+store; none is a second optimiser. `release verify`, `platform status`,
+`ops history`, `tenant report` and the harness approval verbs are read-only or
+append-only where their guides say so.
+
 ## One concept, one owner
 
 The package grew by adding a module per capability. That left several near
@@ -117,15 +134,14 @@ exist, so new code should follow the canonical column.
    `{"ok": false, "error": ...}` under `--json`, and confines MCP refs/writes
    with `AGENTDESCENT_SURFACE_ALLOW` / `AGENTDESCENT_SURFACE_WRITE_DIRS`.
 4. If it is research, do not export it from `agentdescent/__init__`; describe it
-   as experimental in `modules.md`. The `agentdescent/experimental/` namespace is
-   the next step for it once that move lands.
+   as experimental in `modules.md` and keep it in `agentdescent/experimental/`.
 5. If it duplicates an existing concept, extend the canonical module or add a
    documented alias; do not ship a second engine.
 
 ## Related pages
 
 - [Module audit](module-audit.md) — the current static reachability report.
-- The experimental status page (once it lands) — research and recently
+- [Experimental status](experimental.md) — research prototypes and recently
   productized modules.
 - [Architecture](architecture.md) — the five layers and their data flow.
 - [Module map](modules.md) — the catalog.

docs/modules.md

@@ -89,6 +89,22 @@ and *how*, that is *what*.
 | `ledger` | the git-backed, compare-and-swap artifact store | [Ledger](ledger.md) |
 | `governance` | L0 frozen / L1 slow / L2 fast, by blast radius | [Governance](governance.md) |
 
+## Product surfaces
+
+The CLI/MCP verbs are thin seams over these modules. They validate inputs,
+return `schema_version: 1`, and never reimplement the decision logic below.
+
+| module | what it is | page |
+|---|---|---|
+| `release_surface`, `release_pipeline`, `policy_release`, `promotion_ledger`, `lineage` | signed release receipt, independent verification and lineage | [Release](release.md) |
+| `surface_governed`, `governed_harness`, `approval`, `proofs`, `safe_selfmod` | one governed harness change: gate, proof, human approval, canary, promotion | [Governed harness](governed-harness.md) |
+| `surface_tenant`, `tenant_platform`, `workspaces`, `workspace_store` | roles, quota reservations, scoped audit and a durable registry snapshot | [Tenant](tenant.md) |
+| `surface_ops`, `campaign_ops`, `ops_fabric`, `ops_console`, `rsi_metrics`, `rsi_telemetry` | terminal runs into the control room, plus a JSONL publish history | [Operations](ops.md) |
+| `surface_platform`, `platform`, `platform_campaign`, `loop_kernel`, `durable_runs` | durable five-layer cycles and read-only campaign inspection | [Platform](platform.md) |
+| `surface_capability`, `capability_loop`, `capability_foundry`, `capability_scout` | failures into an admitted capability | [Capability loop](capability-loop.md) |
+| `trace_digest` | layered, sourced trajectory digest and drill-down | [Trajectory evidence](traces.md) |
+| `surface_common`, `runstore`, `rsi_control`, `controller`, `campaign`, `tournament` | shared envelopes/allowlists, detached runs and bounded sessions | [Runtime](runtime.md) |
+
 ## Across all of it
 
 | module | what it is | page |

mkdocs.yml

@@ -108,18 +108,19 @@ nav:
     - The RSI loop kernel: loop-kernel.md
     - Trusted promotion: trusted-promotion.md
     - Trusted evidence: trust-evidence.md
-    - Release a candidate: release.md
-    - Trajectory evidence: traces.md
-    - Governed harness change: governed-harness.md
-    - Meta campaign: meta-campaign.md
-    - Tenant cycle: tenant.md
     - Module audit: module-audit.md
     - Adaptive compute: compute-policy.md
     - Capability foundry: capability-foundry.md
     - Continual experience: continual-experience.md
+  - Product surfaces:
+    - Release a candidate: release.md
+    - Trajectory evidence: traces.md
+    - Governed harness change: governed-harness.md
+    - Tenant cycle: tenant.md
+    - Operations console: ops.md
     - The RSI platform cycle: platform.md
     - Capability loop: capability-loop.md
-    - Operations console: ops.md
+    - Meta campaign: meta-campaign.md
     - Experience store: experience-cli.md
   - The decision plane (policies):
     - Choosing policies: policies.md