@b00dea/cockpit 0.1.0 → 0.1.1

package/docs/command-list.md

@@ -8,8 +8,11 @@ This generated index is for users choosing the command that owns their next oper
 
 - `cockpit init`: Preview, then accept, a first cockpit setup for one or more agent tools.
 - `cockpit setup`: Clone or locate the declared sibling repositories and link them.
+- `cockpit use`: Serve a sibling from another of its checkouts, such as a worktree.
+- `cockpit pull`: Fast-forward the cockpit and its siblings to their upstreams.
 - `cockpit sibling`: Add or remove a repository in cockpit.toml (sibling add, sibling remove).
 - `cockpit tool`: Add or remove an agent tool in cockpit.toml (tool add, tool remove).
+- `cockpit confirm`: Confirm an init answer no person stated by running the observation that verifies it.
 - `cockpit registry-resolve`: Turn a validated shell registry into data shell scripts can source.
 - `cockpit upgrade`: Move the exact cockpit pin to a newer version and re-run sync.
 
@@ -26,9 +29,14 @@ This generated index is for users choosing the command that owns their next oper
 - `cockpit preflight`: Check that the environment is healthy and ready for work.
 - `cockpit session`: Keep the environment available for one command, then release it.
 - `cockpit logs`: Show recent logs for one declared service.
+- `cockpit ps`: Show the state and health of each service in this checkout's stack.
+- `cockpit restart`: Restart one service of this checkout's stack and wait until it is healthy.
+- `cockpit rebuild`: Rebuild one service's image, replace its container and wait until it is healthy.
+- `cockpit exec`: Run a command inside one service's container of this checkout's stack.
 - `cockpit sleep`: Release this checkout and stop the stack if no other holder remains.
 - `cockpit down`: Stop and remove the stack (on the active local Docker context).
 - `cockpit reset`: Preview a reset, then approve it interactively or apply it as [autonomy] reset allows (on the active local Docker context).
+- `cockpit stacks`: List every stack on this machine, or preview and remove those whose checkout is gone (stacks prune).
 
 ## Diagnose
 
@@ -40,8 +48,10 @@ This generated index is for users choosing the command that owns their next oper
 - `cockpit work status`: Report each work order, its state and how it closed.
 - `cockpit work accept`: Accept a work order, or a change to an accepted one, as [work.gates] allows.
 - `cockpit work check`: Run every criterion's check and the order's gates.
-- `cockpit work note`: Record a note on an order, or with --ask an open question that blocks it.
+- `cockpit work note`: Record a note on an order, an open question with --ask, or a decision with --decision.
+- `cockpit work decide`: Resolve a recorded decision: write or cite its decision record, or say it is not lasting.
 - `cockpit work answer`: Answer an open question on an order, as [work.gates] allows.
+- `cockpit work acknowledge`: Acknowledge that an order weakened tests, as [work.gates] allows.
 - `cockpit work grade`: Grade an accepted order the way [work] grading says.
 - `cockpit work signoff`: Close a graded order as done, or any open one as partial or abandoned.
 - `cockpit work recover`: Inspect or remove a crashed command's work-order lock.
@@ -49,3 +59,4 @@ This generated index is for users choosing the command that owns their next oper
 - `cockpit grade`: Independently grade uncommitted work against a criteria file, with no work order.
 - `cockpit browser drive`: Drive the declared application browser surfaces.
 - `cockpit browser screenshot`: Capture the declared application surfaces.
+- `cockpit docs check`: Report removed paths and make targets living docs still cite, and broken decision records.

package/docs/concepts.md

@@ -68,10 +68,12 @@ holds its schema and limits.
 ### Evaluator
 
 The grader for a finished work order under the default `independent` grading. It grades each
