@b00dea/cockpit 0.0.0-stage → 0.1.1

package/docs/extending.md

@@ -0,0 +1,43 @@
+# Extending cockpit
+
+This page is for integrators adding product-specific behaviour to a cockpit: which declaration to
+use for each need, and how to keep your own build logic beside cockpit. Cockpit is not a plugin
+host. An extension stays ordinary version-controlled product code; cockpit manages only the
+generated files listed in its ownership manifest.
+
+## Choose the seam
+
+| Need | What to declare | Why this seam exists | How to use it |
+| --- | --- | --- | --- |
+| Product instructions, skills, agents or hooks | `[[surfaces.overlays]]` | Add product context without forking shipped surfaces. | Give the overlay a stable name, feature and complete source bytes. Use `replaces` only for an intentional core replacement. |
+| Existing Compose stack | `[environment].compose_files` | Keep your own Compose file as the source of truth. | Declare its paths and port variables; cockpit writes only its label override. |
+| Starting Compose file | `cockpit init --scaffold-compose` | Give a small app with no Compose file one it then owns. | Run it once; edit the written `compose.yml` like any other product file. |
+| Service health | a Compose `healthcheck` | Make readiness a checked property instead of a delay. | Give every service a healthcheck; `check` warns on one without. |
+| Demo data | `environment.seed` with `resettable_volumes` | Fill the data volumes once the stack is healthy, and again after they are recreated. | Point it at the product's own seed or restore command; write that command to be rerun. |
+| Vendor stubs, TLS | services in your Compose file | Keep the stack plain Compose. | Follow [Compose patterns](compose-patterns.md). |
+| External tool server | `[mcp]` and `sibling[].derives.mcp_sources` | Declare one server once and generate it for every harness that supports MCP. | Point a sibling at its MCP declaration file (a JSON `mcpServers` object) and approve the server centrally by the digest `sync` reports for its declaration; keep credentials outside tracked files. |
+| Extra guard policy | `[[guards.allow]]` and `[[guards.deny]]` | Refine prompts for exact product commands while preserving cockpit's hard boundaries. | Match an exact command, starting with its executable, and state the reason. Prefer a deny with a safe fix when a known alternative exists. |
+| Your own automation | Files beside `cockpit.toml` | Keep bespoke build, test and release logic usable without cockpit. | Put scripts, task-runner files and Compose inputs outside generated paths, then refer to them from declarations and overlays. |
+| Additional harness | `[[surfaces.harnesses]]` | Record a complete, honest capability matrix without pretending an unsupported feature works. | Declare every feature with its spelling in that tool or the reason it is unavailable; verify each claimed control beside a broken control. |
+
+## Build beside cockpit
+
+Keep the product's `Makefile`, task runner or scripts your own, so people and CI can run them
+without cockpit:
+
+1. Expose a narrow target, such as `make verify`.
+2. Add a skill overlay that tells agents when to use it. Put the procedure in its own file with
+   `loading: pull` and `budget: uncapped` frontmatter, so agents load it only when needed.
+3. Add an exact guard allow for the target, with a reason.
+
+The [extended example](https://github.com/b0dea/cockpit/blob/main/examples/extended/README.md) shows this pattern.
+
+Generated ownership is the upgrade boundary. A later `sync` may replace files cockpit generated,
+and reports a changed overridden core declaration, but it never adopts or overwrites the files
+beside them. Preview `cockpit sync --dry-run` after changing the installed version.
+
+Give generated outputs portable relative names, so one committed checkout works on every
+filesystem. Avoid reserved device names, stream syntax, trailing dots or spaces, and directory names
+that differ only by case or Unicode normalization. Keep every path component within 255 UTF-16
+code units and 255 UTF-8 bytes. To fix an invalid overlay output, rename it and review
+`cockpit sync --dry-run` before publishing.

package/docs/faq.md

@@ -0,0 +1,113 @@
+# FAQ
+
+Short answers to the questions people ask before and while adopting cockpit, each linking to the
+page with the detail.
+
+## What is cockpit, in one sentence?
+
+The local environment coding agents work from: every repository of your product in reach, the
+product running on the checkouts they edit, the same instructions, skills, guard and permissions in
+Claude Code, Codex CLI and OpenCode, and work orders checked against criteria you set and graded
+the way you choose: by a fresh read-only agent run, by the checks alone, or by the agent's own report.
+
+## When should I not use cockpit?
+
+- Your product is one repository and you only need a reproducible toolchain: a dev container or
+  Devbox is simpler.
+- You need isolation from untrusted code: cockpit is not a sandbox.
+- You are on native Windows: every command stops at startup with `CLI_PLATFORM_UNSUPPORTED`,
+  before reading or writing anything, because process management, file publication and the shell
+  guards assume macOS or Linux. Under WSL2 cockpit should behave as on Linux, but that is untested.
+- You need a stable tool: cockpit is pre-1.0, and its commands, configuration and generated
+  layout can still change without a migration path; see
+  [Status and limits](https://github.com/b0dea/cockpit/blob/main/README.md#status-and-limits).
+
+The full list of non-goals, with reasons, is in [Architecture](architecture.md#non-goals).
+
+## How do I install it?
+
+As an exact-pinned, project-local development dependency of the repository that holds the cockpit.
+[Install cockpit](getting-started.md#install-cockpit) has the steps, including the install from
+source.
+
+## Do I have to use every agent tool?
+
+No. `[surfaces] tools` in `cockpit.toml` lists the tools `sync` writes and `check` compares, and
+one tool is a complete setup. It defaults to Claude Code, Codex CLI and OpenCode; `init --target`
+writes the tools you choose (`--target claudecode` or `--target claudecode,opencode`), and
+`cockpit tool add <tool>` or `tool remove <tool>` changes the list later. Custom harnesses can be
+declared under `[surfaces]`; see [Harness surfaces](harness-surfaces.md#capability-states).
+
+## Are the guards actually enforced?
+
+It depends on the tool. cockpit's guard script denies the operation whenever a tool runs it, and
+fails closed on input it cannot read; what differs is whether the tool runs it. The
+[capability matrix](capability-matrix.md) records each tool's state and when it was last probed:
+
+- Claude Code: `enforced`. Its hook refused a push to a protected branch; without the hook, the
+  same push went through. Its own Read tool never reaches the hook, so generated `Read` deny rules
+  cover secrets there.
+- OpenCode: `enforced`. Its plugin refused a protected push and a native read of a secrets file.
+- Codex CLI: `enforced` only after a person trusts the hook on that machine. Codex silently skips
+  an untrusted hook, and `cockpit doctor` and `cockpit check` report `CODEX_HOOK_UNTRUSTED` once Codex
+  has run on the machine (a Codex home exists) and until the hook is trusted; see [Trust the Codex hook](harness-surfaces.md#trust-the-codex-hook).
+- Cursor and Grok Build: no guard. cockpit writes their files but installs no hook, and nobody has
+  confirmed those tools load them.
+
+`cockpit selftest` checks the supported tools installed on your machine, using probe commands you
+write for each tool; [Skills and selftest evidence](harness-surfaces.md#skills-and-selftest-evidence)
+walks through it.
+
+## Does cockpit change my product code?
+
+Only in paths the configuration declares and a preview you accepted shows. cockpit writes generated
+files into the cockpit checkout, plus declared outputs in a sibling repository such as an
+environment template, and records every file it wrote. `setup` can clone a missing sibling from
+its declared remote. It never rewrites Git remotes or edits undeclared files.
+
+## Can two agents use the same machine at once?
+
+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?
+
+`setup` inspects declared secret-file paths without reading or copying their contents. `sync`
+creates an ignore boundary for central secret sources before any exist, and the guards deny
+agents editing or staging declared environment and secret files. None of this isolates secrets
+from malicious code running as your user. See
+[Secret sources and environment schemas](environment.md#secret-sources-and-environment-schemas).
+
+## Does cockpit send data anywhere?
+
+There is no telemetry. The only request cockpit makes on its own is `doctor` reading the latest
+published version from the npm registry, skipped when `CI` or `NO_UPDATE_NOTIFIER` is set.
+Docker, Git and your product's own commands make whatever requests they normally make.
+
+## Why is the configuration so long?
+
+Because every value says where it came from: probes, operations and decisions carry a `provenance`
+table with the source file, the date it was observed, and whether it was declared or inferred.
+The structure underneath is small; the [tutorial](tutorial.md#read-the-configuration) walks
+through it.
+
+## Can I add my own rules and skills?
+
+Yes, through [overlays](concepts.md#cockpit-surface-overlay) under `[surfaces].overlays`.
+Replacing a built-in item requires naming it and its SHA-256, so an upstream change to it is
+reported before you accept new output. See
+[Harness surfaces](harness-surfaces.md#ownership-and-extension).
+
+## A command failed with a diagnostic code. What now?
+
+Every refusal prints a code, the target it applies to and, where one exists, a fix. Look the code
+up in [Troubleshooting](troubleshooting.md), and after a repair run
+`cockpit doctor --config ./cockpit.toml --json` to see the current state.
+
+## Can my AI agent contribute to cockpit itself?
+
+Yes. Point it at AGENTS.md in the repository root, the working guide for agents, and at
+[CONTRIBUTING.md](https://github.com/b0dea/cockpit/blob/main/CONTRIBUTING.md#verification) for the verification gates.