docs: full accuracy pass against the v3 surface

Audit-driven rewrite of 27 files: docs-ia and cli.md rebuilt (cli.md
defers exhaustive flags to the generated reference), 7 architecture
stale claims fixed, env/sessions/lifecycle corrected (secret-key
inheritance order, tmux-only daemon sessions, envelope error codes),
experimental banner standardized across all remote/gateway docs,
tickets reframed as opt-in. Every relative link and documented
command verified against the generated CLI reference.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: roodboi

.claude/skills/hack-init/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: hack-init
+description: >
+  Stand up or adopt hack in a project (agent-assisted onboarding).
+  Trigger when asked to set a repo up with hack, migrate a project onto
+  hack, or finish/repair a partial hack setup.
+---
+
+# hack init (agent-assisted onboarding)
+
+The full onboarding prompt is generated by the hack CLI — do not improvise the steps.
+
+1. Fetch the canonical onboarding prompt:
+   - With shell access: run `hack agent onboard` (works for new and existing projects).
+   - Without shell access: fetch the `hack-init` MCP prompt from the hack MCP server.
+2. Follow the printed prompt phase by phase (inventory, setup, platform nuances, running things, verification).
+3. Finish only when `hack doctor` is clean and every routable service responds.

.codex/skills/hack-init/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: hack-init
+description: >
+  Stand up or adopt hack in a project (agent-assisted onboarding).
+  Trigger when asked to set a repo up with hack, migrate a project onto
+  hack, or finish/repair a partial hack setup.
+---
+
+# hack init (agent-assisted onboarding)
+
+The full onboarding prompt is generated by the hack CLI — do not improvise the steps.
+
+1. Fetch the canonical onboarding prompt:
+   - With shell access: run `hack agent onboard` (works for new and existing projects).
+   - Without shell access: fetch the `hack-init` MCP prompt from the hack MCP server.
+2. Follow the printed prompt phase by phase (inventory, setup, platform nuances, running things, verification).
+3. Finish only when `hack doctor` is clean and every routable service responds.

README.md

@@ -19,9 +19,15 @@ supporting services at the same time.
 - Open stable local HTTPS URLs like `https://myapp.hack` with `hack open`.
 - Route service subdomains through local Caddy and trusted development TLS.
 - Resolve env overlays and secrets from `.hack/` and inject them into compose, host commands, and sessions.
+- In a linked git worktree, `hack up` defaults to a branch instance named after the worktree's git
+  branch (opt out with `worktree.auto_branch=false`, or target one explicitly with `--branch <name>`).
 - Keep tmux-backed project workspaces alive with `hack session`.
-- Diagnose Docker, DNS, TLS, env, lifecycle, and stale runtime state with `hack doctor`.
-- Track optional repo-local work with `hack tickets`.
+- Diagnose Docker, DNS, TLS, env, lifecycle, and stale runtime state with `hack doctor` /
+  `hack doctor --fix`.
+- Script and automate against a stable surface: `--no-interactive` (or `HACK_NO_INTERACTIVE=1`)
+  never prompts, and `up`/`down`/`restart`/`doctor --json` emit a `{ok, data | error: {code,
+  message}}` envelope; `NO_COLOR` disables ANSI output.
+- Track optional repo-local work with the opt-in `hack tickets` extension.
 - Use a slim macOS companion for local project status, controls, logs, and quick actions.
 
 Hack v3 is intentionally self-contained. The supported product is the local CLI/runtime and macOS
@@ -68,6 +74,9 @@ cd /path/to/project
 hack init
 ```
 
+Prefer an agent to drive setup? `hack init --with claude|codex|both` hands the onboarding prompt to
+an agent CLI for a new repo; `hack agent onboard` does the same for an existing project.
+
 Run it:
 
 ```bash
@@ -100,8 +109,12 @@ hack logs --pretty
 hack logs <service>
 hack exec <service> -- bun test
 hack run <service> -- bun db:migrate
+hack projects prune
 ```
 
+`hack projects prune` removes stale entries from the local project registry and stops orphaned
+containers.
+
 Host-side commands can use the same resolved project env:
 
 ```bash
@@ -117,9 +130,11 @@ hack session start <project>
 hack session exec <workspace> "bun test"
 ```
 
-Optional repo-local tickets:
+Optional repo-local tickets (opt-in extension, not part of default agent instructions — `hack tickets
+setup` is the one subcommand that bypasses the enable check and auto-enables the extension):
 
 ```bash