-acceptance criterion against the checks cockpit ran and the change since the order was accepted, in a
-fresh read-only run that never sees the session that did the work, in another listed agent tool when
-one is available, otherwise the same tool in a new run. It never edits code. A cockpit can instead let the
-checks alone decide, or let the agent report its own verdict; the record says which.
+acceptance criterion, and the standing criteria cockpit adds (changes outside scope, flagged test
+changes, the agent's amendments), against the checks cockpit ran and the change since the order was
+accepted, in a fresh read-only run that never sees the session that did the work, in another listed
+agent tool when one is available, otherwise the same tool in a new run. It never edits code. A cockpit
+can instead let the checks alone decide, or let the agent report its own verdict; the record says
+which.
 
 ### Enforced, instructed, generated and unavailable
 

package/docs/configuration-essentials.md

@@ -22,7 +22,8 @@ siblings_root = ".."
 ## `[[sibling]]`
 
 One table per product repository. `mount` says how the stack uses the checkout: `always`
-bind-mounts it, `profile:<name>` mounts it only under that Compose profile, `none` leaves it read
+bind-mounts it, `profile:<name>` mounts it only while that Compose profile is active
+([Compose profiles](environment.md#compose-profiles)), `none` leaves it read
 but never mounted, and `host` runs it outside the stack for the reason given in `host_reason`.
 `acquire` says how it reaches disk: `auto` clones `remote` during `setup`, `manual` expects a
 person to clone it, and `none` never clones it, so it must already be there. The two are
@@ -90,12 +91,15 @@ as written ([Compose-first stacks](environment.md#compose-first-stacks)). A smal
 Compose file gets a starting one from `cockpit init --scaffold-compose`
 ([Scaffold a Compose file](environment.md#scaffold-a-compose-file)). `resettable_volumes` names the
 Compose volumes `reset` may delete, and `seed` the command `up` runs to fill them
-([Demo data, test users and roles](environment.md#demo-data-test-users-and-roles)). Full entry:
+([Demo data, test users and roles](environment.md#demo-data-test-users-and-roles)). `profiles`
+names the Compose profiles every `up` activates; `up --profile <name>` adds one for a run
+([Compose profiles](environment.md#compose-profiles)). Full entry:
 [`[environment]`](configuration-reference.md#environment).
 
 ```toml
 [environment]
 compose_files = ["compose.yml"]
+profiles = ["workers"]
 resettable_volumes = ["postgres-data"]
 seed = { argv = ["npm", "run", "db:seed"], timeout_seconds = 300 }
 ```
@@ -170,3 +174,4 @@ reference also lists the [defaults](configuration-reference.md#defaults) and the
 | MCP approvals | [`[mcp]`](configuration-reference.md#mcp) | [MCP servers and restrictions](harness-surfaces.md#mcp-servers-and-restrictions) |
 | Surface overlays | [`[[surfaces.overlays]]`](configuration-reference.md#surfacesoverlays) | [Ownership and extension](harness-surfaces.md#ownership-and-extension) |
 | Custom harnesses | [`[[surfaces.harnesses]]`](configuration-reference.md#surfacesharnesses) | [Custom harnesses](harness-surfaces.md#custom-harnesses) |
+| Living documents and decision records | [`[docs]`](configuration-reference.md#docs) | [Check living documents and decision records](docs-check.md) |

package/docs/configuration-reference.md

@@ -54,6 +54,7 @@ The values cockpit uses for a key the configuration leaves out.
     "resettable_volumes": [],
     "generated_host_paths": [],
     "compose_files": [],
+    "profiles": [],
     "entrypoint_derivatives": [],
     "install_policies": []
   },
@@ -91,6 +92,7 @@ Each section is one TOML table: `[name]` holds one, `[[name]]` repeats. A table
 | `testing` | Test stages and gates. | table: [`[testing]`](#testing) |  |  |
 | `environment` | How the stack is reached, signed in to, built and kept. | table: [`[environment]`](#environment) | `{}` |  |
 | `surfaces` | Instructions, skills and settings generated for agent tools. | table: [`[surfaces]`](#surfaces) | `{}` |  |
+| `docs` | Living documents and decision records: docs check keeps them true, and work orders record their decisions there. | table: [`[docs]`](#docs) |  |  |
 
 ### `[cockpit]`
 
@@ -118,6 +120,7 @@ Each section is one TOML table: `[name]` holds one, `[[name]]` repeats. A table
 | `instruction_pointer` | Let setup add a pointer to the cockpit guide in this sibling, when the command line also approves it. | boolean | `false` |  |
 | `purpose` | What the sibling is for; printed when its checkout is missing. | string |  | required; at least 1 character |
 | `environment_files` | Template and instance environment file pairs the sibling needs. | array of table: [`[[sibling.environment_files]]`](#siblingenvironment_files) |  |  |
+| `rebuild_inputs` | Files or directories in the sibling, beyond its lockfiles, whose change leaves a running stack stale, such as a migrations directory. | array of string |  | at most 64 items; each item: pattern [P1](#patterns) |
 | `derives` | Facts about the sibling that cockpit derives rows or MCP servers from. | table: [`[sibling.derives]`](#siblingderives) |  |  |
 
 - Must match `{"oneOf":[{"properties":{"acquire":{"enum":["none"]}},"not":{"required":["remote"]}},{"properties":{"acquire":{"enum":["auto","manual"]}},"required":["remote"]}]}`.
@@ -209,9 +212,10 @@ Each section is one TOML table: `[name]` holds one, `[[name]]` repeats. A table
 | Key | Meaning | Type | Default | Constraints |
 | --- | --- | --- | --- | --- |
 | `accept` | Who accepts a draft work order: agent, person or ci. Default agent. | string |  | one of `"agent"`, `"person"`, `"ci"` |
-| `amend` | Who accepts a changed contract. Default agent. Removing or rewriting an accepted criterion always needs a person or ci. | string |  | one of `"agent"`, `"person"`, `"ci"` |
+| `amend` | Who accepts a changed contract. Default agent. Removing an accepted criterion or gate always needs a person or ci; an agent's rewrite of a criterion, scope, non-goal or objective is judged at the next grade, and needs a person under checks grading. | string |  | one of `"agent"`, `"person"`, `"ci"` |
 | `answer` | Who answers an open question on an order. Default agent. | string |  | one of `"agent"`, `"person"`, `"ci"` |
 | `signoff` | Who closes a graded order. Default agent. | string |  | one of `"agent"`, `"person"`, `"ci"` |
+| `acknowledge` | Who acknowledges that an order weakened tests, which checks grading otherwise fails; under independent and self grading the acknowledgement is context for the verdict. Default agent. | string |  | one of `"agent"`, `"person"`, `"ci"` |
 
 ### `[autonomy]`
 
@@ -238,7 +242,7 @@ Each section is one TOML table: `[name]` holds one, `[[name]]` repeats. A table
 | `resolver` | Fixed host name to address mappings the browser uses. | array of table: [`[[browser.resolver]]`](#browserresolver) | `[]` | at most 64 items |
 | `authentication` | How browser sessions sign in to the application. | table: [`[browser.authentication]`](#browserauthentication) |  | required |
 | `data` | Statement about the data the browser touches; cockpit cannot observe it. | table: [`[browser.data]`](#browserdata) |  | required |
-| `request_preapproval` | Run browser tools without prompts; allowed only on isolated, non-production, non-restored data. | boolean | `false` |  |
+| `request_preapproval` | Run browser tools without prompts; allowed only on isolated, non-production, non-restored data. Defaults to true when data qualifies and false otherwise. | boolean |  |  |
 | `artifacts` | Generated host paths for browser output. | table: [`[browser.artifacts]`](#browserartifacts) |  | required |
 
 - Must match at least one of `[{"properties":{"request_preapproval":{"enum":[false]}}},{"properties":{"data":{"required":["mode","isolated","reaches_production"],"properties":{"mode":{"enum":["empty","seeded"]},"isolated":{"enum":[true]},"reaches_production":{"enum":[false]}}}}}]`.
@@ -324,6 +328,7 @@ Each section is one TOML table: `[name]` holds one, `[[name]]` repeats. A table
 
 | Key | Meaning | Type | Default | Constraints |
 | --- | --- | --- | --- | --- |
+| `test_files` | Paths and globs, relative to each checkout, that hold tests. Grading fails an order that deletes, skips or loosens what they match. Defaults to common layouts. | array of string |  | 1–64 items; each item: pattern `^(?!\/)(?!.*(?:^\|\/)\.\.(?:\/\|$))[A-Za-z0-9._@+\-/*?]+$`, 1–512 characters |
 | `stages` | Commands that make up the test gates. | array of table: [`[[testing.stages]]`](#testingstages) |  | required; 1–128 items |
 | `gates` | Named gates that run stages before handing back changes. | array of table: [`[[testing.gates]]`](#testinggates) |  | required; 1–128 items |
 | `native_hooks` | How the repository's own git hooks are handled. | table: [`[testing.native_hooks]`](#testingnative_hooks) | `{"install":"inspect"}` |  |
@@ -383,6 +388,7 @@ Each section is one TOML table: `[name]` holds one, `[[name]]` repeats. A table
 | `resettable_volumes` | Compose volumes that reset may delete and recreate, named by their Compose key. | array of string | `[]` | unique items; each item: pattern `^[a-z0-9][a-z0-9_.-]*$` |
 | `generated_host_paths` | Host paths cockpit generates and owns, relative to the cockpit. | array of string | `[]` | unique items; each item: pattern [P1](#patterns) |
 | `compose_files` | Compose files, relative to the cockpit, that make up the stack; cockpit runs them as written. | array of string | `[]` | unique items; each item: pattern [P1](#patterns), pattern `^[^:]+$` |
+| `profiles` | Compose profiles every up and session activates; up --profile adds more for one run. | array of string | `[]` | at most 64 items; each item: pattern `^[a-z0-9][a-z0-9_.-]*$`, at most 64 characters |
 | `entrypoint_derivatives` | Addresses derived from leased ports, such as application origins and callback URLs. | array of table: [`[[environment.entrypoint_derivatives]]`](#environmententrypoint_derivatives) | `[]` |  |
 | `install_policies` | The build and test commands the guard admits for each toolchain and lockfile. | array of table: [`[[environment.install_policies]]`](#environmentinstall_policies) | `[]` |  |
 | `seed` | Command up runs once the stack is healthy, whenever a resettable volume was created since the last successful seed. | table: [`[environment.seed]`](#environmentseed) |  |  |
@@ -523,6 +529,14 @@ Each section is one TOML table: `[name]` holds one, `[[name]]` repeats. A table
 | `adopted_on` | Date the file was adopted. | string |  | required; format `date`; pattern [P2](#patterns) |
 | `provenance` | Where the adoption came from; its kind must be declared. | table: [`provenance` shape](#provenance-shape) |  | required |
 
+### `[docs]`
+
+| Key | Meaning | Type | Default | Constraints |
+| --- | --- | --- | --- | --- |
+| `living` | Globs of the Markdown documents that must stay true; docs check reports the paths and make targets they cite that the repository has since removed. | array of string | `[]` | at most 64 items; each item: pattern `^(?!(?:[a-z0-9][a-z0-9-]{0,63}:)?(?:.*\/)?\.\.(?:\/\|$))(?:[a-z0-9][a-z0-9-]{0,63}:)?(?![/])[A-Za-z0-9._@+\-/*?]+$`, at most 1024 characters |
+| `decisions` | Directory of decision records, such as docs/adr. Work orders record their lasting decisions there, and docs check reports duplicate numbers, missing statuses and broken supersedes links. | string |  | pattern [P7](#patterns); at most 1024 characters |
+| `decisions_index` | Index file that links every decision record; a record cockpit writes is appended to it, and docs check reports records it omits and links to records that do not exist. | string |  | pattern [P7](#patterns); at most 1024 characters |
+
 ## Shapes
 
 These tables recur in several places; each place links here instead of repeating the keys.
@@ -558,6 +572,7 @@ Long patterns that several keys share, cited by name in the tables.
 | P4 | `^[^\x00-\x1f\x7f-\x9f\uD800-\uDFFF]{1,128}(?![\s\S])` |
 | P5 | `^(?:0\|[1-9]\d*)\.(?:0\|[1-9]\d*)\.(?:0\|[1-9]\d*)(?:-(?:0\|[1-9]\d*\|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0\|[1-9]\d*\|\d*[A-Za-z-][0-9A-Za-z-]*))*)?$` |
 | P6 | `^(?!.*(?:^\|\/)(?:\.git\|internal\|node_modules)(?:\/\|$)).+$` |
+| P7 | `^(?!(?:[a-z0-9][a-z0-9-]{0,63}:)?(?:.*\/)?\.\.?(?:\/\|$))(?:[a-z0-9][a-z0-9-]{0,63}:)?(?![/])[A-Za-z0-9._@+\-/]*[A-Za-z0-9._@+-]$` |
 
 ## Checks beyond the schema
 
@@ -616,6 +631,6 @@ Agent tools load every skill's frontmatter into each session and its entry point
 | `packages/cockpit/surfaces/skills/cockpit-fix.skill.md` | lines | 12 | `packages/cockpit/surfaces/skills/procedures/fix.md` |
 | `packages/cockpit/surfaces/skills/cockpit-work.skill.md` | lines | 9 | `packages/cockpit/surfaces/skills/procedures/work.md` |
 
-Each procedure is read on demand and has no size limit: `packages/cockpit/surfaces/skills/procedures/setup.md` (SHA-256 `0ef32e4d7d2304d5f9b150a59e90edbd825159386d89ee0ea19fe5142c06e366`), `packages/cockpit/surfaces/skills/procedures/explain.md` (SHA-256 `dce839b290d2a584fc5592c895c20425414e9201a4c35c2460ff0539d545f2bb`), `packages/cockpit/surfaces/skills/procedures/fix.md` (SHA-256 `a91365d5a79404d506e95a7d7a64fa50460dfc842265d1040402185767f527af`) and `packages/cockpit/surfaces/skills/procedures/work.md` (SHA-256 `b3e6b8de3a249e73e65f84624c991416933086308073ff979f10632aae988791`).
+Each procedure is read on demand and has no size limit: `packages/cockpit/surfaces/skills/procedures/setup.md` (SHA-256 `f8aa06a781db377ce38e34517f64a523f631e9c6122a13073e38cba46f1d7a0e`), `packages/cockpit/surfaces/skills/procedures/explain.md` (SHA-256 `3055cd5929e13266151a1f5657e6ed6a0d9f2a43545770bda5a0dbe6b9a2c0f9`), `packages/cockpit/surfaces/skills/procedures/fix.md` (SHA-256 `ccb7c2e0c568d0a218c1c4bd8cdb31e5fad67e65df5018b73fe71207b0b555aa`) and `packages/cockpit/surfaces/skills/procedures/work.md` (SHA-256 `037ac35ad0c49202a19a6ee7a65104a9ed052917ac4fb3e15d4f49127103ba20`).
 
 <!-- cockpit:ref schema=cockpit.guide_cap --> `cockpit.guide_cap` limits always-loaded guidance to 200 lines by default. The measured cost depends on each configuration's sibling guides, so it is not listed here.

package/docs/docs-check.md

@@ -0,0 +1,76 @@
+# Check living documents and decision records
+
+`cockpit docs check` reports documents that have drifted from the repositories they describe: a
+living document that still cites a path or `make` target the repository has removed, and a
+decision-record set whose numbers, index, statuses or supersedes links no longer agree. It reads
+files and runs read-only Git; it changes nothing.
+
+## Declare what to check
+
+<!-- cockpit:ref schema=docs.living --> List the documents that must stay true under `[docs]` in
+`cockpit.toml`. Each entry is a glob in the cockpit's own repository, or `<sibling slug>:<glob>` in
+a sibling, spelt as a work order's scope is. `decisions` and `decisions_index` are optional and
+name a directory of decision records and the file that links them. Full entry:
+[`[docs]`](configuration-reference.md#docs).
+
+```toml
+[docs]
+living = ["README.md", "AGENTS.md", "docs/**/*.md", "api:README.md"]
+decisions = "docs/adr"
+decisions_index = "docs/adr/README.md"
+```
+
+Leave append-only logs and backlogs out of `living`: they are full of proposals and history, and
+are true as records of their time. Without `[docs]` the command refuses with `DOCS_NOT_DECLARED`
+rather than passing on nothing, and an entry that matches no file is reported as
+`DOCS_DECLARATION_UNMATCHED`.
+
+## Run it
+
+```sh
+npx --no cockpit docs check --config cockpit.toml
+npx --no cockpit docs check --config cockpit.toml --json
+```
+
+It exits 2 when it reports anything, so a CI job runs it the way it runs `work verify`. The guard
+admits it for agents without asking, because it writes nothing. `doctor` names it when `[docs]` is
+declared but does not run it, and `check` does not run it either: both report on the environment
+and its generated files, while this reads every repository's history and judges prose, which is a
+different verdict and a slower one.
+
+## Stale references
+
+A path counts when it is an inline code span or a relative link target; spans resolve from the
+repository root, links from the document. A `make` target counts when an inline code span or a
+shell fence runs it. Either is reported only when it existed in the repository's history and does
+not exist now:
+
+- `DOCS_REFERENCE_REMOVED`: the path was deleted, or renamed, in which case the message names
+  where it went.
+- `DOCS_TARGET_REMOVED`: a Makefile once defined the target and none does now.
+
+Keying on history keeps proposals quiet: "add `make park`" names a target that never existed, so
+it is not reported, and no allowlist is needed. A link that never resolved is a link checker's
+job, not this one. npm and pnpm scripts are not checked.
+
+## Decision records
+
+The records are the Markdown files directly inside `decisions`, except the index, a `README.md`
+and any file named as a template.
+
+| Code | Reported when |
+|---|---|
+| `DECISION_NUMBER_REUSED` | two records share a numeric prefix; dated names such as `2026-09-cache.md` are not numbered |
+| `DECISION_UNINDEXED` | `decisions_index` does not link a record |
+| `DECISION_INDEX_ENTRY_MISSING` | `decisions_index` links a record file that does not exist |
+| `DECISION_STATUS_MISSING` | the status is absent or does not start with proposed, accepted, superseded, deprecated or rejected |
+| `DECISION_LINK_UNRESOLVED` | a "Supersedes" or "Superseded by" names no record |
+| `DECISION_SUPERSEDED_STALE` | an accepted record supersedes another in full, and that one still says accepted |
+
+The status is read from `status:` in YAML front matter, a `Status:` line (bold or not), or the
+first line under a `## Status` heading. A supersedes reference is a link, a file name, `ADR-12`,
+`#12`, or a number right after the keyword. "Supersedes 0012" replaces the whole record;
+"supersedes the retry clause of 0012" replaces part of it, so 0012 only has to exist.
+
+What this cannot see is a decision that was made and never written down; nothing here makes an
+agent record one.

package/docs/environment.md

@@ -34,7 +34,7 @@ input passed validation.
 | `environment.compose_files` | compose first | the surfaces, plus `check` reads the Compose topology | run the declared Compose files |
 
 The runtime commands are `up`, `sleep`, `session`, `down`,
-`reset`, `preflight`, `logs` and `runtime measure`. Every mode writes the harness
+`reset`, `preflight`, `logs`, `ps`, `restart`, `rebuild`, `exec` and `runtime measure`. Every mode writes the harness
 [surfaces](concepts.md#surface) (instructions, skills, guards, permissions, evaluator and work
 orders) and checks them for [drift](concepts.md#drift). A cockpit that declares only
 `[environment.machine]` still gets the machine-capacity checks in `preflight`, so it is not refused
@@ -66,12 +66,21 @@ with `COMPOSE_TOPOLOGY_UNAVAILABLE` if Docker cannot produce it. It also checks:
   `COMPOSE_PORT_ALL_INTERFACES`, because Docker then binds every interface and the service is
   reachable from the network; write `"127.0.0.1:${API_HOST_PORT}:3000"`, or name `0.0.0.0` when you
   mean the wider exposure;
+- a service that sets `container_name` fails with `COMPOSE_CONTAINER_NAME_FIXED`, because Docker allows
+  one container of a name and the second checkout's stack would fail to start; remove it and address
+  the service by its Compose service name, or with `docker compose exec <service>`;
+- a service with `build` and a fixed `image` fails with `COMPOSE_IMAGE_TAG_SHARED`, because every
+  checkout builds to the same tag and one checkout's build replaces the image another's stack runs;
+  remove `image`, so Compose names the build after the stack's own project;
+- a profile in `environment.profiles` or a `profile:<name>` mount that no service declares fails
+  with `COMPOSE_PROFILE_UNDEFINED`, because Compose accepts an unknown profile and starts nothing
+  for it;
 - a service with no Compose healthcheck warns with `COMPOSE_HEALTHCHECK_MISSING`, because running
   is then treated as ready;
 - an image referenced by tag rather than digest warns with `COMPOSE_IMAGE_UNPINNED`.
 
 `doctor` reports a refusal from this check as itself, with its fix, not as the surface evidence it makes
-unavailable. `init` shows the port and healthcheck findings beside the drafted `cockpit.toml`, as
+unavailable. `init` shows the port, container name, shared image tag and healthcheck findings beside the drafted `cockpit.toml`, as
 warnings carrying the same fix; it never edits a Compose file, so apply the edit before or right after
 accepting.
 
@@ -128,6 +137,25 @@ each image by digest when you can. The file is yours from then
 on: cockpit runs it as written and never rewrites it, and the scaffold refuses with
 `INIT_SCAFFOLD_COMPOSE_EXISTS` when the cockpit root already holds any Compose file.
 
+### Compose profiles
+
+A service with `profiles: [workers]` in the Compose file runs only while that profile is active.
+`environment.profiles` lists the profiles every `up` and `session` activates, and
+`up --profile <name>` or `session --profile <name>`, repeated for several, adds more for that run.
+A sibling declared `mount = "profile:<name>"` is mounted, and checked as mounted, exactly while its
+profile is active; the generated agent files follow `environment.profiles`. A profile no service
+declares is refused with `COMPOSE_PROFILE_UNDEFINED`, by `check` for the declared ones and by `up`
+for the requested ones.
+
+The stack records the profiles it started with, and every later command on it, `down`, `sleep`,
+`logs`, `preflight`, `ps` and the service verbs included, activates the same set, so `down` removes
+the profile services too. A plain `up` or `session` joins the running stack with its recorded set.
+Adding a profile changes what the stack runs, so `up` refuses it on a running stack with
+`LIFECYCLE_PROGRESS_INVALID`, as it refuses any change to what the stack was started from: run
+`down`, then `up --profile <name>`. `check` judges each service's bind mounts under the default
+set and under the default set plus each other profile, so a bind that only one profile set would
+refuse still fails `check`.
+
 ## Local URLs and port families
 
 Write each published port with an explicit loopback binding in your Compose file, as in
@@ -222,6 +250,63 @@ stale key names. Restore the named checkout or bring its instance keys in line w
 then rerun `cockpit doctor --config cockpit.toml`. When no sibling declares an environment file,
 the instance-presence and key-freshness checks pass: there is nothing to seed or compare.
 
+## Serve a sibling from a worktree
+
+The stack mounts each sibling's declared checkout. When you work on a branch in another checkout of
+that repository, usually a linked worktree, point the sibling at it for this cockpit checkout:
+
+```sh
+npx --no cockpit use api /path/to/api/.worktrees/feature --config cockpit.toml
+npx --no cockpit use api --clear --config cockpit.toml
+```
+
+`use` accepts the root of a checkout that shares the declared checkout's object store, or whose
+`origin` names the same repository as the declared checkout or its `remote`; anything else is
+refused with `SIBLING_CHECKOUT_FOREIGN`. Name the checkout's own directory: a path that reaches it
+through a symbolic link is refused. The choice is recorded in `.cockpit/local/sibling-checkouts`,
+never in `cockpit.toml`, so it applies to this checkout of the cockpit alone. `up`, `logs`, the guard's
+allowed roots and protected instance files, `doctor` and `preflight`, work orders (checks, grades,
+test gates and test-weakening detection) and `docs check` all use the recorded checkout, and each
+refuses with `SIBLING_CHECKOUT_UNAVAILABLE` once that checkout is gone. `doctor` and `preflight`
+name each one (`SIBLING_CHECKOUT_OVERRIDDEN`) and warn with
+`SIBLING_ENVIRONMENT_FILE_MISSING` for every declared environment file the worktree lacks: a fresh
+worktree has none of the ignored ones, and cockpit never copies them from another checkout.
+
+A running stack keeps the checkout it mounted: run `down` and `up` after `use`. An agent may run
+`use` for a checkout inside a directory it may already write; any other path is a person's call. The
+directory grants `sync` writes for each agent tool are committed and name the declared checkout, so a
+worktree kept inside it stays reachable without a prompt. For a checkout outside it, `use` grants
+the tools that read a machine-local setting, and `use --clear` takes that grant back:
+
+- **Claude Code**: `use` adds the checkout to `permissions.additionalDirectories` in
+  `.claude/settings.local.json`, keeping everything else in the file, and removes only the entry it
+  added. It refuses a file it cannot parse rather than rewrite it, because Claude Code ignores such
+  a file entirely.
+- **OpenCode**: `use` writes the checkout to the machine-local grant file `sync` writes for the
+  sibling, and `sync` keeps it there.
+- **Codex** has no machine-local setting for extra writable roots, so its sandbox still reaches only
+  the declared checkout: start Codex with `--add-dir <checkout>`.
+- **Cursor** and **Grok Build** have no measured machine-local grant, so `use` writes nothing for
+  them and they may ask before editing the checkout.
+
+`use` lists in its output which tools got the grant, and `--json` reports them as `agentGrants`.
+Restart an agent session that is already running so it reads the new grant.
+[Harness surfaces](harness-surfaces.md#sibling-projection-and-standing-cost) records what was measured.
+
+## Bring checkouts up to date
+
+`cockpit pull --config cockpit.toml` fetches and fast-forwards the cockpit and every sibling
+checkout, including one `use` recorded, to the upstream of the branch each has checked out. It
+never merges, rebases, stashes or switches branch, and it runs no Git hooks. A checkout with
+modified tracked files, a branch that has diverged from its upstream, an upstream that is gone or a
+failed fetch is left exactly as it was and reported with `PULL_SKIPPED` and the command that
+resolves it; a detached HEAD or a branch that tracks nothing is listed and skipped without a
+warning. Like `setup`, its Git reads only each repository's own configuration, so a credential
+helper set only in your global Git configuration is not used, and a repository whose attributes name
+a filter defined only there, such as Git LFS, is skipped rather than checked out as placeholder
+files; run `git pull --ff-only` in it yourself. Because it can only fast-forward, an
+agent may run it without asking.
+
 ## Lifecycle and ownership
 
 `setup` gets the declared sibling checkouts onto disk and wires them up. `mount` controls how the
@@ -375,6 +460,65 @@ identity, control socket or stop confirmation did not match; cockpit then keeps
 refuses any overlapping cleanup. Do not remove its state or runtime resources by hand: that
 destroys the records cockpit needs to repair it safely.
 
+### List and prune stacks across the machine
+
+Each checkout gets its own stack, port lease and state, so deleting a worktree leaves its containers,
+network, volumes and lease behind with no checkout left to run `down` from. `stacks` lists every
+stack this machine knows about, whichever cockpit and checkout started it, and changes nothing:
+
+```sh
+npx --no cockpit stacks --config cockpit.toml --json
+```
+
+It reads cockpit's state root and the containers, networks and volumes on the local Docker daemon
+that carry cockpit's ownership labels, and attributes a resource to a stack only when all of them
+are present and well formed; nothing is attributed by its name. Each row gives the cockpit, the stack,
+its Compose project, its checkout, the state record and whether this version can read it, running
+and stopped containers, networks, volumes, the port lease it still holds, its last recorded
+activity, and a verdict with the reason.
+
+A stack's checkout is proven, never guessed. Compose labels each container with the directory it
+ran from, and the ancestor whose checkout identity derives the stack's own identity is its
+checkout; or the cockpit's main checkout is known and none of the checkouts Git records for it
+derives the stack. `checkout.source` says which. The checkout is `present`, `missing`, `replaced`
+(the path exists but is no longer a checkout of that cockpit) or `unknown`. A worktree whose path
+does not exist while Git still registers it, or marks it locked, is `unknown`, not `missing`: a
+drive or share that is not mounted, or a checkout moved without `git worktree repair`, looks exactly
+like that. Once such a checkout is really gone, `git worktree prune` in its main checkout (after
+`git worktree unlock` for a locked one) lets `stacks prune` remove its stack.
+
+A stack is `orphaned` only when its checkout is proven `missing`. Every other stack is kept: one
+whose checkout exists or cannot be found, one that a `down` or `reset` is still draining, the
+current checkout's own, and one whose state this cockpit version cannot read, because a newer
+version may still use it for a checkout that exists. A state folder this version cannot read is
+listed with the stacks; one in the colon spelling an earlier build used is orphaned once none of its
+stacks is kept, and one named as current versions name their state is kept for a version that reads
+it.
+
+`stacks prune` shows exactly what it would remove and a digest of it, and removes nothing:
+
+```sh
+npx --no cockpit stacks prune --config cockpit.toml
+npx --no cockpit stacks prune --config cockpit.toml --apply
+```
+
+`--apply` observes the machine again and removes only while the plan still has the previewed digest:
+each orphan's containers, then its networks and labelled volumes, then the state records that hold
+its port lease, then the orphaned state folders. State is removed only while every file still holds
+the bytes the preview read, under the lock `up` takes to lease ports. A step that fails stops the
+prune with `STACKS_PRUNE_INCOMPLETE`; what it had not removed stays listed, and running `--apply`
+again resumes. The result is reported only once a fresh inventory no longer lists what was removed.
+
+Removing an orphan is housekeeping, so `--apply` runs for an agent. A prune that deletes volumes
+deletes data, and follows the reset gate: it runs only where `[autonomy] reset` lets the caller
+reset, and otherwise a person runs `stacks prune --interactive` in a terminal and types the
+preview's digest. That gate is the running cockpit's own policy and says nothing for another
+cockpit's, so `--apply` removes only this cockpit's orphans and the state folders an earlier build
+left. The preview still lists every orphan, marks each with `thisCockpit`, and warns with
+`STACKS_PRUNE_UNCONFIRMED` that another cockpit's are removed only by a person's
+`stacks prune --interactive`, which covers the whole machine. `doctor` warns with `STACKS_ORPHANED` when a stack of this cockpit has lost its
+checkout or a state record cannot be read, without asking Docker; `stacks` gives the full picture.
+
 ### Change a running stack
 
 A stack's identity, carried in its ownership labels and saved progress, is a digest of the Compose
@@ -390,9 +534,12 @@ receive, gives the stack a new identity, and `up` refuses with `LIFECYCLE_PROGRE
 running stack in place. To apply such a change, for example a `[ports.bases]` edit:
 
 1. Edit `cockpit.toml`. This can happen while the stack runs.
-2. Have a person run `cockpit sync --config cockpit.toml` in a terminal. Until then, the agent
-   guard holds every tool call, because the configuration no longer matches what it was generated
-   for, and `sleep` and `down` refuse because they read the Compose files `sync` publishes.
+2. Run `cockpit sync --config cockpit.toml`. Until then, the agent guard holds every tool call
+   except that sync, because the configuration no longer matches what it was generated for, and
+   `sleep` and `down` refuse because they read the Compose files `sync` publishes. An agent may run
+   it where `[autonomy] sync = "agent"` and the edit does not
+   [widen what agents may do](safety-and-autonomy.md#edits-the-guard-has-not-applied), as a
+   `[ports.bases]` edit does not; otherwise a person runs it in a terminal.
 3. Run `cockpit down --config cockpit.toml`. It finds the stack and its port lease by the stack,
    not by the edited declaration, and removes the containers still running the old declaration.
    While another holder, such as a running `cockpit session`, still holds the stack, it refuses
@@ -403,15 +550,32 @@ Restoring `cockpit.toml` to the exact bytes `sync` last saw, for example with
 `git restore cockpit.toml`, clears the guard's hold without a `sync`: the guard compares the file's
 content, not which file holds it.
 
+### When a sibling changes under a running stack
+
+A bind mount follows a sibling's files at once, but installed dependencies usually live in an image
+or volume built earlier and the database keeps the schema it was migrated to. When `up` starts a
+stack it records a digest of each mounted sibling's lockfiles and of its `rebuild_inputs`, such as
+a migrations directory. Lockfiles come from the `environment.install_policies` rows for the
+sibling's toolchain, or, without one, from the common lockfile names present in the checkout; each
+finding names which source it came from. `doctor` and `preflight` warn with `STACK_INPUTS_CHANGED`
+when any of them, or the checkout serving the sibling, changed since, and `pull` warns after
+moving one. Run `down` and then `up` so every service starts on the current files; rebuild an image
+that installs the dependencies before `up`. A resumed `up` keeps the record, because resuming
+restarts nothing; `down`, or a `sleep` that stops the stack, drops it.
+
+It is a warning, not a refusal: whether a changed lockfile matters is the product's call, and
+`test-run` does not block on it.
+
 ## Choose the Docker daemon
 
 Every command uses the daemon Docker itself would select: a `DOCKER_HOST` when set, otherwise the
-context `DOCKER_CONTEXT` names, otherwise the active context `docker context show` reports. Three
+context `DOCKER_CONTEXT` names, otherwise the active context `docker context show` reports. Four
 commands fix that daemon once, before their first step, and address only it:
 
 | Command | Why it fixes the daemon |
 |---|---|
 | `down`, `reset` | they delete; reading the context per step could list one daemon and delete from another if `docker context use` ran mid-command |
+| `stacks` | `stacks prune` deletes, for the same reason |
 | `runtime measure` | the measurement must describe the daemon `up` will use, not one selected while the probe ran |
 
 None of them needs a prefix, so they run as printed:
@@ -753,6 +917,30 @@ that, `logs` keeps the newest whole records that fit, sets `truncated` to `true`
 and warns with `LOGS_TRUNCATED`; lower `--tail` to stay under it. Output is returned after
 collection, including structured records in JSON mode, rather than streamed.
 
+### Work on one service
+
+`ps`, `restart`, `rebuild` and `exec` act on one service of this checkout's own running stack, with
+its Compose project, files and profiles, so neither a person nor an agent names the derived project.
+The stack must have been started by `up` from this checkout; after `down` they refuse and name `up`.
+
+- `ps` lists every service of the stack with its container state, health and status; a service
+  with no container is `absent`.
+- `restart --service <name>` restarts the container in place, without its dependents, then waits
+  for it as `up` does and reports its last log lines when it does not become healthy.
+- `rebuild --service <name>` builds the service's image, replaces its container and waits the same
+  way; use it when a change is baked into the image. It also works on a stack whose start stopped at
+  that service, and it records the new container so `preflight` and `logs` follow it.
+- `exec --service <name> -- <command> [args...]` runs the command inside the service's container
+  and exits with the command's own status, as `session` does. It gets a terminal only when cockpit
+  runs in one.
+
+The guard admits these verbs as it admits `up`. The command after `exec --` runs in the container,
+whose files the guard cannot see, so it is never proven read-only: the name-based denials still apply
+(`exec --service web -- cat .env` is refused like `cat .env`), and it runs without asking only when a
+`[guards] allow` rule or a declared build or test command admits it
+([Cockpit and project commands](safety-and-autonomy.md#cockpit-and-project-commands)). `reset` stays
+gated by `[autonomy]`.
+
 ## Where the decisions live
 
 Contributors looking for the source module behind each step should start at

package/docs/faq.md

@@ -67,9 +67,11 @@ its declared remote. It never rewrites Git remotes or edits undeclared files.
 
 ## Can two agents use the same machine at once?
 
-Yes. Each checkout leases its own port family, and each running `up` or `session` is a holder of
-the stack. `sleep` stops the stack only when no holder remains, so one agent cannot stop
-another's environment. See [Environment](environment.md#lifecycle-and-ownership).
+Yes. Each checkout, a linked worktree included, leases its own port family and runs its own stack,
+and each running `up` or `session` is a holder of it. `sleep` stops the stack only when no holder
+remains, so one agent cannot stop another's environment. `cockpit use` points a sibling at a worktree
+for one cockpit checkout, and `cockpit stacks prune` removes the stack a deleted worktree left behind.
+See [Environment](environment.md#lifecycle-and-ownership).
 
 ## What happens to my secrets?