diff --git a/AGENTS.md b/AGENTS.md
index 25c23ee..6d37ef1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,5 +87,5 @@ accurate: regenerate it with `python -B tools/build_export_manifest.py`. Do not
## License
Contributions are licensed [GPL-3.0-only](LICENSE). As stated in the
-[README](README.md#license), commercial licenses are available from
+[README](README.md#contributing-security-and-license), commercial licenses are available from
Refrigeration.AI via craig@nh3.biz.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 40901c3..caf68d0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@ release yet; entries name the pull requests that made them.
### Changed
- Re-vendored the four pinned foundations at the commits that merged the 2026-11-09 backfill-review fixes: refrigeration `f78905d`, film `52fa82c`, robotics `d61de96`, template `0dcf469` (template gains one test file, 50 entries). Upstream changed only docs, tests and tools; no bridge or schema changed, so inventory hashes are unchanged. `poodo_skill` moves to `aeba967` (its 45 synced files are byte-identical; the new upstream release-docs test file is listed as deferred). `EXPORT-MANIFEST.json` rebuilt. EndoForge stays pinned until its rounds 8-10 merge.
+- README and docs index rewritten for a first-time reader: purpose, a real approval run, a top-down diagram and install first; the NASA control documents sit behind one "Engineering records" section. Material moved out of the README went to new how-to guides (approve asks, define bots, use a real model, add a domain, merge train) and an explanation of Foundations and pins. The README's Measured table moved to `docs/verification/measured-2026-11.md`, with every figure tied to a commit on `main` (assurance finding F-7) (#80).
### Added
diff --git a/EXPORT-MANIFEST.json b/EXPORT-MANIFEST.json
index f88d868..f7a575a 100644
--- a/EXPORT-MANIFEST.json
+++ b/EXPORT-MANIFEST.json
@@ -47,12 +47,12 @@
"bytes": 153
},
"AGENTS.md": {
- "sha256": "e216c6f6afc88ce65c13a1cd38d98180bfe48bbfa7b489a3a95eecd3ead3ca59",
- "bytes": 4333
+ "sha256": "225a126498a68afceb1c6168a10d3fe02c50383bd1034fea83d0ea1d4cecb47c",
+ "bytes": 4359
},
"CHANGELOG.md": {
- "sha256": "29eeb42f944739dfc8572a823cd37e851926ef20dddf22bc7f984152fced2eb3",
- "bytes": 6573
+ "sha256": "4b45ad9f8663e5d4e32a2398d5be78a5eeb21bbf95ad3ec5f520f845524c828e",
+ "bytes": 7103
},
"CODE_OF_CONDUCT.md": {
"sha256": "6228457a516409a784d807676564c8477f58d979eb7df3a4f690008d8a794442",
@@ -71,8 +71,8 @@
"bytes": 1183
},
"README.md": {
- "sha256": "b5eb607a6a57b679568b14f30bb8280b8e1e6fa90bf0e34231581ef4a17cd065",
- "bytes": 17903
+ "sha256": "f180ee76b42982e1d4b7a83064746a6684ef1704270d0c0d18f7a9c468d5d015",
+ "bytes": 16333
},
"SECURITY.md": {
"sha256": "ca32c78d9c9402d31cfac4538c20ddbc9e689f9ce6ecec40fd7535e651edba65",
@@ -471,16 +471,16 @@
"bytes": 684
},
"docs/README.md": {
- "sha256": "e46d9d5b87936dfbffb3ac99c003ae0639d29d69e0b1430733f07092cda68987",
- "bytes": 5277
+ "sha256": "914f226db4b69a76e5ccbe616005d65c4def91fa8f95427e33359e638a18315e",
+ "bytes": 7078
},
"docs/architecture/architecture.md": {
"sha256": "d5a259bcfc07576eac4cea7a74036744a5320dec2d98e74debc53a1df47243c3",
"bytes": 22319
},
"docs/assurance/assurance-record.md": {
- "sha256": "2abb767ed00dbd4566797232766e2c75a062244cbcd7f2a51d0d2f5ccdbe4fee",
- "bytes": 7981
+ "sha256": "71d5308e71aa46f70dd1ac06cd99e19955ae63bafd3cea57355634924b3b8a7f",
+ "bytes": 8279
},
"docs/configuration/configuration-management.md": {
"sha256": "df65f3d26e003ab038b1a9f4df324ee2ae16b0c8fe05983b81626b6dcc902049",
@@ -491,17 +491,21 @@
"bytes": 23394
},
"docs/guides/SUM-MAP.md": {
- "sha256": "530b4ff3ea2288adaab39cf79a9945a2d10e20daa32e26c12af5b6ce4ff24879",
- "bytes": 4349
+ "sha256": "374d3bd14d81457b27bf2231509788cddd7f4851be9d325356a56099f558242a",
+ "bytes": 4416
},
"docs/guides/explanation/README.md": {
- "sha256": "1b0a9d5c76ca294abd7ce90c5938a524b055a0fd496c2d2c50dd2e2a13ccbfec",
- "bytes": 1124
+ "sha256": "432229f4a5645681892a52653665db6c838f312cf99b5b79dc92e820da246bd5",
+ "bytes": 1051
},
"docs/guides/explanation/endoforge-vendoring.md": {
"sha256": "c99bbc59dfb0054b163a47cc9656ac1f45915a4da3320b4e2759d4ed770960a6",
"bytes": 8168
},
+ "docs/guides/explanation/foundations-and-pins.md": {
+ "sha256": "20b9b80dbffff240e4b6caf06f38677c7a40ebca114ad19a9d937e5f8075a8a1",
+ "bytes": 3066
+ },
"docs/guides/explanation/limitations.md": {
"sha256": "6fb57a631468d14a4f08315127b326a08b6eff980751aef202ab5102f1965172",
"bytes": 4034
@@ -511,8 +515,24 @@
"bytes": 7321
},
"docs/guides/how-to/README.md": {
- "sha256": "f5afc41d142f89b43a4e58a5b5d19a35270dcd4c99baa6b28931eafb7806d060",
- "bytes": 1168
+ "sha256": "05a9051fb3b603dadbe67fd2507edd8ca435005abc9f382d97e6602c51f166da",
+ "bytes": 1048
+ },
+ "docs/guides/how-to/add-a-domain.md": {
+ "sha256": "2db40dba2a8b8921b41d54c874d1328c2652fbe149614a25309c7edb2b60c429",
+ "bytes": 2248
+ },
+ "docs/guides/how-to/approve-asks.md": {
+ "sha256": "252efe237343b8fde77f429587e2df1185ead8e291cc948245656cf3dcd8a28b",
+ "bytes": 4667
+ },
+ "docs/guides/how-to/define-bots.md": {
+ "sha256": "f0657bb1bfee699cf7782714493b70dcfd97e3ed3b8ef7cd8c67ad6dd50df2d5",
+ "bytes": 2634
+ },
+ "docs/guides/how-to/merge-train.md": {
+ "sha256": "57f342c9540af29378026196cdd67bd918a0aeff1c35e02d7fef2acdda95350f",
+ "bytes": 3363
},
"docs/guides/how-to/repin-endoforge.md": {
"sha256": "1532c7554e343aaea7702f3ebc24ba79efda1aa72ced1ffdb4da6bc56b1f9e0d",
@@ -522,6 +542,10 @@
"sha256": "2cf4d16896f4863d3949be5e6d0a352606d9782ba1ac79717d62c6c148215ce8",
"bytes": 5058
},
+ "docs/guides/how-to/use-a-real-model.md": {
+ "sha256": "47f525d28f2ef975f511adab6404dce51775eb669ab3c8f113bba968ce2e738d",
+ "bytes": 2613
+ },
"docs/guides/reference/README.md": {
"sha256": "982eab890a27ad79a7e77e1ae35e8e7f206a70b81f3938a40c3d5c5d368d7445",
"bytes": 1800
@@ -539,12 +563,12 @@
"bytes": 4218
},
"docs/guides/tutorials/README.md": {
- "sha256": "d25b7310bef8ff10f983f67a6c819abca21af13829d39c027580afcba5a5e76e",
- "bytes": 489
+ "sha256": "e3e7a578ad9a12704e226839c61d88aa2278a64e30c7771228517eee6f06e45b",
+ "bytes": 483
},
"docs/guides/tutorials/first-run.md": {
- "sha256": "e5ab29e2a4273b16620d255d618dfadaea6807f30b7d9fbc033d9638110b7d6c",
- "bytes": 7598
+ "sha256": "a0a8da3c25b2c71a7d06db1acacf07e1c4a55a37222f58090ae4f19fe21353d0",
+ "bytes": 7604
},
"docs/icd/icd-endoforge-pin.md": {
"sha256": "7602054207a725e24ef5c28153582ebdf09d3f89df5e82dac286f827f0147c06",
@@ -674,6 +698,10 @@
"sha256": "53e0fa163ca660558aa851da85531b768d607b5ab78eb397d26388b880120068",
"bytes": 11233
},
+ "docs/verification/measured-2026-11.md": {
+ "sha256": "cd511efbf24f009dc4b5b23f52e57183e92bf75d66f44fedb8838d793ac80965",
+ "bytes": 2137
+ },
"docs/verification/reports/STR-baseline.md": {
"sha256": "ee4b6dac41f93157e08f7fef790f6131ed79ad1293cfc2b508f297ebcebdf35a",
"bytes": 4756
@@ -2363,8 +2391,8 @@
"bytes": 1683
},
"tests/test_readme_tools.py": {
- "sha256": "08d4dbe078f5149ac4dd203131502b6bc69162cba16250487290a006297b9cc6",
- "bytes": 2928
+ "sha256": "d6d957c460d4090e908092f143a3239c02d3ff8d6cacae0e2e2856e7dda84ff4",
+ "bytes": 3327
},
"tests/test_refrigeration_conformance.py": {
"sha256": "fa09df1f83231ad3416c3f1725d53800e1f512a4756e4c328c7ce78b0a7b61b4",
@@ -2451,8 +2479,8 @@
"bytes": 6107
},
"tools/check_readme.py": {
- "sha256": "3263a319803a60a29c1086c5c3af09695f5653ab0000ca8d5a52612d572386eb",
- "bytes": 9987
+ "sha256": "2b829de8aa66f98795878d16b741bea66a8d68d24ccce859db737c3dc9c679f3",
+ "bytes": 10091
},
"tools/check_trace.py": {
"sha256": "621b54f7923fa1cdfb25b3b71f52798befba681f6dffd2df8fea9c60765f8196",
diff --git a/README.md b/README.md
index 7a6bc43..dc5b6ab 100644
--- a/README.md
+++ b/README.md
@@ -2,233 +2,179 @@
# Cstack
-Cstack: template for a bot fleet under one human approver (GPL-3.0-only)
-
-Project code name: **Mjölnir**, Thor's hammer. It covers Cstack and the [EndoForge](https://github.com/Akilleez-QA/endoforge) core it vendors.
+Cstack is a local-first system for building and running software with AI agents under your control. One control core owns every goal, decision, permission and piece of evidence. Domain packages called Foundations plug in to supply exact knowledge and checks. [EndoForge](https://github.com/Akilleez-QA/endoforge), its software engine, is meant to generate code that the core evaluates, then activates, keeps or throws away. Anything risky waits for one human to approve it.
[](LICENSE)
-## Status
+**What works today:** the control core with its approvals and hash-chained ledger; six Foundations wired through checked adapters; an MCP server that gives each agent its own governed session; and forge goals, where a model writes one program that is compiled in an EndoForge workcell and checked against a Foundation. **Not yet:** generated user interfaces, the activate, keep and dispose lifecycle for generated software, and EndoForge's parallel agents and code reuse. See [status and limitations](#status-and-limitations).
-Cstack is a template for running a fleet of AI bots under one human approver. Copy it, name your bots, plug in your own domains, and every action a bot takes goes through a control core that records goals, scoped authority and evidence.
+A *bot* here is an AI agent, such as a Claude Code or Codex session, that reaches Cstack over MCP (the Model Context Protocol), or a script that hands Cstack a JSON file. To use it, you fork it, list your bots in `aors/fleet.json` (one area of responsibility, or AOR, per bot), add your own tools, and point your agents at its MCP server. Leave the control core unchanged so upstream fixes merge cleanly.
-This is an early template; verify the configuration and capabilities you choose. There is no tagged release; `main` is the supported version.
+## Why
-Classification: self-assessed Class E analog under NPR 7150.2D, not safety-critical. Cstack is not NASA software and this is not a NASA compliance determination. Results are bounded observations, not engineering or safety approvals; see [limitations](docs/guides/explanation/limitations.md) and the [software management plan](docs/plan/software-management-plan.md).
+Letting AI agents build and run software is easy to start and hard to trust. You need to know what each agent did, why, with which code, and whether you said yes. Cstack puts one control core between the agents and the world, whether they call tools or generate code:
-## Quickstart
+- **A reason before every action.** A bot must state its goal, record the decision behind each call and say what result it expects, before anything runs. The core enforces that order.
+- **Risky actions wait for you.** Every call has an effect: `allow`, `ask` or `deny`. The bot registry marks sending, paying, posting, filing and deleting as `ask`, so a tool of that kind waits for you. Cstack shows you the exact request and runs it only if you say yes. Your yes is tied to that request's SHA-256 digest, so it can't be reused for a different one.
+- **A record of every step.** Each step is appended to a hash-chained log (the *ledger*), so you can check later what ran, with which code, under whose approval.
+- **Pinned domain tools.** Calculations and checks live in *Foundations*: small packages of domain tools whose every file is listed by hash. Cstack refuses to run a Foundation whose files have changed, and every result carries its evidence.
-Python 3.12 or newer and Node 22 or newer on Linux or macOS. The pinned numpy doesn't install on 3.11. The spawn counter in the test suite needs Linux.
+## See it work
-```sh
-python3 -m venv .venv && . .venv/bin/activate
-pip install -r requirements.txt -r ci/requirements.txt
-npm ci --prefix adapters/workcell-toolchain --ignore-scripts --no-audit --no-fund
-cp cstack.config.example.json cstack.config.json
-python -B cli.py < examples/scalar-and-negative.json
-python -B -m unittest discover -s tests
-bash ci/run-local.sh python links trace
-```
-
-## CLI approval
-
-Calls may add `"effect": "ask"`; omitted effects remain `allow`. Ask restricts every
-call of the same operation in that run. It cannot add a capability or grant.
+This example hands Cstack a JSON file that stands in for what a bot would send: a goal and one tool call marked `ask`. The tool only echoes its input; the point is the stop. Cstack shows you the exact request:
```sh
python -B cli.py --approver < examples/ask-approval.json
-python -B cli.py --approver=deny < examples/ask-approval.json
-python -B cli.py --approver=file:answers.json < examples/ask-approval.json
```
-Bare `--approver` prompts on the controlling terminal (`/dev/tty`) while stdin
-carries JSON. Type exactly `approve` to approve the displayed request. Without
-an approver, or without a usable terminal, ask is denied before dispatch.
-The host-owned answer file is a JSON object mapping exact request SHA-256 digests
-to `"approve"` or `"deny"`; an absent digest denies. Use `CapabilityRequest.sha256`
-to compute the digest, also shown in the terminal prompt. Never take this file
-or flag from tool output. Invalid files produce the structured driver error.
-A denial returns the normal result with `run_status: "stopped"` and no dispatch;
-it is not a tool outcome. Each invocation requires a new host approval record.
-
-## Run a goal
-
-A goal runs through the POODO core and comes back with a witnessed receipt:
-
-```sh
-CSTACK_STUB_TRANSPORT_SCRIPT=examples/forge/saturation-stub.json python -B cli.py < examples/forge/saturation-goal.json
+```text
+Approve decision-1 foundation_template.echo_observation goal=synthetic-template@1 sha256=60f2b7ba86e3bfcfa817c2635415523734ae0cc8ebfa51f39bde594fc3416bf7
+{"arguments": {"observation": "fixture reading 7"}, "capability_id": "foundation_template", "decision_id": "decision-1", ...}
+Type approve to allow: approve
```
-The core makes the decision under a host grant and witnesses it. EndoForge then runs in `IsolatePool` V8 workcells: a model transport returns source, the pinned AssemblyScript compiler builds it in the cell, the real gates and frozen evaluator judge it, and the kernel calls the Foundations it declared as in-process imports. The EndoForge ledger and the receipt name the decision, grant, compiler and Foundation versions.
-
-The command can run again, and each run gets its own task and candidate. A goal's decision binds one request: a different request under it is refused. Numbers in a goal can be decimal literals.
+Type anything other than `approve`, or leave out `--approver`, and the call is never dispatched: the result says `"run_status": "stopped"` and `"execution_certainty": "not_dispatched"`.
+
+After you approve, Cstack prints the run as one JSON document, and the same steps go into the ledger. Its `events` list is the whole story, in order. Each event carries its own hash and the hash of the one before it, so corruption or a careless edit shows up. Summarised from one run, with hashes shortened (approval ids and times differ, so your hashes will too):
+
+```text
+seq kind what hash prior
+1 proposal start_goal 7d40af3f9ccc
+2 decision phase pontificate -> observe 0eb7b34c42db 7d40af3f9ccc
+3 decision phase observe -> orient cbe281848503 0eb7b34c42db
+4 decision phase orient -> decide 843094c9c928 cbe281848503
+5 decision precommit (expected result) 6f949be0547e 843094c9c928
+6 decision phase decide -> orchestrate 32bed9851298 6f949be0547e
+7 decision approved by cli-owner 959c7c7b347d 32bed9851298
+8 action dispatch 7078c22c2df3 959c7c7b347d
+9 outcome observation_echoed 47d913b564b4 7078c22c2df3
+```
-The controller and both ledgers stay outside the cohort. A lost cell or supervisor is recorded as `outcome_unknown`, never as a pass, and isn't retried; a rerun then takes `python -B cli.py --resume DECISION_ID`. A lost controller is reconciled against the run ledger by the next run, which lists anything unresolved. A kernel can propose a decision only as data, through its host; the core accepts or refuses it. A run with a refusal records no pass.
+The phases come from [POODO](https://github.com/Akilleez-QA/poodo), a reasoning method in the style of the OODA loop (observe, orient, decide, act) with a step in front: *pontificate* (frame the problem), *observe*, *orient*, *decide*, then *orchestrate* (carry out the calls). To move to the next phase the agent sends a short checkpoint: its rationale, the sources it read and the options it weighed. (In the example they are pre-written in the JSON file.) A call can run only in the last phase, and only after its expected result is on record.
-This command uses the stub transport, which returns a recorded file. A real model transport goes behind the same `generate` function, selected only by `workcell.transport` in host configuration, and gets its full instructions in `prompt.text`.
+When a bot runs over MCP instead, its `execute` call returns `approval_pending` at once, without dispatching. Your answer is recorded in an approval store under the bot's state directory, from your own shell, never from the bot's process; the agent then calls `execute` again. See [approve ask calls](docs/guides/how-to/approve-asks.md), including a current limitation of the answering tool.
-`adapters/workcell/claude-transport.mjs` is a real transport. It runs `claude -p` on a Claude Code subscription login with no tools, no MCP servers, no settings, no session persistence and an environment that carries no API key variables, and it refuses a session that reports any of them. To use it, set `"transport": "adapters/workcell/claude-transport.mjs"` in `cstack.config.json` and run the goal without the stub variable:
+## How it works
-```sh
-python -B cli.py < examples/forge/saturation-goal.json
+```mermaid
+flowchart TD
+ B["Bot (over MCP)
or script (cli.py)"] -->|goal, decisions, calls| C["Control core
poodo_core/"]
+ C -->|allow| A["Adapter
adapters/"]
+ C -->|ask| H{"You:
approve?"}
+ H -->|yes| A
+ H -->|no| X["Stopped,
nothing dispatched"]
+ C -->|deny| X
+ A -->|files checked by hash| F["Foundation
domain tools"]
+ F --> R["Result with evidence"]
+ R --> L[("Hash-chained log")]
```
-`CSTACK_CLAUDE_MODEL` picks the model (default `opus`), `CSTACK_CLAUDE_COMMAND` the executable (default `claude`), `CSTACK_CLAUDE_CONFIG_DIR` an existing Claude config directory, and `CSTACK_CLAUDE_TIMEOUT_MS` the per-call limit (default 300000). The ledger records the proposer as `claude-code:`. `tools/check_readme.py` runs this command only where `claude auth status` reports a login, and reports it as skipped elsewhere. See [the wiring acceptance](docs/verification/wiring-acceptance.md), [the Foundation routes](docs/verification/foundation-routes.md) and [the interface](docs/icd/icd-endoforge.md).
-
-Workcells aren't an OS sandbox. Cgroup limits apply only where the host delegates them; the receipt says `cgroup: unavailable` where it doesn't.
-
-## What is inside
+A bot reaches Cstack in one of two ways. `cli.py` runs one JSON file to the end, as in the example. `tools/cstack_mcp.py` is an MCP server for one bot. Register it in your agent's MCP settings as a stdio server; most clients take an entry like this, with absolute paths to your clone:
-| Path | What |
-|---|---|
-| `poodo_core/`, `contracts/`, `schemas/` | The control core: goals, phases, authority grants, decisions, attempts and evidence receipts, with the JSON contracts they obey |
-| `adapters/`, `extensions/`, `bootstrap.py` | Capability ports: bounded stdio bridges from the core to each domain, registered once in `bootstrap.DOMAINS`, and the EndoForge workcell runtime in `adapters/workcell/` |
-| `aors/`, `tools/` | The bot layer: areas of responsibility per bot, AOR sessions over MCP, fleet mail, approvals, a witnessed ledger, and the merge train |
-| `foundations/` | Vendored Foundations: math research layer, film, refrigeration, robotics and the template to copy |
-| `reasoning/poodo` | The POODO reasoning method the core enforces |
-| `vendor/foundation-math-v014` | Foundation Math, byte-pinned |
-| `vendor/endoforge` | The EndoForge slice the workcells run, byte-pinned |
-| `vendor/foundation-engine-v020` | The Foundation Engine bridge, its schema and upstream manifest, pinned |
-| `ci/`, `.github/` | The local CI script and the GitHub workflow that calls it |
+```json
+{ "mcpServers": { "cstack-example": {
+ "command": "/path/to/cstack/.venv/bin/python",
+ "args": ["-B", "/path/to/cstack/tools/cstack_mcp.py", "--aor", "example", "--device", "example-host", "--state-root", "/tmp/cstack-state"] } } }
+```
-## Foundations
+`--device` names the machine, and `--state-root` is where this bot's ledger and your approvals live. The agent then gets six tools: `aor` (who am I), `start_goal`, `advance` (next phase, with its checkpoint), `decide` (record a call and its expected result), `execute` and `ledger`. Their descriptions walk the agent through the phases.
-A Foundation is a domain package that Cstack runs through an adapter. Some are vendored, meaning copied into this repository, and the rest are only linked.
+Cstack doesn't start your agents. Each agent connects to its own server; the shared registry, ledgers and approval channel are what make them one team. With `--fleet-mail`, bots can also leave each other messages. Either way, the core walks the goal through the POODO phases and applies each call's effect: `allow` runs it, `ask` waits for you, `deny` refuses it. Which bot may do what is set in `aors/fleet.json`, a file you own. Nothing in a request, a bot's output or a tool's reply can raise its own permissions.
-| Foundation | In this repository | How Cstack uses it |
-|---|---|---|
-| [foundation-math](https://github.com/Akilleez-QA/foundation-math) | `vendor/foundation-math-v014/`, plus the research layer in `foundations/math/` | Vendored copy of v0.14, run through `adapters/math_stdio.py` and `extensions/foundation_math.py` |
-| foundation-film | [`foundations/film/`](foundations/film/) | Vendored copy, byte-pinned |
-| foundation-refrigeration | [`foundations/refrigeration/`](foundations/refrigeration/) | Vendored copy, byte-pinned. Also an in-process kernel in workcells |
-| foundation-robotics | [`foundations/robotics/`](foundations/robotics/) | Vendored copy, byte-pinned |
-| foundation-template | [`foundations/template/`](foundations/template/) | Vendored copy, byte-pinned. Also an in-process kernel in workcells |
-| [foundation-engine](https://github.com/Akilleez-QA/foundation-engine) | `vendor/foundation-engine-v020/`, partial: bridge, schema and manifest | Two read-only validators, run through `adapters/engine_stdio.py` and `extensions/foundation_engine.py`. The engine's TypeScript runtime isn't included |
-| [endoforge](https://github.com/Akilleez-QA/endoforge) | [`vendor/endoforge/`](vendor/endoforge/), byte-pinned | Lifecycle, gates, ledger and `IsolatePool`, run through `adapters/endoforge_workcell.py` |
-| [poodo](https://github.com/Akilleez-QA/poodo) | `reasoning/poodo/` | Earlier snapshot of the skill that the core follows |
+An allowed call goes to an adapter. The adapter checks the Foundation's files against the hashes in `contracts/SOURCE-PINS.json`, starts it as a child process, validates the reply, and checks the files again. A tool result is recorded as an observation, never as proof that the goal is done.
-### How pins work
+## Install and run
-Cstack does not trust a vendored Foundation just because it is present. Each one ships a `SOURCE-MANIFEST.json` that lists a hash for every file. `contracts/SOURCE-PINS.json` records the expected hash of each manifest, and the adapters refuse to run a Foundation whose files or manifest don't match. To update a Foundation, copy in the new version, rebuild its manifest with `foundations//tools/build_manifest.py`, update the pin, and run all the test suites on a reviewed branch. EndoForge has its own tool; see [repin EndoForge](docs/guides/how-to/repin-endoforge.md). There is no automatic upgrade. The pin values are listed in [docs/icd/icd-foundations.md](docs/icd/icd-foundations.md). A matching pin proves that the bytes are unchanged. It does not prove that the content is correct.
+You need Linux or macOS, Python 3.12 or newer and `git`. Code-writing runs and the test suite also need Node 22 or newer and `npm`. No API key or model login is needed.
-## Verification
-
-Run the root and Foundation unittest suites normally and with optimization enabled. `python -B tools/check_readme.py` runs every command in this file on a fresh clone.
+```sh
+git clone https://github.com/Akilleez-QA/cstack
+cd cstack
+python3 -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt -r ci/requirements.txt
+npm ci --prefix adapters/workcell-toolchain --ignore-scripts --no-audit --no-fund
+cp cstack.config.example.json cstack.config.json
+```
-## Define your bots
+The `npm` step installs the pinned compiler for code-writing runs; the approval example runs without it. `ci/requirements.txt` adds what the test suites need. `cstack.config.json` holds your host settings: where the ledger is written and what a code-writing run may use. Now run the example above. To check your install, run the test suite, then the Python, link and trace checks that CI runs:
-1. Edit `aors/fleet.json`. Each bot has a `slug`, the `slices` of the repo it owns, what it does not own, and `effects`. Anything that sends, pays, posts, files or deletes is `ask`, which routes to the one human approver.
-2. Choose branch lanes for your own workflow.
-3. Validate your registry with `adapters.aor_registry.load_fleet` against `contracts/aor.schema.json`:
+```sh
+python -B -m unittest discover -s tests
+bash ci/run-local.sh python links trace
+```
- ```sh
- python -B -c "from adapters.aor_registry import load_fleet; print(load_fleet('aors/fleet.json').approver)"
- ```
+The [first-run tutorial](docs/guides/tutorials/first-run.md) walks through three runs and explains each step, in about ten minutes.
-4. Start a bot's AOR session over MCP. The host picks the bot and device; nothing a bot sends can change them:
+## What you can do with it
- ```sh
- python -B tools/cstack_mcp.py --aor example --device example-host --state-root /tmp/cstack-state
- ```
+| Task | Guide |
+|---|---|
+| Approve calls from a terminal or an answer file | [Approve ask calls](docs/guides/how-to/approve-asks.md) |
+| Name your bots, what they own and what needs your approval | [Define your bots](docs/guides/how-to/define-bots.md) |
+| Let a real model write forge code (Claude Code subscription login) | [Use a real model](docs/guides/how-to/use-a-real-model.md) |
+| Add your own domain tools | [Add a domain](docs/guides/how-to/add-a-domain.md) |
+| Coding bots open pull requests; land them in dependency order | [Run the merge train](docs/guides/how-to/merge-train.md) |
+| Run every check CI runs | [Run CI checks locally](docs/guides/how-to/run-ci-locally.md) |
-## Wire the merge train
+### Bots that write code
-`tools/merge_train.py` merges open PRs in dependency order. A PR merges only when its body lists the local checks that were run, it stays inside its bot's slice, and it merges cleanly. It never deletes branches or force-pushes. It needs `gh`, signed in, and a GitHub remote; without them it says so and exits 2, and `tools/check_readme.py` reports these two commands as skipped. Run it from a timer against a fresh worktree of `main`.
+Bots can also have code built for them. Cstack hands this *forge goal* to [EndoForge](https://github.com/Akilleez-QA/endoforge), the runtime where coding agents build real software: it finds, reuses or generates code, checks it inside fast V8-isolate workcells against an independent evaluator the code never saw, and records the result in a tamper-evident ledger so trusted code gets reused. Cstack vendors a pinned slice of EndoForge in `vendor/endoforge/` and runs one governed goal through its workcells; the code is checked against a Foundation's own answers on cases fixed before any code was written. This example replays a recorded model answer, so no model or account is needed:
```sh
-python3 tools/merge_train.py --wip
-python3 tools/merge_train.py --dry-run --policy low-risk
+CSTACK_STUB_TRANSPORT_SCRIPT=examples/forge/saturation-stub.json python -B cli.py < examples/forge/saturation-goal.json
```
-## Add a domain
-
-Copy `foundations/template`, rename it, add tools and their pins, and register it in `bootstrap.DOMAINS`. The refrigeration, film and robotics domains show three complete examples.
-
-## Not included
-
-No business data, no user or site data, and no engineering, safety or compliance determination. The example domains are references to learn from, not certified tools.
-
-## Measured
+It ends with `"assessment": "candidate_passed"` and a receipt naming the compiler (AssemblyScript 0.28.20), the Foundation version and every call the program made. The [tutorial](docs/guides/tutorials/first-run.md#5-run-a-forge-goal) walks through it, and [use a real model](docs/guides/how-to/use-a-real-model.md) switches to a real one.
-Measured on 2026-11-06 with Python 3.14.9 and Node 26.13.0 on Linux, at commit `e2efa37` of the unmerged draft stack, except where the table says otherwise. GitHub CI results are on the pull requests.
+## What's inside
-| Check | Command | Result |
-|---|---|---|
-| Core test suite on `main`, Python 3.12.14 and Node 26.13.0, 2026-11-08 | `python -B -m unittest discover -s tests`, at `e02a0c4` | 711 tests, OK, 3 skipped |
-| Every README command, on a fresh clone | `python -B tools/check_readme.py --source https://github.com/Akilleez-QA/cstack --branch harden-tools` | 16 commands, 0 failed, 0 uncovered, 0 skipped. The forge goal ran twice and passed both times |
-| Core test suite, optimized | `python -B -O -m unittest discover -s tests` | 663 tests, OK, 2 skipped |
-| Core test suite, Python 3.12.14 on two cores, normal and optimized | `taskset -c 0,1 python -B [-O] -m unittest discover -s tests`, at `7225ae9` | 663 tests, OK, 2 skipped, each |
-| Core test suite with the Film and Robotics ports, Python 3.12.14 and Node 26.13.0, normal and optimized | `python -B [-O] -m unittest discover -s tests`, at `66420c3` | 681 tests, OK, 2 skipped, each |
-| Film and Robotics ports against the pinned Python | `python -B tools/fuzz_ports.py --count 100000 --scan 2000000000 --cap 400 --libm 200000`, Python 3.12.14 | 0 disagreed over 224,043 vectors; 2,153 refused by the port alone. Details in [the routes](docs/verification/foundation-routes.md) |
-| Core test suite and all suites | `python -B -m unittest discover -s tests`, `bash ci/run-local.sh python links`, inside the check above | Both exit 0; 38 paths checked, 0 broken |
-| Secret scan | `bash ci/scan-secrets.sh` (TruffleHog) | 0 verified secrets; 2 unverified, in pip's vendored code in the untracked `.venv` |
-| Secret scan | `gitleaks git`, over the stack | No leaks |
-
-Foundation route numbers are in [the routes](docs/verification/foundation-routes.md), from their own run.
+| Path | What |
+|---|---|
+| `poodo_core/`, `contracts/`, `schemas/` | The control core: goals, phases, grants, decisions, attempts and receipts, and the JSON contracts they follow |
+| `adapters/`, `extensions/`, `bootstrap.py` | The code between the core and each Foundation: adapters start and check it, extensions list its tools for the core, and `bootstrap.py` registers each domain once. The workcell runtime is in `adapters/workcell/` |
+| `aors/`, `tools/` | The bot registry (AORs: each bot's area of responsibility), the MCP server, the approval channel and the merge train |
+| `foundations/`, `vendor/` | Pinned copies of the Foundations and EndoForge. See [Foundations and pins](docs/guides/explanation/foundations-and-pins.md) |
+| `reasoning/poodo/` | The POODO reasoning method the core enforces |
+| `cli.py`, `__main__.py`, `__init__.py` | Entry points, kept at the repository root on purpose |
+| `examples/`, `tests/`, `ci/` | Example runs, the test suite and the local CI script |
+
+## Status and limitations
+
+- Early template. There is no tagged release; `main` is the supported version.
+- The bundled tools are read-only calculations and checks. Tools with outside effects, such as sending email, are yours to add: as a Foundation, or as an external MCP tool server through `adapters/mcp_stdio_client.py`.
+- Workcells and Foundations run as child processes with deadlines and output limits. Neither is an OS sandbox for hostile code.
+- The ledger is written on one machine. A compromised machine can rewrite its own ledger before anyone else sees it; it is not an independent witness.
+- `tools/scheduled_approvals.py`, the owner's tool for answering a bot's asks, doesn't yet find asks in the per-domain ledger files that MCP sessions write. See [approve ask calls](docs/guides/how-to/approve-asks.md#answer-a-bots-asks).
+- A forge goal runs one model at a time. EndoForge's parallel coding agents and its caching are not wired in yet.
+- Results are observations, not engineering, safety or compliance approvals. See [limitations](docs/guides/explanation/limitations.md).
## Documentation
-- [Documentation index](docs/README.md): every document, by what you need.
-- [Tutorial: first run](docs/guides/tutorials/first-run.md): install and run three kinds of goal in about ten minutes.
-- How-to: [run CI checks locally](docs/guides/how-to/run-ci-locally.md), [repin EndoForge](docs/guides/how-to/repin-endoforge.md).
-- Reference: [commands](docs/guides/reference/commands.md), [configuration](docs/guides/reference/configuration.md), [environment variables](docs/guides/reference/environment.md).
-- Explanation: [how Cstack vendors and runs EndoForge](docs/guides/explanation/endoforge-vendoring.md), [the server, the driver and the adapters](docs/guides/explanation/server-and-adapters.md).
-- Engineering records: management plan, requirements, design, interfaces, data dictionary, test plan, verification matrix, test reports, configuration management and assurance record, all in [docs/](docs/README.md). `python -B tools/check_trace.py` checks the requirement-to-test trace.
-- [Limitations and safety-relevant use](docs/guides/explanation/limitations.md).
-- [Cstack family documentation standard](docs/standards/family-doc-standard.md): the canonical copy other family repositories link to.
-- [Code comment rule](docs/rules/no-comments.md).
-- [Control contracts](contracts/DECISION.md) and [capability contract](contracts/INTERFACES.md).
-
+The [documentation index](docs/README.md) is organised by what you want to do: learn, do a task, look something up, or understand the design. Good starting points: the [tutorial](docs/guides/tutorials/first-run.md), the [command reference](docs/guides/reference/commands.md) and [how the server, driver and adapters fit](docs/guides/explanation/server-and-adapters.md).
## Related projects
-| Repository | Role | Relation |
-|---|---|---|
-| [cstack](https://github.com/Akilleez-QA/cstack) | Runs Foundations behind pinned adapters under one human approver | Host |
-| [foundation-engine](https://github.com/Akilleez-QA/foundation-engine) | TypeScript and three.js framework for browser games | Foundation |
-| [foundation-math](https://github.com/Akilleez-QA/foundation-math) | Exact mathematical kernels and physics research tools | Foundation |
-| [foundation-film](foundations/film/) | Film-production acceptance checks | Foundation |
-| [foundation-refrigeration](foundations/refrigeration/) | Refrigeration data and checks | Foundation |
-| [foundation-robotics](foundations/robotics/) | Physics checks for motion | Foundation |
-| [foundation-template](foundations/template/) | Minimal Foundation to copy for a new domain | Foundation |
-| [endoforge](https://github.com/Akilleez-QA/endoforge) | Core engine for coding agents, checks, caching and evidence receipts | Execution substrate for forge goals, byte-pinned |
-| [poodo](https://github.com/Akilleez-QA/poodo) | Reasoning skill that shows evidence before it acts | Tool |
-
-Endoforge sits at the engine layer: forge goals run in its workcells with its gates and ledger. POODO runs on Endoforge as the control and reasoning layer (`poodo_core/`); domains and Foundations plug in through adapters. Foundations judge: a kernel's result is checked against the pinned Foundation, and producers don't grade themselves.
-
-POODO uses its Foundation adapters for execution and can route witnessed evidence through `EndoforgePort`. Configure `endoforge.path` in repository-local `cstack.config.json` (see `cstack.config.example.json`); its parent directory must exist. Configured CLI runs witness precommits before dispatch and outcomes after execution, fail closed on storage errors, and report `endoforge_implemented: true`. Unconfigured runs report false. Forge goals can run a real model through `adapters/workcell/claude-transport.mjs`; running many coding agents at once and EndoForge's caching aren't wired yet. See the [Endoforge interface status](docs/icd/icd-endoforge.md).
+Cstack is the host of the Cstack family (code name Mjölnir). The other projects plug into it.
-```mermaid
-flowchart TB
- P[POODO: control and reasoning] -->|EndoforgePort: witnessed evidence| E[Endoforge local ledger]
- P -->|decision, grant| R[Endoforge workcells: compile, gates, kernel]
- R -->|proposals as data, through the host| P
- R -->|receipts| L[Endoforge run ledger]
- R -->|declared imports, in process| K[Foundation kernels]
- P --> A[Domain extensions and adapters]
- A --> F[Foundations]
- K -.->|same pins, differential tests| F
-```
-
-## Layout
-
-| Path | Contents |
-|---|---|
-| `README.md` | Status, setup and entry points |
-| `docs/` | Requirements, architecture, interfaces, verification, configuration management and rules |
-| `examples/` | CLI input examples |
-| `tests/` | Root unittest suite |
-| `cli.py`, `bootstrap.py`, `__init__.py`, `__main__.py` | Python entry points and composition kept at the repository root |
-
-The root Python files stay at the top level on purpose.
+| Project | What it is | How Cstack uses it |
+|---|---|---|
+| [endoforge](https://github.com/Akilleez-QA/endoforge) | The runtime where coding agents build real software: finds, reuses or generates code, checks it in V8-isolate workcells against an independent evaluator, and records trusted results in a tamper-evident ledger | Runs forge goals; pinned copy in `vendor/endoforge/` |
+| [poodo](https://github.com/Akilleez-QA/poodo) | Reasoning skill that makes an agent show its evidence before it acts | The method the core enforces; snapshot in `reasoning/poodo/` |
+| [foundation-math](https://github.com/Akilleez-QA/foundation-math) | Exact mathematical kernels and certificate verifiers | Pinned copy in `vendor/foundation-math-v014/` |
+| [foundation-refrigeration](https://github.com/Akilleez-QA/foundation-refrigeration) | Refrigeration reference data and checks | Pinned copy in `foundations/refrigeration/` |
+| [foundation-film](https://github.com/Akilleez-QA/foundation-film) | Read-only film acceptance checks | Pinned copy in `foundations/film/` |
+| [foundation-robotics](https://github.com/Akilleez-QA/foundation-robotics) | Read-only physics checks for motion | Pinned copy in `foundations/robotics/` |
+| [foundation-template](https://github.com/Akilleez-QA/foundation-template) | Minimal Foundation to copy for a new domain | Pinned copy in `foundations/template/` |
+| [foundation-engine](https://github.com/Akilleez-QA/foundation-engine) | TypeScript and three.js engine for browser games | Two read-only validators; partial copy in `vendor/foundation-engine-v020/` |
-## Contributing
+## Engineering records
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and local checks.
+You don't need these to use Cstack. For reviewers: the requirements, design, interface documents, test plan, verification matrix and other control documents follow a layout adapted from NASA's software documentation standards, and are listed in the [documentation index](docs/README.md#engineering-records). `python -B tools/check_trace.py` checks that every requirement traces to a test. Test results are in the generated [test report](docs/verification/reports/STR-baseline.md), which names the commit it ran at; older measurements are kept, with their commits, in [measurements, November 2026](docs/verification/measured-2026-11.md).
-## Security
+Classification: self-assessed Class E analog under NPR 7150.2D, not safety-critical. Cstack is not NASA software and this is not a NASA compliance determination. See the [software management plan](docs/plan/software-management-plan.md).
-See [SECURITY.md](SECURITY.md) for the security contact and reporting guidance.
+## Contributing, security and license
-## License
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and local checks, and [SECURITY.md](SECURITY.md) to report a vulnerability.
-This project is available under the GNU General Public License v3.0 only (GPL-3.0-only). If you want to use it to create a product or service under different terms, commercial licenses are available from Refrigeration.AI. Contact craig@nh3.biz.
+Cstack is available under the GNU General Public License v3.0 only (GPL-3.0-only). If you want to use it to create a product or service under different terms, commercial licenses are available from Refrigeration.AI. Contact craig@nh3.biz.
diff --git a/docs/README.md b/docs/README.md
index d08f07b..7cfccf3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,23 +1,55 @@
# Documentation
-Cstack's documents, by what you need. The guides follow [Diátaxis](https://diataxis.fr/): tutorials teach, how-to guides solve a task, reference states facts, explanation gives background. The control documents follow the [Cstack family documentation standard](standards/family-doc-standard.md), whose canonical copy lives here.
+Find what you need by what you want to do. New here? Start with the [README](../README.md), then the tutorial.
-Control documents carry their own baseline commits. Reading or indexing them does not create a new verification result. Classification: self-assessed Class E analog, not safety-critical; this is not a NASA compliance determination or certification (see the [software management plan](plan/software-management-plan.md#1-software-classification-self-assessed)).
+## Learn
-## Start here
+| You will | Start with |
+|---|---|
+| Install Cstack and run a Foundation call, an approval and a forge goal, in about ten minutes | [Tutorial: first run](guides/tutorials/first-run.md) |
+
+## Do a task
+
+| Task | Guide |
+|---|---|
+| Approve calls marked `ask`, on a terminal or from a file | [Approve ask calls](guides/how-to/approve-asks.md) |
+| Name your bots and what needs your approval | [Define your bots](guides/how-to/define-bots.md) |
+| Let a real model write forge code | [Use a real model](guides/how-to/use-a-real-model.md) |
+| Add your own domain tools | [Add a domain](guides/how-to/add-a-domain.md) |
+| Merge bot pull requests in dependency order | [Run the merge train](guides/how-to/merge-train.md) |
+| Run the checks CI runs, before a pull request | [Run CI checks locally](guides/how-to/run-ci-locally.md) |
+| Move to a newer EndoForge | [Repin EndoForge](guides/how-to/repin-endoforge.md) |
+| Everything else | [All how-to guides](guides/how-to/README.md) |
+
+## Look something up
+
+| Need | Reference |
+|---|---|
+| A `cli.py` option, a tool in `tools/`, an error code | [Commands](guides/reference/commands.md) |
+| A key in `cstack.config.json` | [Configuration](guides/reference/configuration.md) |
+| An environment variable | [Environment variables](guides/reference/environment.md) |
+| The core's records, lanes, ask and deny, budgets | [Interfaces](../contracts/INTERFACES.md) |
+| Every reference page | [Reference index](guides/reference/README.md) |
-| Need | Start with |
+## Understand the design
+
+| Question | Read |
|---|---|
-| Install Cstack and run your first goals | [Tutorial: first run](guides/tutorials/first-run.md) |
-| Run the CI checks before a pull request | [How to run CI checks locally](guides/how-to/run-ci-locally.md) |
-| Move to a newer EndoForge | [How to repin EndoForge](guides/how-to/repin-endoforge.md) |
-| Other tasks: bots, merge train, domains | [How-to guides](guides/how-to/README.md) |
-| Look up a command, config key or environment variable | [Reference](guides/reference/README.md) |
-| Understand how EndoForge, the server and the adapters fit | [Explanation](guides/explanation/README.md) |
-| Know what results mean and what Cstack does not do | [Limitations and safety-relevant use](guides/explanation/limitations.md) |
-| Find where each user-manual topic lives | [User manual map](guides/SUM-MAP.md) |
+| How do the CLI, the MCP server and the adapters fit together? | [The server, the driver and the adapters](guides/explanation/server-and-adapters.md) |
+| Why is EndoForge a pinned copy, and how does a forge goal run? | [How Cstack vendors and runs EndoForge](guides/explanation/endoforge-vendoring.md) |
+| Which Foundations ship here, and what does a pin prove? | [Foundations and pins](guides/explanation/foundations-and-pins.md) |
+| What do results mean, and what does Cstack not do? | [Limitations and safety-relevant use](guides/explanation/limitations.md) |
+| What are the core's rules? | [Control decisions](../contracts/DECISION.md) and the [design](architecture/architecture.md) |
+
+The guides follow [Diátaxis](https://diataxis.fr/): tutorials teach, how-to guides solve a task, reference states facts, explanation gives background. The [user manual map](guides/SUM-MAP.md) shows where each user-manual topic lives.
+
+## Engineering records
+
+Cstack keeps a control document set organised after NASA's software documentation standards. The documents follow the [Cstack family documentation standard](standards/family-doc-standard.md), whose canonical copy lives here. Each carries its own baseline commit; reading or indexing them does not create a new verification result.
+
+Classification: self-assessed Class E analog under NPR 7150.2D, not safety-critical. Cstack is not NASA software, and this is not a NASA compliance determination or certification (see the [software management plan](plan/software-management-plan.md#1-software-classification-self-assessed)).
-## Control documents
+### Control documents
| Document | ID | SWEHB | Path |
|---|---|---|---|
@@ -41,7 +73,7 @@ Control documents carry their own baseline commits. Reading or indexing them doe
Not applicable (rationale in the SMP and the standard): training plan (5.15), safety plan (5.18), assurance status report (5.19), IV&V plan (5.20), hazard report (5.24; the limitations page stands in).
-## Verification records
+### Verification records
These are measurement and acceptance records kept as written.
@@ -49,8 +81,9 @@ These are measurement and acceptance records kept as written.
|---|---|
| [Foundation routes](verification/foundation-routes.md) | Measured routes from a workcell into each Foundation (2026-11-06) |
| [Wiring acceptance](verification/wiring-acceptance.md) | The acceptance frozen before end-to-end wiring (historical) |
+| [Measurements, November 2026](verification/measured-2026-11.md) | The README's former "Measured" table (historical) |
-## Family standard
+### Family standard
| Document | Use |
|---|---|
@@ -64,6 +97,6 @@ Decision records and contracts live in [`contracts/`](../contracts/): [ADR 001](
## Repository layout exception
-Python entry points and composition files (`cli.py`, `bootstrap.py`, `__init__.py` and `__main__.py`) remain at the repository root. See the [repository layout](../README.md#layout). The documentation directories do not change those import paths.
+Python entry points and composition files (`cli.py`, `bootstrap.py`, `__init__.py` and `__main__.py`) remain at the repository root. See [what's inside](../README.md#whats-inside). The documentation directories do not change those import paths.
See [Contributing](../CONTRIBUTING.md) for the review workflow and local checks, [Security](../SECURITY.md) for reporting guidance and [Support](../SUPPORT.md) for help.
diff --git a/docs/assurance/assurance-record.md b/docs/assurance/assurance-record.md
index 48036bb..8a17a8e 100644
--- a/docs/assurance/assurance-record.md
+++ b/docs/assurance/assurance-record.md
@@ -66,7 +66,7 @@ Rolling record of requirements, design, testing, code-quality and configuration
| F-4 | S4 | `ci/requirements.txt` installs pillow and numpy for a hillclimb pixel-diff script under a `forge/` directory that does not exist in this repository; no tracked Python file imports either package | `ci/requirements.txt` | Not filed | Open |
| F-5 | S4 | `tools/check_links.py` scans `forge/endoforge/docs/*.md` and its docstring describes that area; the path does not exist | `tools/check_links.py` | Not filed | Open |
| F-6 | S4 | Operator tools have no tests: `tools/agent_profiles.py`, `tools/generate_aors.py`, `tools/measure_foundation_routes.py`, `tools/measure_routes_pyodide.mjs`, `tools/tty_approve.py`, `tools/gen_release_docs.py` | SDD-C23 | Not filed | Open; recorded as infrastructure |
-| F-7 | S4 | The README "Measured" table cites runs at older commits and an unmerged branch; it is not regenerated | `README.md` | Not filed | Open |
+| F-7 | S4 | The README "Measured" table cites runs at older commits and an unmerged branch; it is not regenerated | `README.md` | Not filed | Closed 2026-11-10 (PR #80): the table left the README, which now points to the generated [STR-baseline](../verification/reports/STR-baseline.md); the old figures are kept in [measured-2026-11](../verification/measured-2026-11.md), each tied to a commit on `main`, and the row with no commit was removed |
| F-8 | Observation | No branch protection on `main`; CI results are not required to merge | GitHub settings | - | Recorded |
### Overall assessment
diff --git a/docs/guides/SUM-MAP.md b/docs/guides/SUM-MAP.md
index 42c5e67..4985c98 100644
--- a/docs/guides/SUM-MAP.md
+++ b/docs/guides/SUM-MAP.md
@@ -17,14 +17,14 @@ Cstack has no single user manual. Its content (SWEHB 5.12) is spread over the RE
| SUM element | Where | Verified how |
|---|---|---|
-| Application summary and intended users | [README Status](../../README.md#status) | Read against code at baseline |
-| Inventory (what is shipped) | [README Layout](../../README.md#layout), [README Related projects](../../README.md#related-projects); [version descriptions](../releases/README.md) | VDD generated by `tools/gen_release_docs.py` |
-| Environment and prerequisites | [README Quickstart](../../README.md#quickstart); [environment variables](reference/environment.md) | README commands run by `tools/check_readme.py` (TP-5) |
+| Application summary and intended users | [README](../../README.md), [Status and limitations](../../README.md#status-and-limitations) | Read against code at baseline |
+| Inventory (what is shipped) | [README What's inside](../../README.md#whats-inside), [README Related projects](../../README.md#related-projects); [version descriptions](../releases/README.md) | VDD generated by `tools/gen_release_docs.py` |
+| Environment and prerequisites | [README Install and run](../../README.md#install-and-run); [environment variables](reference/environment.md) | README commands run by `tools/check_readme.py` (TP-5) |
| Modes and states of operation | [Server, driver and adapters](explanation/server-and-adapters.md); [EndoForge vendoring](explanation/endoforge-vendoring.md); goal phases in [`contracts/INTERFACES.md`](../../contracts/INTERFACES.md) | Inspection |
| Security and privacy | [SECURITY.md](../../SECURITY.md); [limitations](explanation/limitations.md#misuse-and-security-considerations) | Inspection |
| Assistance and problem reporting | [SUPPORT.md](../../SUPPORT.md); [problem report](../../.github/ISSUE_TEMPLATE/problem-report.md) and [change request](../../.github/ISSUE_TEMPLATE/change-request.md) templates | Inspection |
| First-time use | [Tutorial: first run](tutorials/first-run.md) | TP-2, last run 2026-11-08 (PR #74) |
-| Starting and stopping a run | [Commands reference](reference/commands.md); [README CLI approval](../../README.md#cli-approval) | Covered by `tests/test_process_and_cli.py` and the tutorial |
+| Starting and stopping a run | [Commands reference](reference/commands.md); [Approve ask calls](how-to/approve-asks.md) | Covered by `tests/test_process_and_cli.py` and the tutorial |
| Capabilities and commands reference | [Commands](reference/commands.md); [data dictionary](../data/data-dictionary.md) tool tables | Tool tables generated from `schemas/` |
| Conventions (IDs, units, file layout) | [Configuration reference](reference/configuration.md); [data dictionary](../data/data-dictionary.md) | Generated from schemas and config |
| Processing procedures | [How-to guides](how-to/README.md) | Repin guide reproduced the vendor tree at PR #74 |
diff --git a/docs/guides/explanation/README.md b/docs/guides/explanation/README.md
index d29bd0e..af85899 100644
--- a/docs/guides/explanation/README.md
+++ b/docs/guides/explanation/README.md
@@ -7,9 +7,8 @@ Background that helps you reason about Cstack. These pages say why, not how-to.
| [How Cstack vendors and runs EndoForge](endoforge-vendoring.md) | Why EndoForge is a pinned copy, what the slice holds, and how a forge goal crosses from the core to the workcells and back |
| [The server, the driver and the adapters](server-and-adapters.md) | The CLI driver, the MCP server for bot sessions, the capability adapters and what the host keeps |
| [Architecture](../../architecture/architecture.md) | Control-core composition and the Foundation boundary |
-| [Foundations](../../../README.md#foundations) | Which Foundations are vendored, which are linked, and how pins work |
+| [Foundations and pins](foundations-and-pins.md) | Which Foundations ship here and why Cstack refuses one whose files changed |
| [Control decisions](../../../contracts/DECISION.md) | The core's invariants and capability model, and the later decision records beside it |
-| [Not included](../../../README.md#not-included) | The example domains' limits |
| [Limitations and safety-relevant use](limitations.md) | What results mean, what Cstack does not do, and how not to use it |
Return to the [documentation index](../../README.md).
diff --git a/docs/guides/explanation/foundations-and-pins.md b/docs/guides/explanation/foundations-and-pins.md
new file mode 100644
index 0000000..c71eec7
--- /dev/null
+++ b/docs/guides/explanation/foundations-and-pins.md
@@ -0,0 +1,24 @@
+# Foundations and pins
+
+A Foundation is a domain package, such as exact math or refrigeration data, that Cstack runs through an adapter. This page explains which Foundations ship in this repository and why Cstack refuses to run one whose files have changed.
+
+## Which Foundations ship here
+
+Most Foundations are vendored, meaning copied into this repository and pinned by hash. Each has its own upstream repository.
+
+| Foundation | In this repository | How Cstack uses it |
+|---|---|---|
+| [foundation-math](https://github.com/Akilleez-QA/foundation-math) | `vendor/foundation-math-v014/`, plus the research layer in `foundations/math/` | Vendored copy of v0.14, run through `adapters/math_stdio.py` and `extensions/foundation_math.py` |
+| [foundation-film](https://github.com/Akilleez-QA/foundation-film) | [`foundations/film/`](../../../foundations/film/) | Vendored copy, byte-pinned |
+| [foundation-refrigeration](https://github.com/Akilleez-QA/foundation-refrigeration) | [`foundations/refrigeration/`](../../../foundations/refrigeration/) | Vendored copy, byte-pinned. Also an in-process kernel in workcells |
+| [foundation-robotics](https://github.com/Akilleez-QA/foundation-robotics) | [`foundations/robotics/`](../../../foundations/robotics/) | Vendored copy, byte-pinned |
+| [foundation-template](https://github.com/Akilleez-QA/foundation-template) | [`foundations/template/`](../../../foundations/template/) | Vendored copy, byte-pinned. Also an in-process kernel in workcells |
+| [foundation-engine](https://github.com/Akilleez-QA/foundation-engine) | `vendor/foundation-engine-v020/`, partial: bridge, schema and manifest | Two read-only validators, run through `adapters/engine_stdio.py` and `extensions/foundation_engine.py`. The engine's TypeScript runtime isn't included |
+| [endoforge](https://github.com/Akilleez-QA/endoforge) | [`vendor/endoforge/`](../../../vendor/endoforge/), byte-pinned | Lifecycle, gates, ledger and `IsolatePool`, run through `adapters/endoforge_workcell.py` |
+| [poodo](https://github.com/Akilleez-QA/poodo) | `reasoning/poodo/` | Partial copy of the skill that the core follows; the synced files and their upstream commit are listed in `contracts/SOURCE-PINS.json` |
+
+## How pins work
+
+Cstack does not trust a vendored Foundation just because it is present. Each one ships a `SOURCE-MANIFEST.json` that lists a hash for every file. `contracts/SOURCE-PINS.json` records the expected hash of each manifest, and the adapters refuse to run a Foundation whose files or manifest don't match. To update a Foundation, copy in the new version, rebuild its manifest with `foundations//tools/build_manifest.py`, update the pin, and run all the test suites on a reviewed branch. EndoForge has its own tool; see [repin EndoForge](../how-to/repin-endoforge.md). There is no automatic upgrade. The pin values are listed in [docs/icd/icd-foundations.md](../../icd/icd-foundations.md). A matching pin proves that the bytes are unchanged. It does not prove that the content is correct.
+
+Return to the [explanation index](README.md).
diff --git a/docs/guides/how-to/README.md b/docs/guides/how-to/README.md
index f6288af..cdedba6 100644
--- a/docs/guides/how-to/README.md
+++ b/docs/guides/how-to/README.md
@@ -4,13 +4,13 @@ Task recipes. Each assumes a working clone; the [tutorial](../tutorials/first-ru
| Task | Guide |
|---|---|
+| Approve calls marked `ask`, on a terminal or from a file | [Approve ask calls](approve-asks.md) |
+| Name your bots, their slices and effects, validate the registry and start a bot's session | [Define your bots](define-bots.md) |
+| Let a real model write forge code | [Use a real model](use-a-real-model.md) |
+| Add a domain from the Template Foundation | [Add a domain](add-a-domain.md) |
+| Merge open PRs in dependency order | [Run the merge train](merge-train.md) |
| Run the checks CI runs, before a pull request | [Run CI checks locally](run-ci-locally.md) |
| Move `vendor/endoforge/` to a newer EndoForge commit | [Repin EndoForge](repin-endoforge.md) |
-| Name your bots, their slices and effects, and validate the registry | [Define your bots](../../../README.md#define-your-bots) |
-| Start one bot's AOR session over MCP | [Define your bots](../../../README.md#define-your-bots), step 4, and [the server explanation](../explanation/server-and-adapters.md) |
-| Merge open PRs in dependency order | [Wire the merge train](../../../README.md#wire-the-merge-train) |
-| Use a real model for forge goals | [Run a goal](../../../README.md#run-a-goal) |
-| Add a domain from the Template Foundation | [Add a domain](../../../README.md#add-a-domain) |
| Update a vendored Foundation | [Change procedure](../../configuration/configuration-management.md#change-procedure) |
| Contribute a change | [Contributing](../../../CONTRIBUTING.md) |
diff --git a/docs/guides/how-to/add-a-domain.md b/docs/guides/how-to/add-a-domain.md
new file mode 100644
index 0000000..e96ddb0
--- /dev/null
+++ b/docs/guides/how-to/add-a-domain.md
@@ -0,0 +1,28 @@
+# How to add a domain
+
+A domain is a set of tools the core can call, packaged as a Foundation and reached through an adapter. Cstack ships a Template Foundation to copy. The refrigeration, film and robotics domains are three complete worked examples; read their files beside these steps.
+
+## The pieces
+
+| Piece | Copy from | What it does |
+|---|---|---|
+| `foundations//` | `foundations/template/` | The Foundation: its tools, a stdio JSON-RPC bridge, tests and a `SOURCE-MANIFEST.json` of file hashes |
+| `schemas/-v01-tools.json` | `schemas/template-v01-tools.json` | The pinned tool catalog the adapter checks the live bridge against |
+| `adapters/_stdio.py` | `adapters/template_stdio.py` | A profile on `adapters/foundation_stdio.py`: source hash, file count, protocol, bridge module and boundary |
+| `extensions/foundation_.py` | `extensions/foundation_template.py` | The domain extension the core binds |
+| A row in `contracts/ADAPTERS.json` | the `foundation-template-stdio` row | The adapter's identity and lane. `bootstrap.check_grants` refuses a grant that doesn't match it |
+| An entry in `contracts/SOURCE-PINS.json` | the `foundation_template` entry | The expected manifest hash |
+| A `register(Domain(...))` call in `bootstrap.py` | the `foundation_template` call | Adds the domain to `bootstrap.DOMAINS`, the one registry |
+
+## Steps
+
+1. Copy `foundations/template` to `foundations/` and rename its packages.
+2. Replace the placeholder tool with your own. Each result should carry a receipt and Evidence, as the template's do.
+3. Rebuild its manifest with `foundations//tools/build_manifest.py`, then add the pin.
+4. Add the schema, adapter, extension and inventory row from the table.
+5. Register the domain in `bootstrap.py`.
+6. Run every suite, on a reviewed branch: [run CI checks locally](run-ci-locally.md).
+
+A pin proves that the bytes are unchanged. It doesn't prove the content is correct, so your Foundation's own tests matter. [Foundations and pins](../explanation/foundations-and-pins.md) explains the checks, and [the server, the driver and the adapters](../explanation/server-and-adapters.md) explains what each adapter does at run time.
+
+Return to the [how-to guides](README.md).
diff --git a/docs/guides/how-to/approve-asks.md b/docs/guides/how-to/approve-asks.md
new file mode 100644
index 0000000..6a75df2
--- /dev/null
+++ b/docs/guides/how-to/approve-asks.md
@@ -0,0 +1,64 @@
+# How to approve ask calls
+
+A call marked `"effect": "ask"` runs only after a human approves it. This guide shows the three ways to answer from the command line. It assumes a working clone; the [tutorial](../tutorials/first-run.md) sets one up.
+
+## Mark a call as ask
+
+In a run document, add `"effect": "ask"` next to the call's `request`. A call without `effect` is `allow`. Once one call of an operation is `ask`, every call of that operation in the same run asks too. `ask` can't add a capability or a grant; it only adds a stop. See [`examples/ask-approval.json`](../../../examples/ask-approval.json).
+
+## Answer on the terminal
+
+```sh
+python -B cli.py --approver < examples/ask-approval.json
+```
+
+Stdin carries the JSON, so the prompt goes to the controlling terminal (`/dev/tty`):
+
+```text
+Approve decision-1 foundation_template.echo_observation goal=synthetic-template@1 sha256=60f2b7ba86e3bfcfa817c2635415523734ae0cc8ebfa51f39bde594fc3416bf7
+{"arguments": {"observation": "fixture reading 7"}, "capability_id": "foundation_template", "decision_id": "decision-1", ...}
+Type approve to allow:
+```
+
+Type exactly `approve`. Any other answer declines. Without a usable terminal the ask is declined before anything is dispatched.
+
+## Decline everything
+
+```sh
+python -B cli.py --approver=deny < examples/ask-approval.json
+```
+
+The result has `"run_status": "stopped"` and `"stopped": {"execution_certainty": "not_dispatched", ...}`. A denial is a normal result, not a tool outcome.
+
+## Answer from a file
+
+An answer file is a JSON object that maps the SHA-256 digest of each exact request to `"approve"` or `"deny"`. A request whose digest is missing is denied. The digest is the one shown in the terminal prompt; compute it with `CapabilityRequest.sha256`:
+
+```sh
+python -B -c "import json; from poodo_core import CapabilityRequest; d=json.load(open('examples/ask-approval.json')); print(json.dumps({CapabilityRequest.from_dict(d['calls'][0]['request']).sha256: 'approve'}))" > answers.json
+python -B cli.py --approver=file:answers.json < examples/ask-approval.json
+```
+
+An invalid file produces the structured driver error `invalid_or_unsupported_request`.
+
+## Rules that keep approval yours
+
+- An answer file is a standing approval. Keep it owned by you, and never take the file or the `--approver` flag from tool output.
+- Each run records a new approval and consumes it once. The consumed markers go under `$XDG_STATE_HOME/cstack/cli-approvals` (default `~/.local/state/cstack/cli-approvals`).
+- A file that starts with the SQLite header is read as an approval store instead. See `--approver` in the [command reference](../reference/commands.md#clipy-the-local-run-driver).
+
+## Answer a bot's asks
+
+A bot running over MCP doesn't use these flags. When it calls `execute` on an `ask` decision, the call returns `{"status": "approval_pending", "dispatched": false, ...}` at once and waits as an `approval_pending` event in its ledger under the session's `--state-root`. After you answer yes, the bot calls `execute` again. You answer from your own shell with `tools/scheduled_approvals.py`:
+
+```text
+python -B tools/scheduled_approvals.py brief --state-root DIR
+python -B tools/scheduled_approvals.py pending --state-root DIR [--json | --full DECISION_ID]
+python -B tools/scheduled_approvals.py answer DECISION_ID yes|no --sha256 HEX --state-root DIR
+```
+
+**Current limitation (found 2026-11-08).** With a witnessed ledger configured, a session writes one ledger file per domain, at `//.jsonl`, where `` is the node log path from `ledger.json` without its `.jsonl` suffix. `scheduled_approvals.py` reads only the single node log named in `ledger.json`, so it reports `Approvals: nothing waiting on you.` and `answer` refuses with `is not pending in any readable ledger`, even while the bot waits. Until that is fixed, the approval can be written only through `adapters.approval_store.ApprovalWriter`, as `tests/test_mcp_driving_adapter.py` does. Without a witnessed ledger the session's ledger is memory only, and no other process can see its asks.
+
+When the channel does see an ask, an answer must quote the request digest you were shown (`--sha256`). A yes expires after `--ttl` seconds (default 3600). It is recorded once in `approvals.db` under the state root. The tool refuses to run inside a bot's MCP server process. Its own docstring states the trust limit: any process running as the same OS user can write that database, so real separation needs the approval channel on its own OS user or device. See [the server, the driver and the adapters](../explanation/server-and-adapters.md).
+
+Return to the [how-to guides](README.md).
diff --git a/docs/guides/how-to/define-bots.md b/docs/guides/how-to/define-bots.md
new file mode 100644
index 0000000..9394f0c
--- /dev/null
+++ b/docs/guides/how-to/define-bots.md
@@ -0,0 +1,52 @@
+# How to define your bots
+
+Each bot in Cstack has an area of responsibility (AOR): what it owns, what it doesn't, which parts of the repository it may write, and which effects need your approval. The registry is one host-owned file, `aors/fleet.json`. This guide changes it and starts one bot's session.
+
+## 1. Edit the registry
+
+Copy the example entry in `aors/fleet.json` and set, for each bot:
+
+| Field | Meaning |
+|---|---|
+| `slug` | Short name, used on the command line |
+| `owns`, `not` | What the bot is and isn't responsible for, in words |
+| `slices` | The repository paths it may write |
+| `effects` | One of `allow`, `ask` or `deny` for each effect class: `read`, `write_slice`, `execute`, `config`, `send`, `payment`, `post`, `filing`, `delete` |
+| `reports_to` | The bot it reports to, or `null` |
+
+Keep every external effect (`send`, `payment`, `post`, `filing`, `delete`) at `ask`, so it routes to the one human approver. The example bot does:
+
+```json
+"effects": { "read": "allow", "write_slice": "deny", "execute": "allow", "config": "allow",
+ "send": "ask", "payment": "ask", "post": "ask", "filing": "ask", "delete": "ask" }
+```
+
+Choose branch lanes that fit your own workflow; the registry doesn't fix them.
+
+## 2. Validate it
+
+```sh
+python -B -c "from adapters.aor_registry import load_fleet; print(load_fleet('aors/fleet.json').approver)"
+```
+
+```text
+owner-via-approver
+```
+
+This checks the file against `contracts/aor.schema.json`. Loading the registry grants nothing by itself; `bootstrap.py` derives each session's authority from it.
+
+## 3. Start a bot's session
+
+```sh
+python -B tools/cstack_mcp.py --aor example --device example-host --state-root /tmp/cstack-state
+```
+
+This starts an MCP server on stdin and stdout for one bot. Point your agent's MCP client configuration at this command. The host picks the bot (`--aor`) and the device; nothing the bot sends can change them. Asked who it is (the `aor` tool), the session answers with the registry entry (trimmed):
+
+```text
+{"approver": "owner-via-approver", "bot": {"id": "00000001", "name": "Example", "slug": "example"}, "device": "example-host", ..., "ledger": "memory (not durable: no ADR 004 roster configured)", ...}
+```
+
+The ledger is memory only until you configure a witnessed ledger under `--state-root`. [The server, the driver and the adapters](../explanation/server-and-adapters.md) explains the tool table, how effects resolve and where state lives. `tools/agent_profiles.py` generates MCP wiring and one agent profile per bot; see the [command reference](../reference/commands.md).
+
+Return to the [how-to guides](README.md).
diff --git a/docs/guides/how-to/merge-train.md b/docs/guides/how-to/merge-train.md
new file mode 100644
index 0000000..e093a65
--- /dev/null
+++ b/docs/guides/how-to/merge-train.md
@@ -0,0 +1,64 @@
+# How to run the merge train
+
+`tools/merge_train.py` merges open pull requests in dependency order. It is meant to run from a timer against a fresh worktree of `main`, so bots' pull requests land without a human merging each one.
+
+It works in passes: pull requests based on `main` first, then each merged pull request's children, retargeted to `main`. A pull request merges only when:
+
+- it is not a draft,
+- its branch's first segment is a bot slug from `aors/fleet.json` or a lane in aors/branch-slugs.json (a lane list the tool reads if present). This check applies only when both files exist; this repository ships no lane list, so it is off until you add one,
+- its branch and files are in scope (see below),
+- its body lists the local checks that were run,
+- it passes the policy: with `--policy low-risk`, every file must be Markdown or under `docs/`, and none under `contracts/`, and
+- GitHub reports it as mergeable, with no conflicts with `main`.
+
+It squash-merges, never deletes branches and never force-pushes.
+
+## What the train will merge without review
+
+Scope depends on the branch name. This is `in_scope()` in `tools/merge_train.py`:
+
+| Branch | Merged by the train when | Always left for review |
+|---|---|---|
+| `worker/*` | every file is under `examples/` or `docs/` (including `examples/interface/*`) | Any file outside `examples/` and `docs/` |
+| `coordinator/*` | no file is under the four paths on the right | `poodo_core/`, `adapters/`, `contracts/`, `examples/interface/*` |
+| Any other branch | never | Everything |
+
+Coordinator branches are trusted more than worker branches. With the default `--policy all`, the train merges a coordinator pull request that changes `tools/`, `tests/`, `bootstrap.py`, `cli.py`, `extensions/`, `vendor/`, `.github/` (including the CI workflow) or `foundations/`, without review. Only `poodo_core/`, `adapters/` and `contracts/` are left for review on every branch.
+
+If you run the train unattended and want those paths reviewed, run it with `--policy low-risk`, which merges only Markdown and `docs/` changes, or keep `coordinator/*` branches for work you have already reviewed. The tool's own docstring says `tools` and `tests` are never merged by the train; for coordinator branches the code above is what applies. Its docstring also lists `examples/interface/*`, but a `worker/*` branch that changes only files there is in scope, because `examples/` is an iteration path.
+
+## What you need
+
+`gh` installed and signed in, and a GitHub remote. Without them the tool says so and exits 2.
+
+## Run it
+
+Count open pull requests per lane against the work-in-progress limit (10):
+
+```sh
+python3 tools/merge_train.py --wip
+```
+
+```text
+ 1 docs
+```
+
+Plan a run without merging anything, limited to low-risk pull requests:
+
+```sh
+python3 tools/merge_train.py --dry-run --policy low-risk
+```
+
+```text
+{
+ "merged": [],
+ "retargeted": [],
+ "skipped": {
+ "80": "out of scope (platform core or other bot)"
+ }
+}
+```
+
+The dry run prints what it would do, as JSON. Here the only open pull request is on a `docs/` branch, which is neither `worker/*` nor `coordinator/*`, so it is out of scope. Drop `--dry-run` to merge. Other options are in the [command reference](../reference/commands.md): `--policy` is `all` (default) or `low-risk`, and `--max-passes` defaults to 12.
+
+Return to the [how-to guides](README.md).
diff --git a/docs/guides/how-to/use-a-real-model.md b/docs/guides/how-to/use-a-real-model.md
new file mode 100644
index 0000000..4b96e0f
--- /dev/null
+++ b/docs/guides/how-to/use-a-real-model.md
@@ -0,0 +1,51 @@
+# How to use a real model for forge goals
+
+A forge goal asks a model transport for source code, compiles it in an EndoForge workcell and checks it. The examples use the stub transport, which replays a recorded answer. This guide switches to a real model.
+
+## What you need
+
+- A working clone with `cstack.config.json` (see the [tutorial](../tutorials/first-run.md)).
+- Claude Code installed, with a subscription login: `claude auth status` reports `"loggedIn": true`. No API key is used.
+
+## 1. Point the host configuration at the Claude transport
+
+In `cstack.config.json`, set:
+
+```json
+"transport": "adapters/workcell/claude-transport.mjs"
+```
+
+The transport is chosen only by `workcell.transport` in host configuration. Request data can't choose it.
+
+## 2. Run the goal without the stub
+
+```sh
+python -B cli.py < examples/forge/saturation-goal.json
+```
+
+The transport runs `claude -p` with no tools, no MCP servers, no settings, no session persistence and an environment that carries no API key variables. It refuses a session that reports any of them. The model gets its full instructions in `prompt.text`. The ledger records the proposer as `claude-code:`.
+
+## Settings
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CSTACK_CLAUDE_MODEL` | `opus` | The model |
+| `CSTACK_CLAUDE_COMMAND` | `claude` | The executable |
+| `CSTACK_CLAUDE_CONFIG_DIR` | none | An existing Claude config directory |
+| `CSTACK_CLAUDE_TIMEOUT_MS` | `300000` | The per-call limit |
+
+The [environment reference](../reference/environment.md) lists every variable.
+
+## What happens on failure
+
+- Each run gets its own task and candidate, so you can run the same goal again.
+- A goal's decision binds one request. A different request under the same decision is refused.
+- A lost workcell or supervisor is recorded as `outcome_unknown`, never as a pass, and isn't retried. Rerun it with `python -B cli.py --resume DECISION_ID`.
+- A lost controller is reconciled against the run ledger by the next run, which lists anything unresolved.
+- A kernel can propose a decision only as data, through its host; the core accepts or refuses it. A run with a refusal records no pass.
+
+Workcells aren't an OS sandbox. Cgroup limits apply only where the host delegates them; the receipt says `cgroup: unavailable` where it doesn't.
+
+`tools/check_readme.py` runs this goal only where `claude auth status` reports a login, and reports it as skipped elsewhere. See [how Cstack vendors and runs EndoForge](../explanation/endoforge-vendoring.md) and [the EndoForge interface](../../icd/icd-endoforge.md).
+
+Return to the [how-to guides](README.md).
diff --git a/docs/guides/tutorials/README.md b/docs/guides/tutorials/README.md
index 7807547..28bf454 100644
--- a/docs/guides/tutorials/README.md
+++ b/docs/guides/tutorials/README.md
@@ -6,6 +6,6 @@ Lessons that start from nothing and end with something working.
|---|---|
| [Run your first goals on a fresh clone](first-run.md) | Install Cstack, run a Foundation call, approve an ask, and run a forge goal through EndoForge workcells. About ten minutes, no model login needed |
-The README [Quickstart](../../../README.md#quickstart) is the same setup and the CI checks as a bare command list.
+The README's [Install and run](../../../README.md#install-and-run) is the same setup as a bare command list.
Return to the [documentation index](../../README.md).
diff --git a/docs/guides/tutorials/first-run.md b/docs/guides/tutorials/first-run.md
index eb0b66a..a1fa947 100644
--- a/docs/guides/tutorials/first-run.md
+++ b/docs/guides/tutorials/first-run.md
@@ -136,6 +136,6 @@ Keep `cstack.config.json` if you want to carry on. It is ignored by git.
## Where next
- Run the checks CI runs: [run CI checks locally](../how-to/run-ci-locally.md).
-- Use a real model: set `workcell.transport` to `adapters/workcell/claude-transport.mjs`, as the [README](../../../README.md#run-a-goal) describes.
+- Use a real model: set `workcell.transport` to `adapters/workcell/claude-transport.mjs`, as [use a real model](../how-to/use-a-real-model.md) describes.
- Understand what you just ran: [how Cstack vendors and runs EndoForge](../explanation/endoforge-vendoring.md).
- Look up a flag, key or variable: [reference](../reference/README.md).
diff --git a/docs/verification/measured-2026-11.md b/docs/verification/measured-2026-11.md
new file mode 100644
index 0000000..efea322
--- /dev/null
+++ b/docs/verification/measured-2026-11.md
@@ -0,0 +1,18 @@
+# Measurements, November 2026
+
+This table was the "Measured" section of the README until 2026-11-08. It is a historical record, not a current result. Current test results are in the generated [test report](reports/STR-baseline.md), which names its commit and environment.
+
+Measured on 2026-11-06 with Python 3.14.9 and Node 26.13.0 on Linux, at commit `e2efa37`, except where the table names another commit. Every commit named here is on `main`. One row was removed on 2026-11-10 (assurance finding F-7): a fresh-clone run of `tools/check_readme.py` against the `harden-tools` branch, which recorded no commit, so its result can't be tied to `main`. GitHub CI results are on the pull requests.
+
+| Check | Command | Result |
+|---|---|---|
+| Core test suite on `main`, Python 3.12.14 and Node 26.13.0, 2026-11-08 | `python -B -m unittest discover -s tests`, at `e02a0c4` | 711 tests, OK, 3 skipped |
+| Core test suite, optimized | `python -B -O -m unittest discover -s tests` | 663 tests, OK, 2 skipped |
+| Core test suite, Python 3.12.14 on two cores, normal and optimized | `taskset -c 0,1 python -B [-O] -m unittest discover -s tests`, at `7225ae9` | 663 tests, OK, 2 skipped, each |
+| Core test suite with the Film and Robotics ports, Python 3.12.14 and Node 26.13.0, normal and optimized | `python -B [-O] -m unittest discover -s tests`, at `66420c3` | 681 tests, OK, 2 skipped, each |
+| Film and Robotics ports against the pinned Python | `python -B tools/fuzz_ports.py --count 100000 --scan 2000000000 --cap 400 --libm 200000`, Python 3.12.14 | 0 disagreed over 224,043 vectors; 2,153 refused by the port alone. Details in [the routes](foundation-routes.md) |
+| Core test suite and all suites | `python -B -m unittest discover -s tests`, `bash ci/run-local.sh python links`, inside the check above | Both exit 0; 38 paths checked, 0 broken |
+| Secret scan | `bash ci/scan-secrets.sh` (TruffleHog) | 0 verified secrets; 2 unverified, in pip's vendored code in the untracked `.venv` |
+| Secret scan | `gitleaks git`, over the stack | No leaks |
+
+Foundation route numbers are in [the routes](foundation-routes.md), from their own run.
diff --git a/tests/test_readme_tools.py b/tests/test_readme_tools.py
index f6272a5..fceb515 100644
--- a/tests/test_readme_tools.py
+++ b/tests/test_readme_tools.py
@@ -22,6 +22,12 @@ def test_gh_commands_are_a_separate_group(self):
if "merge_train" in command:
self.assertIn(command, check_readme.NEEDS_GH)
+ def test_every_readme_command_has_a_check(self):
+ source = (ROOT / "tools/check_readme.py").read_text()
+ done_by_checker = getattr(check_readme, "DONE_BY_CHECKER", ())
+ for command in check_readme.readme_commands((ROOT / "README.md").read_text()):
+ self.assertTrue(command in done_by_checker or json.dumps(command) in source or repr(command) in source, command)
+
def test_without_gh_the_group_is_skipped_with_a_clear_reason(self):
reason = check_readme.gh_unavailable({"PATH": "/nonexistent"})
self.assertIn("gh", reason)
diff --git a/tools/check_readme.py b/tools/check_readme.py
index 4716e18..f634598 100644
--- a/tools/check_readme.py
+++ b/tools/check_readme.py
@@ -14,6 +14,7 @@
FORGE_RUNS = 2
NEEDS_GH = ("python3 tools/merge_train.py --wip", "python3 tools/merge_train.py --dry-run --policy low-risk")
REAL_FORGE = "python -B cli.py < examples/forge/saturation-goal.json"
+DONE_BY_CHECKER = ("git clone https://github.com/Akilleez-QA/cstack", "cd cstack")
STUB_TRANSPORT, CLAUDE_TRANSPORT = '"adapters/workcell/stub-transport.mjs"', '"adapters/workcell/claude-transport.mjs"'
@@ -115,7 +116,7 @@ def main():
subprocess.run(["git", "clone", "--quiet", *(["--branch", args.branch] if args.branch else []), args.source, str(clone)], check=True)
subprocess.run(["git", "remote", "set-url", "origin", args.github_remote], cwd=clone, check=True)
commands = readme_commands((clone / "README.md").read_text())
- covered = set()
+ covered = set(DONE_BY_CHECKER)
check = Check(clone, covered)
check.plain("python3 -m venv .venv && . .venv/bin/activate")
check.plain("pip install -r requirements.txt -r ci/requirements.txt")
@@ -123,7 +124,7 @@ def main():
check.plain("cp cstack.config.example.json cstack.config.json")
check.run_status("python -B cli.py < examples/scalar-and-negative.json", "completed")
check.plain("python -B -m unittest discover -s tests", timeout=1800)
- check.plain("bash ci/run-local.sh python links", timeout=3600)
+ check.plain("bash ci/run-local.sh python links trace", timeout=3600)
approve_on_tty(check, "python -B cli.py --approver < examples/ask-approval.json")
check.run_status("python -B cli.py --approver=deny < examples/ask-approval.json", "stopped")
request = subprocess.run([sys.executable, "-B", "-c", "import json,sys; sys.path.insert(0,'.'); from poodo_core import CapabilityRequest; d=json.load(open('examples/ask-approval.json')); print(CapabilityRequest.from_dict(d['calls'][0]['request']).sha256)"],