@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/docs/environment.md

@@ -0,0 +1,760 @@
+# Environment lifecycle
+
+This page is the reference for cockpit's environment commands: what each one does, what it
+refuses, and how to recover when it refuses. It is for people running cockpit on a product and for
+agents working inside it. For the order to run the commands in, follow
+[Bring the product up](getting-started.md#bring-the-product-up); every flag is in the
+[CLI reference](cli-reference.md), and `cockpit <command> --help` prints a command's usage.
+
+## Output and exit codes
+
+Add `--json` to get the result and any diagnostics as one JSON document on stdout. Without
+`--json`, cockpit prints the result as readable text and diagnostics to stderr. Every refusal exits
+nonzero with a named diagnostic code, and unknown flags are refused. `logs` defaults to
+`--tail 100 --since 15m`.
+
+## Input limits
+
+cockpit checks the size of configuration, registry and adoption files before parsing them, against
+the limit defined in [`config/load.ts`](https://github.com/b0dea/cockpit/blob/main/packages/cockpit/src/config/load.ts). A file that cannot
+be read, is not a regular file, is too large, or changes while cockpit reads it is refused with a
+diagnostic. Make the file smaller; raising an output or subprocess limit does not change this one.
+
+A skipped registry row produces no `init --registry` draft, because cockpit may no longer know
+which repository it applies to. `registry-resolve` prints shell data you can `source` only when its
+input passed validation.
+
+## Environment modes
+
+`[environment]` is optional. What it declares decides which commands have anything to run.
+
+| Declares | Mode | `sync` and `check` | Runtime commands |
+|---|---|---|---|
+| no `compose_files` | surfaces only | write and drift-check the harness surfaces | refuse with `ENVIRONMENT_NOT_DECLARED` |
+| `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
+[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
+as surfaces only. `doctor` reports an undeclared runtime as not declared, not as healthy, and its
+`declarations` result says whether the runtime, the reset volumes and the seed command are
+declared. [`examples/docs-only`](https://github.com/b0dea/cockpit/blob/main/examples/docs-only/README.md) and
+[`examples/compose-first`](https://github.com/b0dea/cockpit/blob/main/examples/compose-first/README.md) show the two modes. Vendor stubs,
+TLS, seeding and restoring data are plain Compose; [Compose patterns](compose-patterns.md) shows
+each.
+
+### Compose-first stacks
+
+`environment.compose_files` lists paths relative to the cockpit root, and each must stay inside it.
+Compose resolves every relative path in those files, such as `build: ./api` or `"./api:/app"`,
+against the directory of the first listed file, exactly as `docker compose -f <first> -f <second>`
+does. So `compose_files = ["shop/compose.yml"]` runs a product repository's own file with its `./`
+paths meaning what they mean in that repository. Every command passes that directory to Compose as
+`--project-directory`, because Compose reads verified snapshots of the files and could not
+otherwise tell where they came from. List files from two directories only when the later ones name
+no relative paths, since theirs resolve against the first file's directory too.
+
+`check` reads your Compose topology with `docker compose config`, without interpolation, and refuses
+with `COMPOSE_TOPOLOGY_UNAVAILABLE` if Docker cannot produce it. It also checks:
+
+- a published host port not written as a `[ports.bases]` variable, such as `"127.0.0.1:4200:3000"`,
+  fails with `COMPOSE_PORT_NOT_LEASED`, because the same number collides across worktrees and
+  parallel stacks; write `"127.0.0.1:${API_HOST_PORT}:3000"` instead;
+- a published port with no host interface, such as `"${API_HOST_PORT}:3000"`, warns with
+  `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 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
+warnings carrying the same fix; it never edits a Compose file, so apply the edit before or right after
+accepting.
+
+cockpit never edits your Compose files. To run the stack, `sync` writes `compose.cockpit.yml`, an
+override that belongs to cockpit and adds its ownership labels to every service, the default
+network and every named volume that is not `external`. Volumes also get a generation label, so
+`reset` can account for each `resettable_volumes` entry. `check` drift-checks the override, and
+runtime commands pass it after your declared files only while it matches what cockpit would
+generate now. A Compose `include` is refused with `GENERATED_DECLARATION_INVALID`, because Compose
+reads an included file from disk, outside the verified snapshot, and cockpit could not label the
+services it brings in; list the file in `environment.compose_files` instead.
+
+Runtime commands give Compose only these variables: the leased `[ports.bases]` variables, each
+`[[sibling]] var` set to that sibling's absolute directory, and cockpit's own stack and holder
+identities. Any other `${VAR}` reference needs a `:-default`. Every Compose command that
+interpolates the checked configuration turns off Compose's automatic loading of the project `.env`
+file, because a file cockpit has not checked must not change the topology it has checked. The
+topology check does not read service `env_file` contents either, so service secrets never enter
+cockpit's records; Compose still passes those files to the containers when the stack runs.
+
+Mounts must match the declaration in both directions:
+
+- Each sibling declared with `mount = "always"` must be bind-mounted, whole or a directory inside
+  it. Otherwise `check` fails with `COMPOSE_SIBLING_NOT_MOUNTED` and `up` refuses to start the
+  stack. Mount it through its variable, as in `"${WORKER_DIR}:/srv/worker"` or
+  `"${WORKER_DIR}/src:/app"`, through a path relative to the first Compose file's directory, as in
+  `"./worker:/srv/worker"` from a `compose.yml` in the cockpit root, or set `mount = "none"` on the
+  row.
+- Each `environment.generated_host_paths` entry must reach a container: bound itself, through a
+  directory inside it, or inside a bound directory such as a sibling mounted whole. Otherwise
+  `check` fails with `GENERATED_HOST_PATH_UNMOUNTED`.
+- A container gets only what `cockpit.toml` declares. A bind outside every `mount = "always"`
+  sibling and every `environment.generated_host_paths` entry, or one that leaves its sibling
+  through a symbolic link, fails `check` with `COMPOSE_BIND_UNDECLARED`, and `up` refuses it.
+
+### Scaffold a Compose file
+
+A small app with no Compose file can get a starting one, once:
+
+```sh
+npx --no cockpit init . --scaffold-compose api --port 3000 --with postgres,redis
+```
+
+`--scaffold-compose` names the app directory relative to the cockpit root (`.` for the root
+itself) and `--port` the port the app listens on inside its container. The app builds from its
+Dockerfile; without one, a directory with a `package.json` runs on `node:22-alpine` and needs
+`--command "npm start"` or whatever starts it. `--with` adds a database or cache from a fixed list,
+`postgres` and `redis`, each on a pinned major version with a healthcheck, a named volume and its
+URL in the app's environment. The written `compose.yml` publishes the app on
+`127.0.0.1:${API_HOST_PORT:-3000}` and bind-mounts the app directory, and the command prints the
+`[ports.bases]` variable and `resettable_volumes` entries to declare. `check` then warns that the
+app service has no healthcheck and that the images are pinned by tag; add a healthcheck and pin
+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.
+
+## Local URLs and port families
+
+Write each published port with an explicit loopback binding in your Compose file, as in
+`"127.0.0.1:${API_HOST_PORT}:3000"`, so starting a local stack does not expose it to the network;
+use `::1` for IPv6 loopback, or `0.0.0.0` only when you intend that wider exposure. cockpit does not
+rewrite your published interfaces.
+
+Stack *n* publishes each `[ports.bases]` value plus *n* × `ports.step`, for up to `ports.count`
+stacks (defaults: step 100, count 27). `up` leases a whole port family under one lock shared by
+every cockpit run by your user account with the same canonical
+[state root](troubleshooting.md#clear-cockpit-state). It skips any family holding a port that
+another cockpit's active lease holds, then checks that no other program is listening on
+the ports it picked. Cockpits with similar bases therefore never get the same ports, even before
+either stack starts listening; an overlap costs a candidate family, never a shared port. Each
+cockpit's stack count applies only to its own stacks. A retained lease keeps its original family
+and blocks any conflicting reservation. Other user accounts and separate state roots, including different Linux `XDG_STATE_HOME`
+settings, are not coordinated; only the listener check separates them.
+
+The listener check looks for a listener on each port on IPv4 loopback when ports are first
+allocated. It does not reserve the port, does not see a listener bound only to IPv6, and cannot
+stop another process binding the port afterwards. If startup reports a bind failure, find the
+conflicting process, resolve it, and rerun `cockpit up --config cockpit.toml`. The lease stays
+reserved until cockpit has confirmed its cleanup, even when its holder is no longer running. To
+change a stack's ports, see [Change a running stack](#change-a-running-stack).
+
+### Named local URLs
+
+Entrypoint derivatives turn a port lease into application origins, callback URLs and other
+declared addresses. Add an optional `hostname` and `scheme` to use a named local URL:
+
+```toml
+[ports.bases]
+APP_HOST_PORT = 8443
+
+[[environment.entrypoint_derivatives]]
+name = "application"
+kind = "origin"
+port = "APP_HOST_PORT"
+path = "/"
+hostname = "app.sample.localhost"
+scheme = "https"
+```
+
+Run `cockpit up --config cockpit.toml --json` and use the entrypoint it returns; the example
+produces `https://app.sample.localhost:<leased-port>/`. The port comes from the selected port
+family, including any nonzero offset, and a retained lease derives it the same way. Omitting
+`hostname` uses `127.0.0.1`; omitting `scheme` uses `http`. Automatic numeric entrypoints keep their
+plain HTTP loopback URLs. These declarations set no environment variables in the application:
+configure the product's public origin and callback settings to match the returned address.
+
+Names must be lowercase DNS subdomains of `.localhost`, with ordinary letter, digit and hyphen
+labels. Arbitrary suffixes, bare `localhost`, wildcard names and embedded ports are refused.
+[RFC 6761](https://www.rfc-editor.org/rfc/rfc6761.html#section-6.3) reserves `.localhost` for
+loopback; an arbitrary name such as `local.app.sample` has no such guarantee. Use a distinct
+hostname for each project, because
+[cookies are not isolated by port](https://www.rfc-editor.org/rfc/rfc6265.html#section-8.5).
+
+Host clients use the host resolver, and conforming resolvers map `.localhost` names to host
+loopback. Inside a container, loopback is that container's own, so a product container that calls
+the host-published URL needs its own `extra_hosts` mapping to the right host gateway;
+service-to-service traffic normally uses Compose service names and container ports instead.
+`browser.resolver` supplies mappings only to the browser the `browser` commands launch, not to an
+unrelated remote browser, MCP server or other client: put the mapping where that client's network
+process runs. Browser operations then use that browser's own networking and DNS, as described in
+[Work and browser](work-and-browser.md#browser-evidence).
+
+`scheme = "https"` only declares a URL; the product's Compose stack must serve TLS on that leased
+port. cockpit does not install trust roots, change host DNS or start a shared HTTPS proxy. To set
+it up:
+
+1. Provision a certificate whose subjectAltName covers the exact hostname. Port offsets do not
+   change the certificate identity.
+2. Keep private keys outside tracked files and build contexts, and mount only the leaf key into
+   the TLS service.
+3. Explicitly trust the issuer in each runtime that connects. Clients need the public CA
+   certificate, never the CA signing key.
+4. Rerun `cockpit up --config cockpit.toml` and open the returned URL with certificate validation
+   enabled.
+
+[Compose patterns](compose-patterns.md#serve-tls) shows a TLS service in front of the app.
+
+## Sibling and template paths
+
+`sync` and `check` require each declared [sibling](concepts.md#sibling-repository) directory to
+exist inside the siblings root, both as written and after following filesystem links. An absolute
+sibling path is accepted only inside that root. Get missing checkouts onto disk, for example with
+`cockpit setup`, before running `sync`.
+
+`doctor` and `preflight` inspect every declared environment file in every sibling, and each check
+lists all its failing paths, so one healthy file cannot hide another file's missing instance or
+stale key names. Restore the named checkout or bring its instance keys in line with its template,
+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.
+
+## Lifecycle and ownership
+
+`setup` gets the declared sibling checkouts onto disk and wires them up. `mount` controls how the
+stack uses a checkout; `acquire` controls how it gets onto disk; the two are independent. Setup
+looks at declared secret-file paths but never reads or copies their contents.
+
+A sibling with `instruction_pointer = true` asks setup to connect the product's own **AGENTS.md**
+to the cockpit guide. Plain `cockpit setup --config cockpit.toml` only reports the proposed path, so
+an agent cannot silently change the instructions later agents load. After a person reviews the
+exact block, `cockpit setup --config cockpit.toml --write-instruction-pointers` appends that marked
+block and keeps every other byte. A missing guide is created only by this approved write; edited,
+partial or duplicate marked blocks are refused so a person can reconcile them. Setup also refuses
+redirected directories and invalid UTF-8 rather than replace the product's bytes.
+
+An agent started inside a sibling loads only the instruction files its own tool reads: Codex and
+OpenCode read **AGENTS.md**, while Claude Code reads **CLAUDE.md**, as runs of each tool beside a
+decoy file showed. Every tool gets the same
+instructions only when AGENTS.md holds them and CLAUDE.md imports it with a line reading
+`@AGENTS.md`. `doctor` warns for every sibling laid out otherwise:
+`SIBLING_INSTRUCTIONS_AGENTS_ONLY`, `SIBLING_INSTRUCTIONS_CLAUDE_ONLY`,
+`SIBLING_INSTRUCTIONS_UNLINKED` (both files, no import), `SIBLING_INSTRUCTIONS_MISSING` (neither),
+and `SIBLING_INSTRUCTIONS_TOOL_ONLY` for files such as **.cursorrules** or **GEMINI.md** that none of
+those tools load. Setup proposes the two changes that need no judgement, and makes them only when
+a person runs `cockpit setup --config cockpit.toml --write-instruction-files` after reviewing them:
+a sibling with only AGENTS.md gets a CLAUDE.md holding `@AGENTS.md`, and a sibling with only
+CLAUDE.md has it copied byte for byte to AGENTS.md and replaced by `@AGENTS.md`. Setup proposes no
+move when CLAUDE.md imports other files with `@`, because only Claude Code would follow those
+imports from AGENTS.md. It writes only ordinary files, never through a link, and refuses when a
+file changed after it was read. Merging two diverging files, or writing a first AGENTS.md, needs a
+person's judgement and stays with them.
+
+### Start or resume the stack
+
+`up` starts the selected stack, or resumes it. It records a holder it newly adds separately from an
+existing one, so if the start fails, cockpit undoes only what that attempt added. Before resuming,
+cockpit checks that the saved progress still matches the current lifecycle record, runtime and port
+lease. If it does, cockpit rechecks the services that already completed and resumes the rest; if
+anything changed, it discards that progress before touching containers left by the earlier
+attempt. After the first seed, missing saved progress blocks startup. Restore that state rather
+than delete it: deleting it would make the stack look like a fresh environment when it is not.
+
+When a service that `up` started does not become healthy, cockpit reports that service's last log
+lines as one diagnostic, then stops its container and keeps it, so a restart policy cannot leave it
+restarting. Failure logs are limited to that service and time window, and never follow the process
+that failed. The holder and lease stay, so the next `up` resumes and `down` removes the stack.
+
+When `up` starts services, it times the start, from the earliest recorded service start to the
+moment the last newly started service reports healthy. If that exceeds `cold_start_seconds`, `up`
+refuses with `MACHINE_COLD_START_EXCEEDED`. Each service start may run for the whole declared
+budget, and the configuration refuses a budget above 3600 seconds, the longest `up` holds one
+start open. A successful result reports `coldStart.measuredMillis`,
+`limitMillis` and `headroomMillis`. A partial resume times only the services that run started.
+Joining a stack that is already running, or that another holder started, reports no duration
+rather than an invented one.
+
+### Release the stack
+
+`sleep` removes the current holder. It stops the shared runtime only when no other holder remains,
+so one holder cannot stop another's environment. Stopping the runtime also releases the stack's port
+lease, so a stopped stack does not use up one of the `ports.count` families other checkouts need;
+the next `up` leases afresh and may land on a different family, so read the ports and entrypoints
+it returns instead of reusing the earlier ones. `stackId` names the shared runtime and
+`checkoutId` names one checkout; two checkouts with the same stack ID are still not
+interchangeable.
+
+`session` runs `up`, keeps that holder while one foreground command runs, and runs `sleep` only
+after confirming that the command's process group has stopped. A command that prints nothing still
+counts as running. Interrupting the wrapper stops only the process group it started, then sleeps.
+If cockpit cannot confirm that the process group stopped, it keeps the holder so you can clean up
+explicitly. Ordinary cockpit lifecycle commands run inside the wrapper use the same private session
+identity, and a second `cockpit session` wrapper is refused. Once cleanup completes, `session`
+exits with the command's own status, or 128 plus the signal number (and names the signal) when a
+signal ended it. It exits 2 when cleanup fails and 130 when you cancel it.
+
+A session records its wrapper's process ID and start identity with its hold: on Linux the start in
+clock ticks since boot from `/proc`, which a wall-clock step (NTP, a resumed VM) does not move, and
+elsewhere the start time `ps` reports. A wrapper that dies without its closing `sleep`, from
+SIGKILL, a crash or a closed terminal, leaves that hold behind; the next `up`, `sleep`, `down` or
+`reset` from the checkout sees that the process is gone, or that its process ID now belongs to a
+process with another start, and releases it. When it was the last hold, the command's own hold
+takes the running stack over, so `sleep` stops it and `down` removes it. A hold whose process is
+still running is kept, and so is one whose start could not be read while its process ID is in use:
+the `CLAIM_CO_TENANT` refusal names each such holder and its process ID, so you can end that
+command, for example with `kill <pid>`, and retry.
+
+The wrapper passes its process ID and start identity to its command in `COCKPIT_SESSION_PROCESS`, so
+a hold that a `sleep` and then an `up` inside the session drop and re-add is still tied to the
+wrapper, and is released the same way once the wrapper is gone. `up` reads that process's start
+again before recording it, and refuses with `CLI_USAGE_INVALID` when the wrapper has ended or the
+value is malformed.
+
+The command `session` runs gets the stack's addresses in its environment, so an agent started under
+it can reach the stack without rerunning `up --json`:
+
+- each `[ports.bases]` name holds the port leased for this stack, the same value the Compose files
+  read, as in `API_HOST_PORT=4210`;
+- each entrypoint `up --json` returns is under `COCKPIT_ENTRYPOINT_` followed by its name in upper
+  case with hyphens as underscores, as in
+  `COCKPIT_ENTRYPOINT_API_HOST_PORT=http://127.0.0.1:4210/`.
+
+The lease is the truth for the stack, so these replace a value of the same name already set in the
+calling shell. They are read once when the command starts and do not follow a later `down` and
+`up`. When the command ends, the session releases only its own hold: a stack that an earlier `up`
+from this checkout still holds keeps running, and the session says so with
+`SESSION_STACK_RETAINED`; `sleep` releases that hold.
+
+Each `sleep` and `down` stops containers with a stop grace: Docker sends SIGTERM and waits ten
+seconds before killing. A service whose PID 1 ignores SIGTERM, as `node` does unless the program
+handles it, pays the whole grace at every stop. Add `init: true` to such a service in your Compose
+file, or handle SIGTERM in the program.
+
+### Remove the stack and its data
+
+`down` removes only what cockpit's runtime, checkout and ownership records show it owns: it lists
+only containers, networks and images that carry this stack's ownership label, and reports and
+keeps anything it cannot show is this stack's. Ownership is the stack's identity, not the
+configuration, so a container or network that an earlier `cockpit.toml` started is removed too. An
+image the stack built carries the same label and is removed, unless it also has a second tag.
+Volumes stay, because only `reset` deletes data.
+
+When one of the stack's own resources has to stay, such as a network another container is still
+attached to or an image tagged under a second name, `down` refuses with `DOWN_RESOURCES_KEPT` and
+names each resource and the reason, rather than reporting a stack removed that is still there. It
+clears startup progress only after confirming the removals, which lets the next `up` start
+afresh. `down` also retires a stack that `sleep` or an ended `session` left stopped:
+with no holder left, it claims the stack for this checkout without starting anything and removes
+it, so you do not have to run `up` first. While another session still holds the stack, `down`
+refuses with `CLAIM_CO_TENANT` and names that session's holder and process; end that
+`cockpit session`, then retry.
+
+`reset` first shows an exact preview of the declared volumes and generated host paths it would
+delete. Plain and `--json` reset calls delete nothing. Interactive reset needs a person at a
+terminal outside CI; the approval stays with the process that showed the preview, which checks
+everything again before it acts. `down` and `reset` delete only from a local Docker daemon, which
+they fix once per run; see [Choose the Docker daemon](#choose-the-docker-daemon).
+
+Name each `environment.resettable_volumes` entry by its top-level `volumes:` key in the Compose
+file. Docker's volume name carries a per-checkout project prefix, so it is not accepted. `sync`,
+`check` and every runtime command, `down` included, refuse a name that no declared volume has, and
+an `external` volume too, because cockpit cannot label it. A declared volume that does not exist yet is left out of the
+preview. A volume that an earlier `cockpit.toml` created is still this stack's data, and `reset`
+deletes it with the rest.
+
+Every destructive action is recorded durably before it starts. If cockpit itself is interrupted, a
+detached supervisor process keeps track of that exact attempt. The next `sleep`, `down` or approved
+`reset` asks the supervisor to stop the action's process group, confirms the group is gone, marks
+the attempt as failed, and retries the saved action. If the target was already removed, cockpit
+checks again that it is gone and that the remaining targets are unchanged, then marks the action
+complete without repeating it. `DRAIN_ATTEMPT_REPAIR_REQUIRED` means the attempt marker, supervisor
+identity, control socket or stop confirmation did not match; cockpit then keeps the attempt and
+refuses any overlapping cleanup. Do not remove its state or runtime resources by hand: that
+destroys the records cockpit needs to repair it safely.
+
+### Change a running stack
+
+A stack's identity, carried in its ownership labels and saved progress, is a digest of the Compose
+files and of the `cockpit.toml` declarations that reach its containers, not of the bytes of
+`cockpit.toml`. Editing a sibling's
+`purpose`, the guards, MCP, surfaces, comments or formatting leaves a running stack alone, and the
+next `up` resumes it. So do the fields the host checks rather than the containers receive:
+`[environment.machine]` (including `cold_start_seconds`), `addressing`, `authentication`,
+`posture_requirements`, `resettable_volumes`, `seed` and `entrypoint_derivatives`.
+
+A change to a Compose file, or to ports, mounts or anything else in `cockpit.toml` the containers
+receive, gives the stack a new identity, and `up` refuses with `LIFECYCLE_PROGRESS_INVALID` rather than replace the
+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.
+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
+   with `CLAIM_CO_TENANT`.
+4. Run `cockpit up --config cockpit.toml --json` and use the newly returned ports and entrypoints.
+
+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.
+
+## 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
+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 |
+| `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:
+
+```sh
+npx --no cockpit down --config cockpit.toml
+npx --no cockpit runtime measure --config cockpit.toml --image node:22-alpine
+```
+
+However the daemon was chosen, its endpoint must be an absolute `unix://` socket path. TCP, SSH and
+other transports are refused, because a remote daemon could receive a deletion and its behaviour
+says nothing about this machine. A `DOCKER_HOST` that is not local is refused with
+`CLI_USAGE_INVALID`; a named or active context that is not local, or whose endpoint cannot be read,
+is refused with `RUNTIME_UNAVAILABLE`, naming the context and its endpoint. For `down` and `reset`,
+conflicting selections are refused, and so is a TLS override. Socket paths keep literal spaces and
+punctuation, and cockpit uses the exact spelling when it binds the context and runs discovery or
+deletion.
+
+## Compose project name
+
+Every command that runs Docker Compose passes `--project-name <cockpit.name>-<stack>`, where `<stack>` is the first 12 hex digits of the stack ID. The
+stack ID comes from the cockpit's main checkout and the current checkout, so two cockpits that share
+a `cockpit.name`, or two checkouts of one cockpit, get separate projects on one Docker daemon
+instead of replacing each other's containers. It never depends on the bytes of `cockpit.toml`, so
+editing the file keeps the same project.
+
+Containers, networks and named volumes carry that name: a cockpit named `shop-cockpit` runs
+containers such as `shop-cockpit-3f2b3aead733-api-1` and a volume
+`shop-cockpit-3f2b3aead733_postgres-data`. Your own file's `name:` is overridden. To look at the stack with Docker directly, find the project with `docker compose ls`
+and name it: `docker compose --project-name shop-cockpit-3f2b3aead733 ps`. Renaming `cockpit.name`
+addresses a different project and stack, so run `down` before renaming, as
+[Rename a cockpit](getting-started.md#rename-a-cockpit) describes.
+
+## Measure the container runtime
+
+`up`, `session`, `down` and `reset` refuse with `RUNTIME_UNMEASURED` unless the container runtime
+Docker selects has been measured on this machine. `sleep` and `logs` act on a running stack and
+fail while its runtime no longer matches a measurement, for example after an engine upgrade.
+`preflight` and `doctor` only report an unmeasured runtime, as an unavailable check. A measurement
+is a fact about one machine, not something the team declares: teammates run different runtimes and
+versions, so it is never written to `cockpit.toml`.
+
+cockpit identifies the runtime from one `docker info` reading of `OperatingSystem`, `Name` and
+`OSType`:
+
+| Runtime identity | Recognised by | Provenance |
+|---|---|---|
+| `docker-desktop` | `OperatingSystem` is `Docker Desktop` | vendor `docker info` output, not probed |
+| `orbstack` | `OperatingSystem` is `OrbStack` | observed on an OrbStack host |
+| `colima` | `Name` starts with `colima` | vendor `docker info` output, not probed |
+| `rancher-desktop` | `Name` ends with `rancher-desktop` | vendor `docker info` output, not probed |
+| `docker-engine` | a Linux host whose daemon reports `OSType` `linux` | vendor `docker info` output, not probed |
+
+Any other reading, including an unrecognised VM on macOS, is not identified and never accepted; the
+refusal lists the raw `docker info` values so you can report them.
+
+Measure the runtime on this machine:
+
+```sh
+docker pull node:22-alpine
+./node_modules/.bin/cockpit runtime measure --config ./cockpit.toml --image node:22-alpine
+```
+
+The command runs a probe in a throwaway directory: a candidate stack that exercises profiles, bind
+mounts in both directions, labels, health, logs, recovery and teardown, next to a deliberately
+broken Compose file that the runtime must reject. It uses only the local image you name and never
+pulls. Its Compose project is `<cockpit.name>-probe-<id>`, so anything it leaves on a shared daemon
+names the cockpit that ran it, and the probe removes it before returning. If a measure was killed
+before it could, the next `runtime measure` first removes that cockpit's own probe containers,
+network and volume and the stale `cockpit-runtime-measure-*` temporary directory, and lists what it
+removed. Each probe resource carries a `dev.b0dea.cockpit.probe-owner` label naming the measure
+process that created it, so a measure running from another worktree or terminal, with its own
+temporary directory, is still recognised: only resources whose process is gone are removed, and
+anything that may belong to a measure still running is left and named. It refuses to probe when a
+leftover cannot be removed, naming it. The probe runs only from
+an installed `@b00dea/cockpit` package and only against a daemon that passes the
+[local endpoint rules](#choose-the-docker-daemon).
+
+If the candidate passes and the broken file is rejected, the command records the measurement in
+`machine/runtime-measurements.json` under cockpit's per-user state root (the same root the stack
+state lives in), so every checkout and git worktree on this machine reads it and measures once. The
+record is keyed by the runtime identity and the daemon name `docker info` reports, and holds the
+engine version and the Compose version the probe saw, which becomes the Compose floor. Measuring
+again replaces the row for the same runtime and daemon and keeps the others, so switching between
+two runtimes needs one measurement each. A failed measurement records nothing.
+
+`up` admits the runtime only when this machine's record has a row for the same runtime and daemon,
+with the same engine version and a Compose version at or above the floor, so an engine upgrade
+needs a new measurement. Recording a measurement changes no committed file, so an agent can run it
+before its first `up` without waiting for a human `sync`. `doctor` names the measurement that
+admitted the runtime in the `RUNTIME_UNMEASURED` check's source.
+
+## Secret sources and environment schemas
+
+Keep each product component's `.env.schema` tracked beside its application. If its ignore rules
+match `.env.*`, explicitly allow `.env.schema` and confirm that Git tracks it before adoption. The
+schema declares variable names, validation and how a provider resolves each value; review its
+resolver code and dependency lock as you would product code.
+
+Put encrypted resolver expressions or external-provider references in
+`env/.secrets/<cockpit-project>/<component>`, which the generated guards keep agents from changing
+or staging. Ignore `env/.secrets/` in the cockpit's `.gitignore` before any secret material exists,
+create the directories with mode 0700 and no symbolic links, and create resolver files with mode
+0600 through your own approved provisioning process. cockpit does not create those files or their
+values.
+
+The shipped setup procedure explains how to adopt Varlock, optionally, through the product's
+pinned dependency and an existing declared command or script. Use agent-mode validation for status
+and `run --inject vars --redact-stdout` for a trusted product process, and keep resolved
+credentials out of the agent's environment. Give both paths as absolute paths with repeated
+`--path`: the component schema root first, then its central resolver directory in the cockpit; the
+later path wins. Installation, initialization, provider login, encryption and migration need
+explicit permission from whoever owns the product and the provider. Current commands and
+limitations are in the [Varlock CLI reference](https://varlock.dev/reference/cli/load-and-run/) and
+[AI tools guide](https://varlock.dev/guides/ai-tools/).
+
+`cockpit preflight` and `cockpit doctor` check every sibling that contains a `.env.schema` and skip
+the rest. Each runs `varlock load --agent --format json-full --path <sibling>` from your `PATH`
+with the command's timeout and a 256 KiB output cap, and keeps only key names and a validity
+category; values and Varlock's messages are discarded. `ENV_SCHEMA_UNHEALTHY` fails the row and
+names the sibling and its keys, or reports the row as unavailable when Varlock times out, exits
+without a readable report, or a provider cannot resolve a value; run `varlock load` in that sibling
+to see why. `ENV_SCHEMA_TOOL_MISSING` is a warning, not a failure, when Varlock is not installed
+(<https://varlock.dev>).
+
+Report only variable names, validation state, exit status and where each value came from. Raw
+resolver output, resolved values and browser state do not belong in work-order results. Generated
+guards refuse changes and staging under secrets directories, including staging a parent directory
+of the central store; whether a harness can natively block reads of these files has not been
+tested. Git ignore rules, filesystem permissions, encryption and output redaction do not protect
+secrets from malicious code running as the same user, and trusted product child processes receive
+plaintext variables. A stronger boundary needs a separately tested sandbox and provider policy.
+
+## Check and sync
+
+`check` works out what the generated files should contain now and compares that with every whole
+file and shared-file region listed in the ownership manifest (see
+[generated ownership](concepts.md#cockpit-generated-ownership)). It reports drift and never changes
+an output. `sync --dry-run` does the same preparation and lists the writes and removals, in order,
+without changing anything. `sync` writes the full set as one recoverable filesystem transaction.
+
+Team package metadata is prepared separately: a known surface conflict, an input overlap or a
+refused stale-removal approval leaves it unchanged; resolve the reported conflict, then run
+`cockpit sync --config cockpit.toml` again. Metadata is replaced only after these checks pass, but
+a later I/O failure or concurrent input change can still leave those metadata updates in place
+while the generated-file transaction reports its own recovery result.
+
+Removing a stale file needs a separate approval of the exact path, operation and current bytes that
+the dry run showed. Plain `sync` refuses to apply it; `sync --interactive` shows the request and
+asks you to type its exact digest. After approval and a final recheck, cockpit can remove an
+unchanged whole file, or its own region in a shared file. Files cockpit did not write,
+and bytes outside its regions, are kept. A stale path that changed or is unsafe needs manual
+reconciliation before you retry.
+
+Generated content for a shared Markdown region is rejected before writing if it contains either
+region delimiter, and shared JSON updates keep the whitespace outside cockpit's property group. The
+transaction plans its helper steps before staging and keeps time in reserve to roll back if forward
+work reaches its deadline. If cockpit cannot confirm that writing or rollback finished, it keeps the
+recovery inputs and refuses to report success.
+
+Capability states, overlay rules, MCP approval, sibling guide copies, the skill contract and
+`selftest` for the generated harness surfaces are in [Harness surfaces](harness-surfaces.md);
+see [Upgrade cockpit](harness-surfaces.md#upgrade-cockpit) before changing the installed version.
+
+## Bring-up order
+
+Bring-up starts from the lifecycle history: `setup` writes `started`, and so does the first `up` on
+a stack that has neither lifecycle data nor history, so you do not have to run `setup` first.
+Lifecycle data without history is refused as lost history. Bring-up then checks the runtime,
+starts the Compose stack, waits for every service to report healthy, records `seeded` in the
+lifecycle history, and only then runs `environment.seed` when it is due. A refusal keeps the
+progress so the next `up` resumes. Fix the named prerequisite or failed check; never edit
+lifecycle state to fake `started` or `seeded` history.
+
+## Result words
+
+Environment results use four words with exact meanings. `enforced` and `unavailable` mean what they
+mean for harness features (see [Capability states](harness-surfaces.md#capability-states)); for the
+environment:
+
+- **enforced**: cockpit refuses a declaration, file, ownership record, identity, mount or
+  operation that does not match.
+- **measured**: a probe produced the stated result. Repository tests run mounted candidates next to
+  unmounted and incompatible controls, but those synthetic controls say nothing about your local
+  runtime.
+- **unavailable**: cockpit could not get or verify the required result, and it counts as not
+  passing.
+- **human_needed**: product or vendor behavior a maintainer still has to review; no check has
+  established it.
+
+## Demo data, test users and roles
+
+This section is for whoever makes the local stack start with useful data and test users.
+cockpit runs the product's own seed command and records when it last succeeded. It never writes
+rows or creates identities itself: the product's writers already encode its invariants, and a
+second writer in cockpit would drift from them.
+
+**What to declare.** Name the Compose volumes that hold the data, and the command that fills them:
+
+```toml
+[environment]
+compose_files = ["compose.yml"]
+resettable_volumes = ["postgres-data"]
+seed = { argv = ["npm", "run", "db:seed"], timeout_seconds = 300 }
+```
+
+`up` runs the seed once every service is healthy, whenever no successful seed is recorded for the
+stack or one of the `resettable_volumes` was created after the last one: the first `up`, the `up`
+after `reset`, and the `up` after anything else removed the volume. The command runs on the host
+from the cockpit directory, with the leased `[ports.bases]` variables and each
+`COCKPIT_ENTRYPOINT_*` address added to the caller's environment, so it reaches the stack as a
+person's shell would. `up --json` reports `seed` as `ran` or `current`. A seed that exits nonzero,
+or runs longer than `timeout_seconds`, refuses with `DATA_SEED_FAILED`: the stack stays up, its data
+may be partly applied, and the next `up` runs the seed again, so write it to be rerun. When Docker
+cannot say when the volumes were created, `up` refuses with `DATA_SEED_UNAVAILABLE` rather than
+guess. `seed` requires `resettable_volumes`, because those volumes are what tells cockpit the data
+is gone. To seed from inside the stack instead, see
+[Compose patterns](compose-patterns.md#seed-or-restore-data).
+
+Preview a reset with `cockpit reset`, which lists exactly which volumes and host paths it will remove.
+Applying it wipes data, so it needs a person by default: `reset --interactive` in a terminal, or
+`reset --apply` when `[autonomy] reset` allows the caller. The next `up` seeds again, because the
+volume `reset` recreated is newer than the last seed.
+
+```sh human-only: resets data and requires the declared local stack
+./node_modules/.bin/cockpit up --config cockpit.toml
+./node_modules/.bin/cockpit reset --config cockpit.toml --json
+./node_modules/.bin/cockpit reset --interactive --config cockpit.toml
+./node_modules/.bin/cockpit up --config cockpit.toml
+```
+
+**Test users.** cockpit has no user model; the product's seed creates them. Give each test user a
+stable synthetic ID such as `auth-admin` or `auth-member`, a role, one operation it must be allowed
+and one it must be denied. Stable IDs let a re-seed update the same rows, and the allowed and denied
+pair proves the roles work, not only that a sign-in succeeded. The shipped `cockpit-setup` skill
+carries an on-demand reference (`references/test-data-and-personas.md`) that keeps these identities
+separate from what an identity provider owns.
+
+**Fixture hygiene.** These rules come from seeders that broke in real use:
+
+- Seed through the product's own writers, not raw inserts, so derived fields and constraints hold.
+- A re-seed restores only the fields a fixture names. Name every field a test changes, or the next
+  run fails its own precondition. Unset fields rather than writing null.
+- Seed the settled state a test needs. Default column values can read as work in flight and
+  disable the interface.
+- Before a seed writer runs, assert that every database and service target is local. A development
+  fixture is no permission to reach a shared or non-local environment.
+- Resolve a sibling fixture path by probing the declared sibling root and a documented fallback;
+  never embed one checkout layout as a constant.
+- Clean up by ownership, never by time window.
+
+## Declare environment postures
+
+Declare which local requirements depend on how the product is addressed (`addressing`) and how
+sign-in works locally (`authentication`). For example:
+
+```toml
+[environment]
+addressing = "hostname"
+authentication = "bypassed"
+posture_requirements = [
+  { requirement = "local-route-resolution", addressing = "hostname" },
+  { requirement = "local-session-access", authentication = "bypassed" },
+]
+```
+
+A product with no local sign-in declares `authentication = "none"`; no requirement needs a tag for
+it, and a requirement tagged with a sign-in value fails preflight. A plain localhost stack reached
+through leased ports declares:
+
+```toml
+[environment]
+addressing = "port"
+authentication = "none"
+posture_requirements = [{ requirement = "leased-localhost-ports", addressing = "port" }]
+```
+
+Use your actual requirement names. Each tag must match the selected value, and the selected
+`addressing` value, and any `authentication` value other than `none`, must each appear in at least
+one tag. Preflight refuses missing declarations, mismatched tags and selected values that no tag
+uses. Draft configurations may leave these fields out, but then cannot pass that gate. The check
+validates the declared tags; deciding which requirements need tags is still a maintainer's review.
+
+## Health and evidence
+
+`preflight` is the blocking gate; `doctor` reports the same checks without repairing anything.
+Before the first bring-up (`STATE_UNSEEDED`), while the stack sleeps
+(`STACK_NOT_RUNNING`), and for a cockpit that declares no runtime (`ENVIRONMENT_NOT_DECLARED`,
+`doctor` only), both still run every check that needs no running stack, such as Git state, sibling
+presence, the machine floor and the runtime measurement, and report the checks that need running
+services as not applicable; `preflight` never passes in those states. A check can pass, fail, be
+unavailable, or not apply to the declared setup, and an unavailable required check never becomes a
+pass because another check succeeded. Host capacity and runtime health need complete results from processes cockpit itself ran; when those results are missing, the
+result does not pass.
+
+`preflight` and `doctor` read current results without changing anything; `doctor` also previews
+generated surfaces to list overrides. They never run `sync`, seed data or advance lifecycle
+progress. Only bring-up runs those steps, as [Bring-up order](#bring-up-order) describes.
+
+`doctor` exits 0 with a report whenever it can read `cockpit.toml`, whatever the verdict, and exits
+2 when the configuration is missing or invalid. Its human output is one line per area followed by
+the diagnostics; `--json` carries the checks, declarations, override inspection and whether the
+generated files are current. `check --json` shows the generated-file detail.
+
+What the checks compare:
+
+- **Git remotes.** A declared sibling remote is compared with the remote selected by that
+  checkout's branch upstream; cockpit does not rewrite Git remotes. A checkout with no upstream has
+  nothing to compare, and the result says so. Once an upstream is selected, it must be available
+  and match; a missing or diverged upstream blocks the gate. Only an https or ssh `remote` has a
+  repository identity to compare. A `remote` that is a local path (not a URL or `host:path`) is
+  still cloned by `setup`, resolved against the siblings root, but `preflight` refuses it with a
+  reason: declare the hosted https or ssh remote, or remove `remote` and set `acquire = "none"`.
+  `init` never proposes a local-path remote.
+- **Surfaces.** Generated files must match the ownership manifest and stay within the guide line
+  cap and the built-in harness skill caps. Custom outputs and plugin bundle copies are checked for
+  being current, but no harness-side cap on their always-loaded size applies to them. Whether each
+  harness enforces the files is recorded in the [capability matrix](capability-matrix.md). Missing
+  or edited generated files block health: run `cockpit sync --config cockpit.toml`, then retry.
+- **Grants.** Directory grants are checked only when a sibling declares `mount = "always"`.
+- **Mounts and ports.** A runtime with no bind mounts passes as an exact empty mount comparison;
+  declared binds must match the current mounts exactly. Health on a running stack rechecks the
+  retained lease, current container identities, mounts and published listeners without reserving
+  sockets. Compose reports a `::` publication beside each `0.0.0.0` one, and some runtimes forward
+  only IPv4 loopback, so the `::` row is not required to listen while its `0.0.0.0` twin does; a
+  leased port that nothing publishes must stay free on both address families.
+- **Capacity.** Cold-start timing applies only to services that `up` actually started; read-only
+  health checks do not invent a new duration. The machine disk floor compares current free space
+  with an explicitly declared machine floor, independently of generated file sizes; without that
+  declaration, host-floor checks do not apply.
+
+`logs` reads one declared service from the selected running stack. `--tail` accepts 1 through 10000
+records, and `--since` limits the time range. Records keep their stream and restart details. A read
+without `--follow` has ten seconds and reports a timeout as a failure. `--follow` collects until you
+interrupt it, the container stops, or two hours pass; interrupting it in the CLI returns exit 130
+with the records collected before the process group stopped, and programmatic callers must supply an
+abort signal. Output is limited to 1 MiB of the container's stdout and 64 KiB of its stderr. Past
+that, `logs` keeps the newest whole records that fit, sets `truncated` to `true` in the JSON result
+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.
+
+## Where the decisions live
+
+Contributors looking for the source module behind each step should start at
+[Architecture](architecture.md#runtime-behavior) and the
+[environment code map](https://github.com/b0dea/cockpit/blob/main/AGENTS.md#environment-code-map).