@b00dea/cockpit 0.0.0-stage → 0.1.0

package/docs/cli-reference.md

@@ -0,0 +1,599 @@
+# CLI reference
+
+<!-- Generated by `npm run references`; edit its sources, not this file. -->
+
+This generated reference is for users looking up an exact command, flag, exit code or diagnostic. It is generated from the CLI, so it matches this version; `cockpit <command> --help` shows the same flags.
+
+Each diagnostic message names what failed and how to fix it. Codes whose remedy never changes are listed in [Troubleshooting](troubleshooting.md#codes-with-a-fixed-remedy).
+
+## cockpit init
+
+Preview, then accept, a first cockpit setup for one or more agent tools.
+
+Does not read `cockpit.toml`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--target` | string | unset |
+| `--registry` | string | unset |
+| `--interactive` | boolean | `false` |
+| `--json` | boolean | `false` |
+| `--answers` | string | unset |
+| `--accept-preview` | string | unset |
+| `--accept-defaults` | string | unset |
+| `--reset-answer` | string | unset |
+| `--accept-reset` | string | unset |
+| `--scaffold-compose` | string | unset |
+| `--command` | string | unset |
+| `--port` | string | unset |
+| `--with` | string | unset |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit setup
+
+Clone or locate the declared sibling repositories and link them.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--write-instruction-pointers` | boolean | `false` |
+| `--write-instruction-files` | boolean | `false` |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit sibling
+
+Add or remove a repository in cockpit.toml (sibling add, sibling remove).
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--create` | boolean | `false` |
+| `--from` | string | unset |
+| `--remote` | string | unset |
+| `--dir` | string | unset |
+| `--var` | string | unset |
+| `--purpose` | string | unset |
+| `--mount` | string | unset |
+| `--instruction-pointer` | boolean | `false` |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit tool
+
+Add or remove an agent tool in cockpit.toml (tool add, tool remove).
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--dry-run` | boolean | `false` |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit registry-resolve
+
+Turn a validated shell registry into data shell scripts can source.
+
+Does not read `cockpit.toml`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--registry` | string | unset |
+| `--siblings-root` | string | unset |
+| `--adoption` | string | unset |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit upgrade
+
+Move the exact cockpit pin to a newer version and re-run sync.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--dry-run` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit sync
+
+Write the Compose ownership override and agent files from cockpit.toml.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--dry-run` | boolean | `false` |
+| `--adopt` | string | unset |
+| `--interactive` | boolean | `false` |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit check
+
+Report generated files that no longer match cockpit.toml.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit selftest
+
+Test whether agent tools enforce the generated controls.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--probe-specifications` | string | unset |
+| `--write-probe-specifications` | string | unset |
+| `--interactive` | boolean | `false` |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit runtime
+
+Measure the local container runtime (runtime measure) and record the result for this machine.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--image` | string | unset |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit up
+
+Start or resume the declared environment.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit preflight
+
+Check that the environment is healthy and ready for work.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit session
+
+Keep the environment available for one command, then release it.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit logs
+
+Show recent logs for one declared service.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--service` | string | unset |
+| `--tail` | string | `"100"` |
+| `--since` | string | `"15m"` |
+| `--follow` | boolean | `false` |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit sleep
+
+Release this checkout and stop the stack if no other holder remains.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit down
+
+Stop and remove the stack (on the active local Docker context).
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit reset
+
+Preview a reset, then approve it interactively or apply it as [autonomy] reset allows (on the active local Docker context).
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--interactive` | boolean | `false` |
+| `--apply` | boolean | `false` |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit doctor
+
+Report environment problems without changing anything.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit test-run
+
+Run a declared product test gate and report which tests it selected.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--gate` | string | unset |
+| `--mode` | string | `"canonical"` |
+| `--select` | string | unset |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit work status
+
+Report each work order, its state and how it closed.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--work-order` | string | unset |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit work accept
+
+Accept a work order, or a change to an accepted one, as [work.gates] allows.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--work-order` | string | unset |
+| `--interactive` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit work check
+
+Run every criterion's check and the order's gates.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--work-order` | string | unset |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit work note
+
+Record a note on an order, or with --ask an open question that blocks it.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--work-order` | string | unset |
+| `--text` | string | unset |
+| `--ask` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit work answer
+
+Answer an open question on an order, as [work.gates] allows.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--work-order` | string | unset |
+| `--question` | string | unset |
+| `--text` | string | unset |
+| `--interactive` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit work grade
+
+Grade an accepted order the way [work] grading says.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--work-order` | string | unset |
+| `--verdict` | string | unset |
+| `--note` | string | unset |
+| `--evaluator` | string | unset |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit work signoff
+
+Close a graded order as done, or any open one as partial or abandoned.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--work-order` | string | unset |
+| `--partial` | boolean | `false` |
+| `--abandon` | boolean | `false` |
+| `--note` | string | unset |
+| `--interactive` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit work recover
+
+Inspect or remove a crashed command's work-order lock.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--work-order` | string | unset |
+| `--apply` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit work verify
+
+Check every record against its order; in CI, pass the steps gated on ci.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit grade
+
+Independently grade uncommitted work against a criteria file, with no work order.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--criteria` | string | unset |
+| `--evaluator` | string | unset |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit browser drive
+
+Drive the declared application browser surfaces.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--role` | string | unset |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |
+
+## cockpit browser screenshot
+
+Capture the declared application surfaces.
+
+Reads `cockpit.toml` from `--config`.
+
+| Flag | Type | Default |
+| --- | --- | --- |
+| `--config` | string | unset |
+| `--json` | boolean | `false` |
+| `--role` | string | unset |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | success |
+| 2 | failure |
+| 130 | cancelled |

package/docs/command-list.md

@@ -0,0 +1,51 @@
+# Command list
+
+<!-- Generated by `npm run references`; edit its sources, not this file. -->
+
+This generated index is for users choosing the command that owns their next operation. The command table supplies this list.
+
+## Set up
+
+- `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 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 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.
+
+## Generate and verify
+
+- `cockpit sync`: Write the Compose ownership override and agent files from cockpit.toml.
+- `cockpit check`: Report generated files that no longer match cockpit.toml.
+- `cockpit selftest`: Test whether agent tools enforce the generated controls.
+
+## Run the stack
+
+- `cockpit runtime`: Measure the local container runtime (runtime measure) and record the result for this machine.
+- `cockpit up`: Start or resume the declared environment.
+- `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 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).
+
+## Diagnose
+
+- `cockpit doctor`: Report environment problems without changing anything.
+
+## Test and grade
+
+- `cockpit test-run`: Run a declared product test gate and report which tests it selected.
+- `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 answer`: Answer an open question on an order, 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.
+- `cockpit work verify`: Check every record against its order; in CI, pass the steps gated on ci.
+- `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.