From 328245c31e136f808a5026f82f05d7ce4d369378 Mon Sep 17 00:00:00 2001 From: Day Dreamer <87640074+HugoXK@users.noreply.github.com> Date: Fri, 6 Nov 2026 09:21:14 +0800 Subject: [PATCH] docs: deep documentation refresh --- changelog.d/786-docs-deep-refresh.md | 7 +++ docs/capabilities.md | 25 +++++++---- docs/docs.md | 66 +++++++++++++++++++++++++--- docs/experimental.md | 1 + docs/main-path.md | 24 ++++++++-- docs/modules.md | 16 +++++++ mkdocs.yml | 13 +++--- 7 files changed, 127 insertions(+), 25 deletions(-) create mode 100644 changelog.d/786-docs-deep-refresh.md diff --git a/changelog.d/786-docs-deep-refresh.md b/changelog.d/786-docs-deep-refresh.md new file mode 100644 index 00000000..6a73949f --- /dev/null +++ b/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. diff --git a/docs/capabilities.md b/docs/capabilities.md index 792282e1..b7c190f5 100644 --- a/docs/capabilities.md +++ b/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. diff --git a/docs/docs.md b/docs/docs.md index b2f7cf97..dfb6bebf 100644 --- a/docs/docs.md +++ b/docs/docs.md @@ -9,14 +9,68 @@ Choose the route that matches what you want to do. Each guide links to the deepe
01 / STARTUse it in your agentInstall AgentDescent, connect Claude Code, Codex, OpenCode or DeepSeek Harness, and review your first change.Open Quickstart ↗ 02 / TRYSee the interactionWalk through a sample agent conversation in the interactive demo on the homepage.Try the demo ↗ - 03 / BUILDCompose an evolution loopFind strategies, actors, rewards, policies, workers, and the replaceable optimizer.Explore the module map ↗ + 03 / MAPRead the supported pathThree paths, the advanced layers, and the canonical module for each concept.Open the main path ↗ 04 / STUDYBrowse 23 algorithm portsSee how published methods fit different artifact types and algorithm choices.Browse methods ↗
+## 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). diff --git a/docs/experimental.md b/docs/experimental.md index dc5667f0..46387efe 100644 --- a/docs/experimental.md +++ b/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 diff --git a/docs/main-path.md b/docs/main-path.md index 657a9ff4..91c7c6d6 100644 --- a/docs/main-path.md +++ b/docs/main-path.md @@ -79,7 +79,7 @@ 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`) | @@ -87,6 +87,23 @@ it only inspects the durable run store. 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. diff --git a/docs/modules.md b/docs/modules.md index fd35af2e..a963dbfe 100644 --- a/docs/modules.md +++ b/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 | diff --git a/mkdocs.yml b/mkdocs.yml index 49bd249c..37129baf 100644 --- a/mkdocs.yml +++ b/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