+hack tickets setup
 hack tickets create --title "Fix lifecycle cleanup"
 hack tickets list
 hack tickets show T-00001
@@ -137,7 +152,10 @@ Hack uses YAML env files in `.hack/` as the source of truth:
 .hack/hack.env.<overlay>.local.yaml
 ```
 
-Shared files can be committed. `*.local.yaml` files are worktree-local overrides.
+Shared files can be committed. `*.local.yaml` files are worktree-local overrides. Hack owns a
+committed `.hack/.gitignore` that keeps machine-local generated files (`.internal/`, `.branch/`,
+`.env`, `.env.state.json`, `hack.env*.local.yaml`) out of git; it self-heals on `init`/`up`, and if
+generated files ever leak into git, `hack doctor --fix` untracks them (files stay on disk).
 
 Runtime commands read the YAML model directly. Use `hack env materialize` only when an external tool
 needs a compatibility `.hack/.env` file on disk.
@@ -146,7 +164,8 @@ Secret key lookup is local-first:
 
 1. current checkout `.hack.secret.key`
 2. shared key under the git common dir for linked worktrees
-3. `HACK_ENV_SECRET_KEY`
+3. key inherited from the primary checkout's `.hack.secret.key` (linked worktrees)
+4. `HACK_ENV_SECRET_KEY`
 
 Use `HACK_ENV_SECRET_KEY` in CI and managed containers instead of copying `.hack.secret.key` into an
 image.
@@ -182,7 +201,9 @@ Use `hackdance/hack:slim` as a smaller base for Codex, CI, or managed containers
 `hack`, Bun, env resolution, sessions, and tickets without the full host stack.
 
 For reproducible remote or managed environments, install project dependencies normally, install Hack,
-and pass `HACK_ENV_SECRET_KEY` at runtime so encrypted project env can be resolved.
+and pass `HACK_ENV_SECRET_KEY` at runtime so encrypted project env can be resolved. Set `HACK_HOME`
+alongside it when you also want to redirect global state (registry, daemon, secrets) to an isolated
+root instead of `~/.hack`.
 
 Start with [Codex managed environments](./docs/guides/codex-managed-environments.md) for a concrete
 setup guide.

docs/README.md

@@ -10,12 +10,13 @@ The docs are split into three areas so the default path stays on core local work
 
 Use this path for the main product story:
 
-- local project setup
-- isolated runtime orchestration
+- local project setup (including agent-assisted onboarding via `hack init --with` / `hack agent onboard` — see the [agent-first setup guide](guides/agent-first-setup.md))
+- isolated runtime orchestration (including branch instances and linked worktrees)
 - stable local hostnames
 - env and secret management
 - lifecycle hooks
 - persistent sessions
+- diagnostics (`hack doctor` / `hack doctor --fix`)
 
 Start here if you want to understand and use `hack` without remote or beta complexity by default.
 
@@ -35,7 +36,7 @@ out of the default path.
 
 Use this path for:
 
-- full command reference
+- full command reference: [CLI overview](cli.md) plus the generated [CLI reference](reference/cli.md) (every command and flag)
 - extension configuration and authoring
 - tickets and integrations
 - gateway API and SDK details
@@ -45,14 +46,17 @@ This section is easy to find, but it does not lead the product story.
 ## Quick links
 
 - New to `hack`: [Core docs](core.md)
+- Setting up with a coding agent: [Agent-first setup](guides/agent-first-setup.md)
+- Looking for command or API details: [Extensions & reference](reference.md), including the generated [CLI reference](reference/cli.md)
 - Need unsupported experimental remote workflows: [Beta workflows](beta.md)
-- Looking for command or API details: [Extensions & reference](reference.md)
 - Need the bucket definitions: [Docs information architecture](docs-ia.md)
 
 ## Repo notes
 
-- Specs remain in `SPECS/` as working notes
+- Working notes and historical design docs live in `docs/plans/`; they are not the supported product contract
 - Root scripts orchestrate workspace tasks through Turbo
 - Package-local commands remain available via `bun run --cwd <workspace> <script>`
-- Agent-facing docs and setup output are generated from `src/agents/*` and `src/mcp/agent-docs.ts`; update those renderers when changing AGENTS/Codex/MCP guidance.
+- Agent-facing docs and setup output are generated from `src/agents/instruction-source.ts` via `src/agents/*` and `src/mcp/agent-docs.ts`; update the canonical source (not the rendered surfaces) when changing AGENTS/Codex/MCP guidance.
+- The generated [CLI reference](reference/cli.md) is rendered from the command spec (`bun run docs:cli-reference`); a drift test fails when it is stale.
+- End-to-end coverage that backs docs claims lives in `tests/e2e/` (`bun run test:e2e:local`).
 - `.factory/validation/` contains historical evidence from retired hosted/web/integration work and is not the current product contract.

docs/architecture.md

@@ -1,7 +1,8 @@
 ## System overview
 
 `hack` is a Bun CLI that writes per-project Compose files under `.hack/` and manages a machine-wide
-proxy, DNS helpers, and logging stack under `~/.hack/`.
+proxy, DNS helpers, and logging stack under `~/.hack/` (overridable via the `HACK_HOME` env var,
+which redirects all global state — registry, daemon, secrets — to another root).
 
 - **Caddy** (docker-proxy) routes `*.hack` based on container labels.
 - **CoreDNS** resolves `*.hack` inside containers to the Caddy IP, with `extra_hosts` mappings for resolver compatibility.
@@ -65,8 +66,11 @@ graph LR
   - `controlPlane.gateway.enabled` marks the project as gateway-capable
   - Optional overrides:
     - `.internal/compose.override.yml` (generated internal DNS/TLS injection)
-    - `.internal/extra-hosts.json` (user-managed extra_hosts merged into the override)
+    - `.internal/extra-hosts.json` — CLI-managed, not hand-edited (use
+      `hack internal extra-hosts set/unset/list`)
     - `.branch/compose.<branch>.override.yml` (branch builds)
+  - Everything under `.hack/.internal` is a hack-managed artifact; do not hand-edit generated files
+    there.
 
 
 ## Internal DNS + TLS (containers)
@@ -96,7 +100,9 @@ Projects can declare shareable env overlays and safely inject secrets into compo
 
 - Canonical env: `.hack/hack.env.default.yaml` plus optional `.hack/hack.env.<overlay>.yaml`
 - Compatibility output: `.hack/.env` only when explicitly materialized
-- Secret key: `.hack.secret.key` locally, or `HACK_ENV_SECRET_KEY` in CI/managed environments
+- Secret key: checkout-local `.hack.secret.key`, or — in a linked git worktree — inherited
+  automatically from the primary checkout through the shared git common dir; `HACK_ENV_SECRET_KEY`
+  covers CI/detached environments. `hack doctor` flags divergent keys across checkouts.
 
 At runtime, hack resolves the selected overlay and injects the effective env directly into compose and
 host-side command flows. For service-scoped values, hack still generates
@@ -152,7 +158,8 @@ sequenceDiagram
 - **compose**: fast, direct `docker compose logs`
 - **loki**: searchable history + LogQL filters
 
-NDJSON streaming (`hack logs --json`) emits `start`, `log`, and `end` events for MCP/TUI consumers.
+NDJSON streaming (`hack logs --json`) emits `start`, `log`, `error`, and `end` events for MCP/TUI
+consumers.
 
 Retention:
 - Loki retention is set in the global Loki config (`~/.hack/logging/loki.yaml`), default `168h` in the template.
@@ -208,33 +215,36 @@ graph LR
 The control plane keeps the core CLI minimal while adding features as extensions. `hackd` loads
 extension manifests and exposes their APIs; the CLI dispatches extension commands via `hack x`.
 
-- **Gateway**: optional HTTP/WS access to `hackd` (localhost by default).
-- **Supervisor**: job execution + streaming for agents.
+Builtin extensions: **Tickets** (opt-in local ticket store — disabled by default, requires enabling
+before use), **Supervisor** (job execution + streaming for agents), **Gateway** (optional HTTP/WS
+access to `hackd`), **Cloudflare**, and **Tailscale** (exposure/tunnel helpers).
+
+> Gateway, remote, node, and dispatch surfaces are experimental and unsupported. They are hidden
+> from default `hack help` (use `hack help --all` to see them) and print a warning when invoked.
+> See [Beta workflows](beta.md) and [Gateway API](gateway-api.md) for details — this doc only
+> summarizes where they fit in the system.
 
 ```mermaid
 graph LR
   CLI["hack CLI"] --> Hackd["hackd"]
   Hackd --> ExtMgr["ExtensionManager"]
   ExtMgr --> Gateway["Gateway"]
   ExtMgr --> Supervisor["Supervisor"]
-  ExtMgr --> Tickets["Tickets"]
+  ExtMgr --> Tickets["Tickets (opt-in)"]
+  ExtMgr --> Cloudflare["Cloudflare"]
+  ExtMgr --> Tailscale["Tailscale"]
   Remote["Remote client"] -->|HTTP/WS| Gateway
   Gateway --> Hackd
 ```
 
-### Gateway API + remote workflows
+### Gateway API + remote workflows (unsupported experimental)
 
-The gateway exposes:
+Summary only — see `gateway-api.md` for full usage, security posture, and end-to-end examples:
 - `GET /v1/projects` with `project_id` for remote workflow routing
 - job execution + streaming (`/control-plane/projects/:id/jobs`)
 - PTY-backed shells (`/control-plane/projects/:id/shells`, WS stream)
-
-Current gateway routing:
-- One gateway instance is active per machine (global config).
-- Projects opt in with `controlPlane.gateway.enabled` in their project config.
-- Remote clients route by `project_id` in the API paths.
-
-For full usage, security posture, and end-to-end examples, see `gateway-api.md`.
+- One gateway instance is active per machine (global config); projects opt in with
+  `controlPlane.gateway.enabled`; remote clients route by `project_id` in the API paths.
 
 ## Branch builds
 
@@ -245,9 +255,18 @@ For full usage, security posture, and end-to-end examples, see `gateway-api.md`.
 
 This enables parallel worktrees without port or hostname collisions.
 
+In a linked git worktree, `hack up` defaults to a branch instance named after the worktree's git
+branch instead of requiring an explicit `--branch` — opt out with config `worktree.auto_branch=false`
+or pass an explicit `--branch`. The secret key for a linked worktree is inherited automatically from
+the primary checkout through the shared git common dir (see "Project env + secrets" above), and
+`hack doctor` checks for divergent secret keys and `dev_host` collisions across checkouts sharing the
+same repo.
+
 ## Files and directories
 
-- `~/.hack/`
+- `~/.hack/` (default; override the whole root with `HACK_HOME`)
+  - `hack.config.json` (global config: control-plane defaults, gateway bind/port/allowWrites,
+    extension settings)
   - `daemon/hackd.sock`
   - `daemon/hackd.pid`
   - `daemon/hackd.log`
@@ -260,13 +279,24 @@ This enables parallel worktrees without port or hostname collisions.
   - `schemas/hack.config.schema.json`
   - `schemas/hack.branches.schema.json`
   - `certs/` (mkcert output for non-Caddy services)
-  - `projects.json` (best-effort registry)
+  - `projects.json` (best-effort registry; `hack projects prune` removes stale entries and stops
+    orphaned containers)
 
 - `<repo>/.hack/`
   - `docker-compose.yml`
   - `hack.config.json`
   - `hack.branches.json` (optional)
+  - `.gitignore` (committed, self-healing on `init`/`up`; covers machine-local generated files —
+    `.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`. If generated files
+    leaked into git, `hack doctor --fix` untracks them without deleting them from disk.)
+  - `hack.env.default.yaml` plus optional `hack.env.<overlay>.yaml` (committed env)
+  - `hack.env.local.yaml` / `hack.env.<overlay>.local.yaml` (worktree-local overrides)
+  - `.env.state.json`
+  - `.env` (optional, only when explicitly materialized)
   - `.internal/compose.override.yml`
+  - `.internal/compose.env.override.yml`
+  - `.internal/extra-hosts.json`
+  - `.internal/lifecycle/state.json` and `.internal/lifecycle/*.log`
   - `.branch/compose.<branch>.override.yml`
 
 ## Key design choices

docs/beta.md

@@ -1,5 +1,7 @@
 # Beta Workflows
 
+> **Status: unsupported experimental.** These surfaces are source-available but outside the supported v3 product contract. They are hidden from default `hack --help` (see `hack help --all`) and print a warning when invoked.
+
 This section holds unsupported experimental remote workflows.
 
 Start in [Core docs](core.md) first if you are new to `hack`. Beta workflows build on the core