From 8f873de17de47190a33bffe572be568efdb331b9 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 22:25:27 +0000
Subject: [PATCH 001/134] feat: document env portability trust model

---
 docs/env.md                                   |  30 ++
 ...ortability-and-secret-management-design.md | 400 ++++++++++++++++++
 ...-portability-and-secret-management-plan.md | 278 ++++++++++++
 src/commands/env.ts                           |  54 +++
 src/lib/hack-env.ts                           |  50 +++
 tests/env-backend-command.test.ts             | 107 +++++
 6 files changed, 919 insertions(+)
 create mode 100644 docs/plans/2026-03-13-env-portability-and-secret-management-design.md
 create mode 100644 docs/plans/2026-03-13-env-portability-and-secret-management-plan.md

diff --git a/docs/env.md b/docs/env.md
index 3314d7971..02905d506 100644
--- a/docs/env.md
+++ b/docs/env.md
@@ -2,6 +2,28 @@
 
 hack supports a project-scoped env contract (shareable, no values) plus safe secret storage for local development.
 
+## Trust model at a glance
+
+Hack currently has three env layers, and they should be understood separately:
+
+- Contract: `.hack/hack.env.json` defines what keys exist and how they should materialize locally.
+- Local values: `.hack/.env` stores local plaintext values for `plain_env`.
+- Local secrets: the configured secret backend stores secret values for keys that should not live in `.hack/.env`.
+
+Current status:
+
+- The contract is portable and safe to commit.
+- Local values and local secrets are not automatically portable across machines.
+- Remote env portability is a follow-on design, not the current default.
+
+Planned direction:
+
+- portable env values will live in an immutable encrypted bundle artifact
+- bundle access will be controlled through explicit project-key sharing
+- applying a bundle will still write values back into `.hack/.env` and the configured local secret backend so existing runtime behavior stays intact
+
+See `docs/plans/2026-03-13-env-portability-and-secret-management-design.md` for the full portable env and key-sharing model.
+
 ## Files and storage
 
 - `.hack/hack.env.json` (committed): declares env vars, required vs optional, per-service scope, and where values should come from.
@@ -34,6 +56,7 @@ hack supports a project-scoped env contract (shareable, no values) plus safe sec
 ```
 
 Fields:
+
 - `key`: uppercase snake-case env var name (e.g. `AWS_PROFILE`).
 - `required`: if true, `hack up/run/restart` fails when missing (for targeted services).
 - `source`:
@@ -46,6 +69,7 @@ Fields:
 
 - `hack env list [--json] [--show-secrets]`
   - shows contract + resolution state
+  - includes a storage summary for the committed contract, local `.hack/.env`, configured secret backend, and current portable-state status
   - exits `1` if required vars are missing
 - `hack env set KEY=VALUE`
   - writes to `.hack/.env`
@@ -59,6 +83,7 @@ Fields:
   - sets global backend strategy for multi-node/env secret storage
 
 Notes:
+
 - `hack env set` also supports interactive prompting when `KEY` or `VALUE` is omitted.
 - Keychain mode uses service name `hack-<projectName>` (project name from `.hack/hack.config.json`).
 - Encrypted-file mode uses `HACK_SECRETS_FILE_KEY` (if set) before keychain key lookup (`hack-secrets-backend/encrypted-file-key`).
@@ -89,6 +114,7 @@ Global config supports backend selection for secret portability:
 ```
 
 Fields:
+
 - `backend`: `keychain` | `encrypted_file` | `cloud`.
 - `allowEnvAuthRefs`: allow `env:VAR_NAME` auth/secret references for node/controller workflows.
 - `encryptedFile.path`: target path for encrypted local store mode.
@@ -106,22 +132,26 @@ When you run `hack up`, `hack restart`, or `hack run`, hack:
 4. Invokes `docker compose` with an environment that includes resolved values (including secret backend values).
 
 Security posture:
+
 - Secret values are never written into `.hack/` YAML files.
 - Plain env values live in `.hack/.env` (expected to be gitignored in most repos).
 
 ## Remote node secret behavior
 
 Current behavior (today):
+
 - Node auth tokens and extension auth refs are stored through the configured secret backend.
 - `env:VAR_NAME` auth refs are allowed only when `controlPlane.secrets.allowEnvAuthRefs=true`.
 - Remote dispatch/workspace bootstrap does **not** automatically copy all host env values to remote nodes.
 
 Recommended setup:
+
 - Keep controller secrets in `keychain` or `encrypted_file` backend (not shell env).
 - Configure each remote node to use the same secret backend strategy where possible.
 - Use project env contract (`.hack/hack.env.json`) to make required keys explicit before runs.
 
 Planned direction:
+
 - Add an explicit host-to-node secret sync command with least-privilege scoping, encrypted payload delivery, and audit events per run.
 
 ## Daemon/gateway API (UI integration)
diff --git a/docs/plans/2026-03-13-env-portability-and-secret-management-design.md b/docs/plans/2026-03-13-env-portability-and-secret-management-design.md
new file mode 100644
index 000000000..29664444c
--- /dev/null
+++ b/docs/plans/2026-03-13-env-portability-and-secret-management-design.md
@@ -0,0 +1,400 @@
+# Env Portability And Secret Management Design
+
+## Context
+
+Hack already has the beginnings of a useful env system:
+
+- `.hack/hack.env.json` defines the committed project env contract
+- `.hack/.env` stores local non-secret values
+- the configured secret backend stores local secret values
+- `hack env` can list, set, unset, and resolve values for runtime injection
+
+What is still missing is an explicit product model for portability, sharing, recovery, and operator trust. Today the user can understand the local contract, but not yet the full lifecycle of:
+
+- where portable values would live
+- how encrypted values are modeled
+- how another human or machine should gain access
+- how key loss or rotation should behave
+- how all of this preserves `.env` compatibility instead of replacing it
+
+This design defines that product boundary for the full stream. It treats the existing remote encrypted env portability plan as one child slice inside the larger env portability and secret-management program.
+
+## Goals
+
+- Make the storage model explicit for committed, local, and portable env state.
+- Define a portable project env artifact schema that is independent from any one device or local keychain.
+- Define a separate encrypted key-sharing model so access is explicit and reviewable.
+- Make rotation and recovery behavior safe enough to explain before it ships.
+- Preserve `.env` compatibility and existing backend choices instead of forcing a new runtime model.
+- Break the work into coherent child streams that can be implemented independently.
+
+## Non-Goals
+
+- Do not make local-only Hack usage require Hack account auth.
+- Do not turn the broker into a plaintext env editor.
+- Do not silently copy host env values to remote nodes.
+- Do not auto-share env access to every org or team member.
+- Do not replace `.hack/hack.env.json` with a value-bearing committed file.
+
+## Approved Product Rules
+
+### Local remains the default
+
+The current local behavior remains valid:
+
+- `.hack/hack.env.json` is the committed contract
+- `.hack/.env` remains the local plaintext materialization for non-secret values
+- the configured secret backend remains the local materialization for secret values
+- `hack up`, `hack run`, and `hack restart` continue resolving local values first
+
+Portable env management is opt-in per project binding. If a user never enables it, Hack should continue behaving as a local-only tool.
+
+### Portability is a separate value artifact
+
+The committed contract and the portable value artifact are different objects:
+
+- `.hack/hack.env.json` describes what keys exist and how they should materialize locally
+- the portable artifact stores encrypted values plus ownership and lineage metadata
+
+This avoids putting secrets in git while still making the portable state explicit and inspectable.
+
+### Shared or remote state requires Hack account ownership
+
+Portable env bundles are owned by a Hack scope:
+
+- user
+- organization
+- team
+
+Provider identity is not the owner. A GitHub login method, Linear profile, or local keychain identity is not the durable ownership layer for portable env state.
+
+## Explicit Storage Model
+
+Hack should describe env storage in three layers.
+
+### 1. Committed contract
+
+File:
+
+- `.hack/hack.env.json`
+
+Purpose:
+
+- declares required keys
+- declares service scoping
+- declares local materialization intent
+
+This file stays safe to commit because it contains no values.
+
+### 2. Local materialization
+
+Files/backends:
+
+- `.hack/.env` for `plain_env`
+- configured secret backend for secret material
+
+Purpose:
+
+- stores the values a local machine actually uses for runtime injection
+- stays compatible with existing Docker Compose env handling and local debugging workflows
+
+### 3. Portable encrypted state
+
+Artifact:
+
+- `hack.project-env-bundle/v1`
+
+Purpose:
+
+- stores an immutable encrypted snapshot of project env values
+- supports broker storage and explicit export/import
+- is portable across machines because it does not rely on one local keychain as the only durable copy
+
+Portable state must never be described as "the `.env` file in the cloud." It is an encrypted artifact that can be applied back into `.hack/.env` and the local secret backend.
+
+## Portable Artifact Schema
+
+The portable value artifact is one immutable bundle version. It may live in the broker and may also be exportable as a file for backup or manual transport.
+
+Recommended schema:
+
+```json
+{
+  "$schema": "https://schemas.hack/hack.project-env-bundle.schema.json",
+  "kind": "hack.project-env-bundle",
+  "version": 1,
+  "bundleId": "peb_01JQ...",
+  "projectBindingKey": "user:usr_123/my-project/default",
+  "environment": "default",
+  "ownerScope": {
+    "type": "user",
+    "id": "usr_123"
+  },
+  "createdAt": "2026-03-13T12:00:00.000Z",
+  "createdBy": "usr_123",
+  "supersedesBundleId": null,
+  "contract": {
+    "path": ".hack/hack.env.json",
+    "version": 1,
+    "digest": "sha256:2e7d..."
+  },
+  "crypto": {
+    "scheme": "project-key-envelope-v1",
+    "projectKeyId": "pek_01JQ...",
+    "bundleKeyId": "bek_01JQ...",
+    "bundleKeyWrap": {
+      "wrapType": "project_key",
+      "wrappedBundleKey": "base64..."
+    },
+    "entryAlgorithm": "aes-256-gcm"
+  },
+  "entries": [
+    {
+      "key": "DATABASE_URL",
+      "required": true,
+      "services": ["api", "worker"],
+      "materialization": {
+        "type": "secret_backend",
+        "backendHint": "preserve_current"
+      },
+      "ciphertext": "base64...",
+      "iv": "base64...",
+      "tag": "base64...",
+      "digest": "sha256:8b1a..."
+    },
+    {
+      "key": "AWS_PROFILE",
+      "required": true,
+      "services": ["api"],
+      "materialization": {
+        "type": "plain_env"
+      },
+      "ciphertext": "base64...",
+      "iv": "base64...",
+      "tag": "base64...",
+      "digest": "sha256:3a7d..."
+    }
+  ]
+}
+```
+
+### Schema rules
+
+- Every bundle version is immutable.
+- All values are encrypted in the bundle, including values that will later be written into `.hack/.env`.
+- `materialization.type` tells Hack where to place the decrypted value during apply:
+  - `plain_env` writes to `.hack/.env`
+  - `secret_backend` writes to the configured secret backend
+- `backendHint` is advisory only. It should never force a backend switch during apply.
+- `projectBindingKey` is stable across versions and is the join point for bundle history, key shares, and audit.
+
+## Encrypted Entry And Key Model
+
+The stream needs two different key concepts.
+
+### Project key
+
+The project key is a long-lived wrapping key for one project binding. It is not the value-encryption key for every entry directly. Its job is to make sharing, rotation, and recovery explicit.
+
+Responsibilities:
+
+- wraps each bundle version key
+- is the object shared with collaborators or recovery targets
+- can be rotated without forcing an operator to hand-edit every env value
+
+### Bundle key
+
+Each bundle version gets a fresh random bundle key.
+
+Responsibilities:
+
+- encrypts each entry payload in the bundle
+- is wrapped by the project key
+- is discarded from plaintext after publish/apply completes
+
+This separation keeps snapshot publication simple and makes project-key sharing possible without treating one giant ciphertext blob as the only unit of control.
+
+## Manual Project-Key Sharing Model
+
+Sharing access to a portable project env must be manual and additive. The portable bundle and the key share record are separate objects.
+
+Recommended key-share schema:
+
+```json
+{
+  "$schema": "https://schemas.hack/hack.project-env-key-share.schema.json",
+  "kind": "hack.project-env-key-share",
+  "version": 1,
+  "shareId": "pks_01JQ...",
+  "projectBindingKey": "user:usr_123/my-project/default",
+  "projectKeyId": "pek_01JQ...",
+  "recipient": {
+    "type": "user",
+    "id": "usr_456"
+  },
+  "wrapMethod": "x25519-sealed-box-v1",
+  "wrappedProjectKey": "base64...",
+  "createdAt": "2026-03-13T12:15:00.000Z",
+  "createdBy": "usr_123",
+  "revokedAt": null,
+  "lastUsedAt": null
+}
+```
+
+### Sharing rules
+
+- Sharing happens one recipient at a time.
+- The broker may store key-share records, but it should not auto-grant them based on org membership alone.
+- A user or team receiving access gets a wrapped project key, not plaintext env values.
+- Revocation removes future access by invalidating the share record and blocking fresh unwrap operations. It does not rewrite old local materializations that a recipient already applied.
+
+Manual sharing is the explicit trust boundary. If a project owner never creates a share, nobody else gets access by default.
+
+## Rotation And Recovery Behavior
+
+The program needs three different operator actions, with different UX and audit implications.
+
+### 1. Value rotation
+
+Use when actual env values changed.
+
+Behavior:
+
+- publish a new immutable bundle version
+- mint a fresh bundle key
+- keep the same project key unless crypto rotation is also requested
+
+### 2. Share rotation
+
+Use when recipients change.
+
+Behavior:
+
+- add or revoke key-share records
+- do not rewrite bundle values
+- do not require env republish unless an operator explicitly wants a new bundle
+
+### 3. Project-key rotation
+
+Use when the project key itself is suspected compromised or when the owner wants to re-anchor trust.
+
+Behavior:
+
+- mint a new project key
+- re-wrap the latest active bundle keys to the new project key
+- require explicit regeneration of all active key-share records
+- keep prior project-key lineage in audit metadata
+
+### Recovery policy
+
+Hack should not silently escrow plaintext secrets. Recovery must be explicit.
+
+Required rule:
+
+- portable env enablement must require at least one recovery path before the operator can delete the only local authority
+
+Allowed recovery paths:
+
+- an encrypted recovery package exported by the operator
+- a second admin/owner key share
+- a designated recovery recipient created manually
+
+Unsafe behavior to reject:
+
+- deleting the last active owner share with no recovery path
+- rotating the project key while leaving no valid recipient or backup
+- revoking the last usable recovery share without an explicit forced override
+
+## `.env` Compatibility And Backend UX
+
+Portability should preserve the current local runtime model instead of replacing it.
+
+### Apply behavior
+
+When a portable bundle is applied locally:
+
+- entries with `materialization.type = plain_env` are written to `.hack/.env`
+- entries with `materialization.type = secret_backend` are written to the configured secret backend
+- the contract file remains `.hack/hack.env.json`
+
+This means portability changes where values are sourced from, not how local services consume them.
+
+### UX rule
+
+Hack should always show three things separately:
+
+- contract location
+- local value location
+- portable copy state
+
+Example user-facing explanations:
+
+- `AWS_PROFILE`:
+  - contract: `.hack/hack.env.json`
+  - local value: `.hack/.env`
+  - portable copy: enabled, latest bundle `peb_...`
+- `DATABASE_URL`:
+  - contract: `.hack/hack.env.json`
+  - local value: `keychain`
+  - portable copy: enabled, protected by project key `pek_...`
+
+That separation is what makes the trust model understandable.
+
+## Child Streams
+
+The program should be implemented as five child streams.
+
+### Stream 1: Current-state trust model and operator UX
+
+Deliverables:
+
+- clearer docs for current local storage
+- CLI or UI surfaces that explain contract vs local vs portable state
+- explicit trust-boundary copy for backends and remote ownership
+
+### Stream 2: Portable bundle registry and project binding
+
+Deliverables:
+
+- broker schema for bundle versions and bindings
+- CLI publish/list/pull/apply flows
+- immutable version lineage and audit metadata
+
+This stream is the direct successor to the existing remote encrypted env portability plan.
+
+### Stream 3: Manual project-key sharing
+
+Deliverables:
+
+- key-share schema and broker routes
+- share and revoke flows
+- audit for recipient grants and use
+
+### Stream 4: Rotation and recovery safeguards
+
+Deliverables:
+
+- project-key rotation
+- recovery package flow
+- last-share / last-recovery-path guardrails
+
+### Stream 5: `.env` compatibility and desktop/backend UX
+
+Deliverables:
+
+- consistent apply behavior into `.hack/.env` and configured secret backend
+- visibility-first CLI and macOS UX
+- explicit backend hints and warnings when apply target differs from publish
+
+## Open Questions
+
+- Should export/import use the same portable bundle JSON as broker storage, or a wrapped archive that contains both bundle metadata and selected key shares?
+- Do we want a single default environment first, or named environments such as `default`, `staging`, and `prod` in the first release?
+- Should org-owned project keys require more than one active admin share before rotation/revocation is allowed?
+- How much audit retention is required before remote portability is safe to recommend broadly?
+
+## Links
+
+- `docs/env.md`
+- `docs/plans/2026-03-06-remote-encrypted-project-env-portability-plan.md`
+- `docs/plans/2026-03-06-hack-account-auth-and-provider-ux-design.md`
diff --git a/docs/plans/2026-03-13-env-portability-and-secret-management-plan.md b/docs/plans/2026-03-13-env-portability-and-secret-management-plan.md
new file mode 100644
index 000000000..fb6bca6c0
--- /dev/null
+++ b/docs/plans/2026-03-13-env-portability-and-secret-management-plan.md
@@ -0,0 +1,278 @@
+# Env Portability And Secret Management Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Deliver portable project env management as an explicit, auditable product made of immutable encrypted bundles, manual project-key sharing, safe rotation and recovery, and preserved local `.env` compatibility.
+
+**Architecture:** Keep the current local env contract and local materialization model intact, then add an owner-scoped broker registry for immutable portable bundles plus separate key-share records. Use bundle keys for per-version encryption, a project key for access control and recovery, and visibility-first CLI/macOS UX so users can always tell contract, local materialization, and portable state apart.
+
+**Tech Stack:** Bun, TypeScript, Hack CLI `env` commands, auth-broker, Better Auth ownership, Drizzle/Postgres, macOS SwiftUI follow-on UX, existing secret backend abstractions.
+
+---
+
+### Task 1: Lock current-state storage and trust-model UX
+
+**Files:**
+
+- Modify: `docs/env.md`
+- Modify: `src/commands/env.ts`
+- Modify: `src/lib/hack-env.ts`
+- Test: `tests/env-command.test.ts` or the nearest existing env command test file after inspection
+
+**Step 1: Write the failing test**
+
+Add env command coverage for an explain/status surface that distinguishes:
+
+- committed contract location
+- local plaintext value location
+- local secret backend location
+- portable-state availability
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/env-command.test.ts` Expected: FAIL because the env command output does not yet expose the full trust model.
+
+**Step 3: Write minimal implementation**
+
+Add a visibility-first env status/explain output so operators can see where each value lives and what trust boundary applies before any remote portability is enabled.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/env-command.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add docs/env.md src/commands/env.ts src/lib/hack-env.ts tests/env-command.test.ts
+git commit -m "feat: explain env storage and trust boundaries"
+```
+
+### Task 2: Add portable bundle and binding schema
+
+**Files:**
+
+- Modify: `packages/db/src/schema/core.ts`
+- Modify: `services/auth-broker/src/db/schema.ts`
+- Create: `services/auth-broker/src/modules/project-envs/service.ts`
+- Test: `services/auth-broker/tests/index.test.ts`
+- Docs: `docs/plans/2026-03-06-remote-encrypted-project-env-portability-plan.md`
+
+**Step 1: Write the failing test**
+
+Add broker storage tests for:
+
+- bundle create/list/read by owner scope
+- immutable version supersede behavior
+- project binding create/update/delete
+- cross-owner access rejection
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test --cwd services/auth-broker tests/index.test.ts` Expected: FAIL with missing schema or storage behavior.
+
+**Step 3: Write minimal implementation**
+
+Implement the portable bundle registry so one project binding can own a sequence of immutable encrypted bundle versions.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test --cwd services/auth-broker tests/index.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add packages/db/src/schema/core.ts services/auth-broker/src/db/schema.ts services/auth-broker/src/modules/project-envs/service.ts services/auth-broker/tests/index.test.ts docs/plans/2026-03-06-remote-encrypted-project-env-portability-plan.md
+git commit -m "feat: add portable env bundle storage"
+```
+
+### Task 3: Add broker and CLI publish or pull or apply flows
+
+**Files:**
+
+- Create: `services/auth-broker/src/modules/project-envs/plugin.ts`
+- Modify: `services/auth-broker/src/app.ts`
+- Modify: `services/auth-broker/src/modules/better-auth/session.ts`
+- Modify: `src/commands/env.ts`
+- Modify: `src/mcp/server.ts`
+- Test: `services/auth-broker/tests/index.test.ts`
+- Test: `tests/env-command.test.ts`
+- Test: `tests/mcp.test.ts`
+
+**Step 1: Write the failing test**
+
+Add coverage for:
+
+- `hack env remote publish`
+- `hack env remote list`
+- `hack env remote pull`
+- `hack env remote apply`
+- `hack env remote bind`
+- signed-out and cross-owner rejection cases
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test --cwd services/auth-broker tests/index.test.ts && bun test tests/env-command.test.ts tests/mcp.test.ts` Expected: FAIL with route-not-found or unknown-command errors.
+
+**Step 3: Write minimal implementation**
+
+Implement explicit operator-driven flows for publish, fetch, bind, and apply. Do not add background sync or remote-node fan-out in this slice.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test --cwd services/auth-broker tests/index.test.ts && bun test tests/env-command.test.ts tests/mcp.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add services/auth-broker/src/modules/project-envs/plugin.ts services/auth-broker/src/app.ts services/auth-broker/src/modules/better-auth/session.ts src/commands/env.ts src/mcp/server.ts services/auth-broker/tests/index.test.ts tests/env-command.test.ts tests/mcp.test.ts
+git commit -m "feat: add portable env publish and apply flows"
+```
+
+### Task 4: Add manual project-key sharing
+
+**Files:**
+
+- Modify: `packages/db/src/schema/core.ts`
+- Modify: `services/auth-broker/src/db/schema.ts`
+- Modify: `services/auth-broker/src/modules/project-envs/service.ts`
+- Modify: `services/auth-broker/src/modules/project-envs/plugin.ts`
+- Modify: `src/commands/env.ts`
+- Test: `services/auth-broker/tests/index.test.ts`
+- Test: `tests/env-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add coverage for:
+
+- create key share for one recipient
+- list active shares
+- revoke share
+- block access after revocation
+- reject implicit org-wide sharing when no explicit share exists
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test --cwd services/auth-broker tests/index.test.ts && bun test tests/env-command.test.ts` Expected: FAIL because project-key share records do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Implement explicit key-share records and CLI flows such as:
+
+- `hack env remote share`
+- `hack env remote shares`
+- `hack env remote revoke-share`
+
+Keep the unit of sharing as the project key, not plaintext values.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test --cwd services/auth-broker tests/index.test.ts && bun test tests/env-command.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add packages/db/src/schema/core.ts services/auth-broker/src/db/schema.ts services/auth-broker/src/modules/project-envs/service.ts services/auth-broker/src/modules/project-envs/plugin.ts src/commands/env.ts services/auth-broker/tests/index.test.ts tests/env-command.test.ts
+git commit -m "feat: add manual project key sharing"
+```
+
+### Task 5: Add rotation and recovery safeguards
+
+**Files:**
+
+- Modify: `services/auth-broker/src/modules/project-envs/service.ts`
+- Modify: `services/auth-broker/src/modules/project-envs/plugin.ts`
+- Modify: `src/commands/env.ts`
+- Modify: `src/lib/secret-store.ts`
+- Test: `services/auth-broker/tests/index.test.ts`
+- Test: `tests/env-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add coverage for:
+
+- project-key rotation
+- recovery package export metadata
+- preventing deletion of the last recovery path
+- preventing revocation of the last owner share without force
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test --cwd services/auth-broker tests/index.test.ts && bun test tests/env-command.test.ts` Expected: FAIL because rotation and recovery guardrails are not yet implemented.
+
+**Step 3: Write minimal implementation**
+
+Implement separate commands for value rotation, share changes, and project-key rotation, plus explicit recovery-path validation before destructive actions are allowed.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test --cwd services/auth-broker tests/index.test.ts && bun test tests/env-command.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add services/auth-broker/src/modules/project-envs/service.ts services/auth-broker/src/modules/project-envs/plugin.ts src/commands/env.ts src/lib/secret-store.ts services/auth-broker/tests/index.test.ts tests/env-command.test.ts
+git commit -m "feat: add env key rotation and recovery safeguards"
+```
+
+### Task 6: Add `.env` compatibility and visibility-first desktop UX
+
+**Files:**
+
+- Modify: `src/commands/env.ts`
+- Modify: `apps/macos/Packages/Features/DashboardFeature/Sources/DashboardFeature/ProjectDetailView.swift`
+- Modify: `apps/macos/Packages/Features/DashboardFeature/Sources/DashboardFeature/SettingsOverlayView.swift`
+- Modify: `apps/macos/Packages/Services/HackCLI/Sources/HackCLIService/HackCLIClient.swift`
+- Modify: `apps/macos/Packages/Shared/Models/Sources/HackDesktopModels/Models.swift`
+- Test: `tests/env-command.test.ts`
+- Test: `apps/macos/Packages/Shared/Models/Tests/HackDesktopModelsTests/`
+
+**Step 1: Write the failing test**
+
+Add coverage for:
+
+- apply writing `plain_env` entries into `.hack/.env`
+- apply writing secret entries into the configured backend
+- warnings when local backend differs from publish-time hint
+- desktop visibility of contract, local materialization, and portable state
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/env-command.test.ts && swift test --package-path apps/macos` Expected: FAIL with missing compatibility or model coverage.
+
+**Step 3: Write minimal implementation**
+
+Implement compatibility-first apply logic and visibility-first UI. Do not add inline plaintext editing in desktop for remote bundles.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/env-command.test.ts && swift test --package-path apps/macos` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/commands/env.ts apps/macos/Packages/Features/DashboardFeature/Sources/DashboardFeature/ProjectDetailView.swift apps/macos/Packages/Features/DashboardFeature/Sources/DashboardFeature/SettingsOverlayView.swift apps/macos/Packages/Services/HackCLI/Sources/HackCLIService/HackCLIClient.swift apps/macos/Packages/Shared/Models/Sources/HackDesktopModels/Models.swift tests/env-command.test.ts apps/macos/Packages/Shared/Models/Tests/HackDesktopModelsTests
+git commit -m "feat: preserve env compatibility in portable env UX"
+```
+
+## Recommended Execution Order
+
+1. Ship Task 1 first so the current trust model is understandable before remote state expands.
+2. Reuse the existing remote env portability work as the starting point for Tasks 2 and 3.
+3. Keep key sharing separate from base bundle publication so the access model stays reviewable.
+4. Land rotation and recovery only after the share model is in place.
+5. Add desktop UX after the CLI and broker contracts stabilize.
+
+## Follow-On Ticket Titles
+
+- Clarify env storage and trust boundaries in CLI and docs
+- Add portable env bundle registry and project binding
+- Add portable env publish or pull or apply command flow
+- Add manual project-key sharing and revocation
+- Add env key rotation and recovery safeguards
+- Add compatibility-first portable env desktop UX
+
+## Links
+
+- `docs/plans/2026-03-13-env-portability-and-secret-management-design.md`
+- `docs/plans/2026-03-06-remote-encrypted-project-env-portability-plan.md`
+- `docs/env.md`
diff --git a/src/commands/env.ts b/src/commands/env.ts
index 844d0f8da..03c217f53 100644
--- a/src/commands/env.ts
+++ b/src/commands/env.ts
@@ -12,6 +12,7 @@ import { optJson, optPath, optProject } from "../cli/options.ts";
 import { PROJECT_ENV_FILENAME } from "../constants.ts";
 import { readControlPlaneConfig } from "../control-plane/sdk/config.ts";
 import { updateGlobalConfig } from "../lib/config.ts";
+import type { HackEnvStorageSummary } from "../lib/hack-env.ts";
 import {
   removeDotEnvKey,
   resolveHackEnv,
@@ -242,6 +243,7 @@ const handleEnvList: CommandHandlerFor<typeof listSpec> = async ({
       `${JSON.stringify(
         {
           project: projectName,
+          storage: serializeEnvStorageForJson({ storage: resolved.storage }),
           vars: resolved.values.map((v) => ({
             key: v.key,
             required: v.required,
@@ -269,6 +271,30 @@ const handleEnvList: CommandHandlerFor<typeof listSpec> = async ({
     return 0;
   }
 
+  await display.kv({
+    title: "Env storage",
+    entries: [
+      [
+        "contract",
+        `${resolved.storage.contract.path} (committed contract, no values)`,
+      ],
+      [
+        "local_plaintext",
+        `${resolved.storage.localPlaintext.path} (${resolved.storage.localPlaintext.exists ? "present" : "missing"} local plaintext for plain_env)`,
+      ],
+      [
+        "local_secrets",
+        `${formatSecretStoreDescriptor({ descriptor: resolved.storage.localSecrets })} (local secret backend)`,
+      ],
+      [
+        "portable_state",
+        `${resolved.storage.portableState.status}: ${resolved.storage.portableState.message}`,
+      ],
+    ],
+  });
+
+  await display.section("Resolved env vars");
+
   for (const v of resolved.values) {
     const value =
       v.source === "keychain" && !showSecrets && v.value !== null
@@ -292,6 +318,34 @@ const handleEnvList: CommandHandlerFor<typeof listSpec> = async ({
   return 0;
 };
 
+function serializeEnvStorageForJson(input: {
+  readonly storage: HackEnvStorageSummary;
+}) {
+  return {
+    contract: {
+      path: input.storage.contract.path,
+      trust_model: input.storage.contract.trustModel,
+    },
+    local_plaintext: {
+      path: input.storage.localPlaintext.path,
+      exists: input.storage.localPlaintext.exists,
+      trust_model: input.storage.localPlaintext.trustModel,
+    },
+    local_secrets: {
+      backend: input.storage.localSecrets.backend,
+      location: input.storage.localSecrets.location,
+      mode: input.storage.localSecrets.mode,
+      provider: input.storage.localSecrets.provider ?? null,
+      trust_model: input.storage.localSecrets.trustModel,
+    },
+    portable_state: {
+      status: input.storage.portableState.status,
+      trust_model: input.storage.portableState.trustModel,
+      message: input.storage.portableState.message,
+    },
+  };
+}
+
 const handleEnvSet: CommandHandlerFor<typeof setSpec> = async ({
   ctx,
   args,
diff --git a/src/lib/hack-env.ts b/src/lib/hack-env.ts
index 7f301c030..c157b12c0 100644
--- a/src/lib/hack-env.ts
+++ b/src/lib/hack-env.ts
@@ -7,6 +7,7 @@ import {
 import { parseDotEnv } from "./env.ts";
 import { readTextFile, writeTextFileIfChanged } from "./fs.ts";
 import { getString, isRecord } from "./guards.ts";
+import type { SecretStoreDescriptor } from "./secret-store.ts";
 import { resolveSecretStore } from "./secret-store.ts";
 
 export const HACK_ENV_VERSION = 1 as const;
@@ -47,12 +48,37 @@ export type HackEnvResolveResult = {
   readonly contractPath: string;
   readonly contractExists: boolean;
   readonly contractParseError?: string;
+  readonly envPath: string;
+  readonly envExists: boolean;
   readonly contract: HackEnvContract;
+  readonly storage: HackEnvStorageSummary;
   readonly values: readonly HackEnvValueState[];
   readonly missingRequired: readonly HackEnvValueState[];
   readonly envForCompose: Readonly<Record<string, string>>;
 };
 
+export type HackEnvPortableStateSummary = {
+  readonly status: "not_configured";
+  readonly trustModel: "local_only";
+  readonly message: string;
+};
+
+export type HackEnvStorageSummary = {
+  readonly contract: {
+    readonly path: string;
+    readonly trustModel: "committed_no_values";
+  };
+  readonly localPlaintext: {
+    readonly path: string;
+    readonly exists: boolean;
+    readonly trustModel: "gitignored_plaintext";
+  };
+  readonly localSecrets: SecretStoreDescriptor & {
+    readonly trustModel: "local_secret_backend";
+  };
+  readonly portableState: HackEnvPortableStateSummary;
+};
+
 export async function readHackEnvContract(opts: {
   readonly projectDir: string;
 }): Promise<HackEnvReadResult> {
@@ -101,6 +127,7 @@ export async function resolveHackEnv(opts: {
 
   const envPath = resolve(opts.projectDir, PROJECT_ENV_FILENAME);
   const envText = await readTextFile(envPath);
+  const envExists = envText !== null;
   const dotenv = envText ? parseDotEnv(envText) : {};
 
   const envForCompose: Record<string, string> = {};
@@ -170,7 +197,30 @@ export async function resolveHackEnv(opts: {
     contractPath: read.path,
     contractExists: read.exists,
     ...(read.parseError ? { contractParseError: read.parseError } : {}),
+    envPath,
+    envExists,
     contract,
+    storage: {
+      contract: {
+        path: read.path,
+        trustModel: "committed_no_values",
+      },
+      localPlaintext: {
+        path: envPath,
+        exists: envExists,
+        trustModel: "gitignored_plaintext",
+      },
+      localSecrets: {
+        ...secretStore.descriptor,
+        trustModel: "local_secret_backend",
+      },
+      portableState: {
+        status: "not_configured",
+        trustModel: "local_only",
+        message:
+          "Project env values are not portable across machines by default. Portable encrypted bundles are not configured yet.",
+      },
+    },
     values,
     missingRequired,
     envForCompose,
diff --git a/tests/env-backend-command.test.ts b/tests/env-backend-command.test.ts
index bd67629e3..4600b1693 100644
--- a/tests/env-backend-command.test.ts
+++ b/tests/env-backend-command.test.ts
@@ -258,6 +258,113 @@ test("env set --secret stores value using encrypted backend", async () => {
   expect(apiKey?.value).toBe("super-secret");
 });
 
+test("env list --json explains storage and trust boundaries", async () => {
+  if (!tempDir) {
+    throw new Error("Missing temp dir");
+  }
+  process.env.HACK_SECRETS_FILE_KEY = "env-storage-summary-key";
+  const projectRoot = resolve(tempDir, "storage-repo");
+  const projectDir = resolve(projectRoot, ".hack");
+  const encryptedStorePath = resolve(tempDir, "storage-secrets.enc.json");
+  await mkdir(projectDir, { recursive: true });
+  await writeFile(resolve(projectDir, "docker-compose.yml"), "services: {}\n");
+  await writeFile(resolve(projectDir, ".env"), 'PUBLIC_TOKEN="hello world"\n');
+  await writeFile(
+    resolve(projectDir, "hack.config.json"),
+    `${JSON.stringify(
+      {
+        name: "storage-summary-project",
+        controlPlane: {
+          secrets: {
+            backend: "encrypted_file",
+            encryptedFile: {
+              path: encryptedStorePath,
+            },
+          },
+        },
+      },
+      null,
+      2
+    )}\n`
+  );
+  await writeFile(
+    resolve(projectDir, "hack.env.json"),
+    `${JSON.stringify(
+      {
+        version: 1,
+        vars: [
+          {
+            key: "PUBLIC_TOKEN",
+            required: true,
+            source: "plain_env",
+          },
+          {
+            key: "DATABASE_URL",
+            required: true,
+            source: "keychain",
+          },
+        ],
+      },
+      null,
+      2
+    )}\n`
+  );
+
+  const result = await runHack({
+    args: ["env", "list", "--json"],
+    env: {
+      ...process.env,
+      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+      HACK_SECRETS_FILE_KEY: "env-storage-summary-key",
+    },
+    cwd: projectRoot,
+  });
+
+  expect(result.exitCode).toBe(1);
+
+  const json = JSON.parse(result.stdout) as {
+    readonly storage?: {
+      readonly contract?: {
+        readonly path: string;
+        readonly trust_model: string;
+      };
+      readonly local_plaintext?: {
+        readonly path: string;
+        readonly exists: boolean;
+        readonly trust_model: string;
+      };
+      readonly local_secrets?: {
+        readonly backend: string;
+        readonly location: string;
+        readonly mode: string;
+        readonly trust_model: string;
+      };
+      readonly portable_state?: {
+        readonly status: string;
+        readonly trust_model: string;
+        readonly message: string;
+      };
+    };
+  };
+
+  expect(json.storage?.contract?.path).toBe(
+    resolve(projectDir, "hack.env.json")
+  );
+  expect(json.storage?.contract?.trust_model).toBe("committed_no_values");
+  expect(json.storage?.local_plaintext?.path).toBe(resolve(projectDir, ".env"));
+  expect(json.storage?.local_plaintext?.exists).toBe(true);
+  expect(json.storage?.local_plaintext?.trust_model).toBe(
+    "gitignored_plaintext"
+  );
+  expect(json.storage?.local_secrets?.backend).toBe("encrypted_file");
+  expect(json.storage?.local_secrets?.location).toBe(encryptedStorePath);
+  expect(json.storage?.local_secrets?.mode).toBe("native");
+  expect(json.storage?.local_secrets?.trust_model).toBe("local_secret_backend");
+  expect(json.storage?.portable_state?.status).toBe("not_configured");
+  expect(json.storage?.portable_state?.trust_model).toBe("local_only");
+  expect(json.storage?.portable_state?.message).toContain("not portable");
+});
+
 async function runHack(input: {
   readonly args: readonly string[];
   readonly env: NodeJS.ProcessEnv;

From f8192a53cd7f36a94594fe71843c8133c2febfc0 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 22:30:38 +0000
Subject: [PATCH 002/134] docs: define first-class github workflows

---
 docs/cli.md                                   |   6 +
 docs/extensions.md                            |  64 ++++
 ...-13-github-first-class-workflows-design.md | 237 ++++++++++++++
 ...03-13-github-first-class-workflows-plan.md | 299 ++++++++++++++++++
 4 files changed, 606 insertions(+)
 create mode 100644 docs/plans/2026-03-13-github-first-class-workflows-design.md
 create mode 100644 docs/plans/2026-03-13-github-first-class-workflows-plan.md

diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..247f0f85c 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -959,6 +959,12 @@ GitHub profile precedence for `--pr`:
 2. Project `controlPlane.routing.overrides.github.profile`.
 3. Global `controlPlane.extensions["dance.hack.github"].config.defaultProfile`.
 
+Scope note for `--pr`:
+
+- `hack dispatch run --pr` currently covers the PR update workflow only: push the branch, then create or update the PR.
+- It does not imply broader GitHub workflow support such as review submission, standalone PR comments, merge actions, or repo-admin actions.
+- The broader first-class GitHub workflow model lives in the GitHub extension docs and `docs/plans/2026-03-13-github-first-class-workflows-design.md`, and is intentionally sequenced beyond the current `--pr` path.
+
 #### hack dispatch status
 
 Usage: `hack dispatch status <run-id> [--json]`
diff --git a/docs/extensions.md b/docs/extensions.md
index b4c8b0a81..05103107b 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -273,6 +273,70 @@ Notes:
 - macOS desktop shows read-only system Git identity (host-level inherited Git/gh context) separately from remote OAuth/App accounts to keep local gateway identity and remote auth routing boundaries explicit.
 - `auth.hack` and `auth.hack.gy` are routed by global Caddy to the daemon auth listener (`127.0.0.1:7790` by default), so this endpoint can also host future provider callbacks/hooks.
 
+Workflow scope:
+
+- Current shipped GitHub workflow support is intentionally narrow:
+  - auth/profile connection and selection
+  - PR create/update via `hack x github pr-upsert`
+- The first-class GitHub workflow model for the current milestone is bounded to:
+  - review intake and review decision
+  - PR update and readiness management
+  - PR-level conversation comments
+  - PR-adjacent repo handoff actions
+- The initial set is outcome-based rather than command-based so CLI, desktop, and agent surfaces can share the same product boundary.
+- Until those additional flows land, this section should not be read as claiming those commands already exist.
+
+Initial supported set for this milestone:
+
+1. Review intake for a relevant PR
+2. Review decision submission with a summary body
+3. PR creation/update plus draft-ready state changes
+4. Top-level PR comments
+5. Read-only repo-context handoff actions tied to a PR
+
+Initial workflow definitions:
+
+- Review intake and review decision
+  - Outcome: identify a PR needing action, inspect summary state, and submit `approve`, `comment`, or `request_changes`.
+- PR update and readiness management
+  - Outcome: create or update a PR, keep title/body/base accurate, and move between draft and ready states.
+- Conversation comments
+  - Outcome: leave top-level PR discussion comments without doing a full review submission.
+- PR-adjacent repo handoff actions
+  - Outcome: move from PR context to local repo/branch context without manually reconstructing refs.
+
+Explicitly out of the initial GitHub scope:
+
+- inline diff review comments and thread resolution
+- labels, assignees, milestones, and project edits
+- merge, merge queue, auto-merge, and rebase controls
+- rerunning GitHub Actions jobs
+- GitHub Issues, Projects, Discussions, releases, or repo admin surfaces
+
+Success criteria by workflow class:
+
+- Review intake and review decision
+  - A reviewer can identify a PR that needs action and submit `approve`, `comment`, or `request_changes` from Hack.
+- PR update and readiness management
+  - An author can create or correct a PR state, including draft and ready transitions, from Hack.
+- Conversation comments
+  - A user can leave a contextual PR comment without switching to GitHub web.
+- PR-adjacent repo handoff actions
+  - A user can move from PR context to local repo context without manual copy-paste of refs.
+
+Recommended implementation order:
+
+1. shared PR/review read models
+2. review decision submission
+3. PR metadata update plus draft/ready transitions
+4. standalone PR comment creation
+5. repo-context handoff actions
+
+Detailed design and sequencing live in:
+
+- `docs/plans/2026-03-13-github-first-class-workflows-design.md`
+- `docs/plans/2026-03-13-github-first-class-workflows-plan.md`
+
 ### Linear extension (`hack x linear`)
 
 Linear integration supports multiple auth profiles, project-level binding, and manual sync in both
diff --git a/docs/plans/2026-03-13-github-first-class-workflows-design.md b/docs/plans/2026-03-13-github-first-class-workflows-design.md
new file mode 100644
index 000000000..7fab9c98f
--- /dev/null
+++ b/docs/plans/2026-03-13-github-first-class-workflows-design.md
@@ -0,0 +1,237 @@
+# GitHub First-Class Workflows Design
+
+## Context
+
+Hack already has a GitHub extension, but its current surface is mostly auth/profile plumbing plus a narrow `pr-upsert` write path. That is enough to prove connectivity, but not enough to define what "GitHub support" means as a product capability. Without an explicit workflow set, future work risks growing as disconnected commands and one-off UI affordances.
+
+This ticket defines the first-class GitHub workflow boundary for the current milestone so implementation can sequence intentionally around user outcomes instead of command accumulation.
+
+## Goals
+
+- Define a prioritized, bounded initial GitHub workflow set.
+- Make the supported user outcomes explicit for reviews, PR updates, comments, and adjacent repo actions.
+- Separate the initial release scope from later expansion so product and engineering can say no clearly.
+- Provide enough sequencing guidance that implementation can proceed in phases.
+
+## Non-Goals
+
+- Defining every future GitHub action Hack may ever support.
+- Matching the full GitHub web UI.
+- Covering GitHub Issues, Projects, Discussions, releases, or repo administration in the initial set.
+- Designing the final CLI verbs or macOS UI in detail.
+
+## Approaches Considered
+
+### 1. Command-inventory definition
+
+Define scope around concrete commands such as `pr-upsert`, `review-submit`, and `comment-create`.
+
+Pros:
+
+- Easy to tie directly to implementation
+- Low ambiguity for CLI work
+
+Cons:
+
+- Locks product language to current transport details
+- Makes cross-surface planning harder for macOS, CLI, and agents
+
+### 2. Workflow-class definition (recommended)
+
+Define scope around user jobs such as "review a PR" or "update my PR", then map commands and UI to those jobs.
+
+Pros:
+
+- Keeps the capability user-outcome focused
+- Gives implementation freedom across CLI, desktop, and agents
+- Makes later expansion easier to reason about
+
+Cons:
+
+- Requires a little more up-front definition work
+
+### 3. Broad GitHub workbench
+
+Treat GitHub as a general remote workbench and include most adjacent actions now.
+
+Pros:
+
+- Ambitious and flexible
+
+Cons:
+
+- Too large for the current milestone
+- Makes "first-class" indistinguishable from "everything"
+- Weakens implementation sequencing
+
+## Recommendation
+
+Adopt the workflow-class model. The first-class GitHub surface should be defined by a small number of high-value jobs that users can complete end-to-end inside Hack. Commands, desktop affordances, and agent tools should then map onto those workflows.
+
+## Proposed First-Class Workflow Set
+
+### Priority 1: Review Intake and Review Decision
+
+**User outcome:** A user can see which PR needs their attention, inspect the decision context, and submit a review outcome without falling back to GitHub web for the common case.
+
+**Initial support**
+
+- List relevant PRs for the current user or current repo context.
+- Open a PR summary with:
+  - title, author, branch/base
+  - review state
+  - mergeability/check status summary
+  - changed file summary
+  - unresolved conversation/thread counts
+- Submit a review decision:
+  - `approve`
+  - `comment`
+  - `request_changes`
+- Include one summary review body with the decision.
+
+**Explicitly out of initial scope**
+
+- Inline diff comment authoring
+- Multi-comment review drafts
+- Thread resolution management
+- Batch review across many repositories
+
+**Success criteria**
+
+- A reviewer can identify a PR requiring action in one entry flow.
+- A reviewer can make an approve/comment/request-changes decision from Hack.
+- The review action returns the resulting GitHub review state and PR URL/id so downstream tooling can continue.
+
+### Priority 2: PR Update and Readiness Management
+
+**User outcome:** An author can create or keep a PR accurate and move it between draft and ready states without using the GitHub web UI.
+
+**Initial support**
+
+- Create or update a PR for the current branch/repo context.
+- Update title, body, and base branch.
+- Transition draft <-> ready for review.
+- Read current PR metadata before mutating it.
+- Optionally add a single top-level comment when performing a PR update.
+
+**Explicitly out of initial scope**
+
+- Label, assignee, milestone, or project edits
+- Auto-generated release notes
+- Merge queue controls
+- Auto-rebase, auto-merge, or branch protection bypass
+
+**Success criteria**
+
+- A branch with an existing or missing PR can be brought to a correct GitHub PR state from Hack.
+- An author can mark a PR ready or return it to draft.
+- The update flow is idempotent enough to support agent-driven use.
+
+### Priority 3: Conversation Comments
+
+**User outcome:** A user can leave PR-level discussion comments when they do not need a full review submission.
+
+**Initial support**
+
+- Create a top-level PR comment.
+- Reply to an existing discussion target only if GitHub exposes a clear non-inline comment target already represented in Hack state.
+- Show enough surrounding PR metadata so comments are not sent blind.
+
+**Explicitly out of initial scope**
+
+- Full threaded review comment authoring on diffs
+- Comment editing and deletion
+- Emoji reactions
+- Issue-wide/general GitHub social surface
+
+**Success criteria**
+
+- A user can post a contextual PR comment without switching tools.
+- Comment creation can be attached to either standalone discussion or a PR update flow.
+- The result includes a durable remote identifier for later correlation.
+
+### Priority 4: Adjacent Repo Actions
+
+**User outcome:** A user can move cleanly between GitHub PR context and local repo work without re-entering context manually.
+
+**Initial support**
+
+- Resolve the current branch to its PR, or a PR to its repo/branch refs.
+- Open or hand off to the local repo/branch context:
+  - checkout or branch/worktree handoff target
+  - canonical PR URL
+  - head/base refs
+  - changed file list summary
+- Show CI/check status summary as read-only context when acting on a PR.
+
+**Explicitly out of initial scope**
+
+- Merging a PR
+- Rebasing or updating branches on GitHub
+- Rerunning GitHub Actions jobs
+- Repo settings, secrets, releases, tags, or admin actions
+
+**Success criteria**
+
+- A user can pivot from PR context to local repo context with no manual copy-paste of branch/ref data.
+- Review and PR update workflows can reuse the same repo-context resolution primitives.
+- Repo actions remain supportive, not a second unbounded GitHub product surface.
+
+## Initial Supported Set
+
+The initial GitHub capability set is explicitly limited to:
+
+1. Review intake for a relevant PR
+2. Review decision submission with a summary body
+3. PR creation/update plus draft-ready state changes
+4. Top-level PR comments
+5. Read-only repo-context handoff actions tied to a PR
+
+Everything else is out unless it is necessary to make one of those five workflows function end-to-end.
+
+## Later Expansion
+
+Later GitHub phases may add:
+
+- Inline diff comments and thread resolution
+- PR metadata enrichment such as labels, assignees, milestones, and linked issues
+- Merge and queue actions
+- CI control actions such as rerun/retry
+- Issue-centric workflows
+- Repo maintenance/admin workflows
+- Multi-repo inbox and batch review surfaces
+
+These should remain separate expansion decisions, not implicit additions to the initial milestone.
+
+## Sequencing Guidance
+
+Implementation should land in this order:
+
+1. Shared PR/review read models
+2. Review decision submission
+3. PR metadata update and draft/ready transitions
+4. Standalone comment creation
+5. Repo-context handoff affordances
+
+That order keeps the highest-value workflows intact while forcing a shared read layer before write surfaces multiply.
+
+## Product Boundary Rules
+
+- Every new GitHub action must map to one of the workflow classes above or be deferred.
+- If an action does not complete a clear user outcome, it is not first-class.
+- Repo actions stay subordinate to PR/review workflows unless a separate milestone expands them.
+- Initial support favors summary-level actions over fine-grained GitHub UI parity.
+
+## Acceptance Mapping
+
+### The initial GitHub capability set is explicit and bounded
+
+Yes. The initial set is limited to review intake/decision, PR updates, PR comments, and PR-adjacent repo handoff actions.
+
+### Each workflow has a clear user outcome
+
+Yes. Each workflow class above includes a single primary outcome and explicit success criteria.
+
+### The scope is concrete enough to drive implementation sequencing
+
+Yes. The workflow set is prioritized, split into initial vs later, and ordered for phased implementation.
diff --git a/docs/plans/2026-03-13-github-first-class-workflows-plan.md b/docs/plans/2026-03-13-github-first-class-workflows-plan.md
new file mode 100644
index 000000000..18b337dd1
--- /dev/null
+++ b/docs/plans/2026-03-13-github-first-class-workflows-plan.md
@@ -0,0 +1,299 @@
+# GitHub First-Class Workflows Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Implement the initial first-class GitHub workflow set for reviews, PR updates, comments, and PR-adjacent repo actions in a phased, testable way.
+
+**Architecture:** Build a shared GitHub PR/review domain layer first, then layer workflow-specific command/UI entry points on top. Keep write operations narrowly aligned to the defined workflow classes so the product surface stays bounded.
+
+**Tech Stack:** Bun, TypeScript, Hack CLI extension framework, Bun test, markdown docs
+
+---
+
+### Task 1: Document the product boundary in public docs
+
+**Files:**
+
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+- Test: `docs/plans/2026-03-13-github-first-class-workflows-design.md`
+
+**Step 1: Write the failing documentation expectation**
+
+Add a short checklist to the task branch notes describing the public-doc gap:
+
+- GitHub docs only describe auth/profile management plus `pr-upsert`
+- There is no explicit workflow taxonomy for reviews, comments, or repo handoff
+
+**Step 2: Verify the gap exists**
+
+Run: `grep -n "GitHub extension" -n docs/extensions.md && grep -n "review" docs/extensions.md` Expected: GitHub auth/pr-upsert docs exist, but workflow taxonomy is missing or incomplete.
+
+**Step 3: Add minimal public-facing scope language**
+
+Document:
+
+- supported initial workflow classes
+- explicit non-goals for the first milestone
+- pointer from command docs to the workflow model
+
+**Step 4: Verify the docs render cleanly**
+
+Run: `git diff --check` Expected: no whitespace or patch-format errors.
+
+**Step 5: Commit**
+
+```bash
+git add docs/extensions.md docs/cli.md docs/plans/2026-03-13-github-first-class-workflows-design.md
+git commit -m "docs: define first-class github workflow scope"
+```
+
+### Task 2: Add shared PR/review read primitives
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Test: `tests/github-client.test.ts`
+- Test: `tests/github-commands.test.ts`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+
+- fetching a PR summary by repo + number or branch
+- listing relevant PRs for a repo/user context
+- normalizing review/check/thread summary payloads
+
+**Step 2: Run targeted tests to verify failure**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: FAIL because review/summary read APIs do not exist yet.
+
+**Step 3: Implement the minimal shared read layer**
+
+Add client helpers and command plumbing for:
+
+- PR summary fetch
+- relevant PR listing
+- review/check/thread summary normalization
+
+**Step 4: Re-run tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: PASS for the new read-path coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts tests/github-client.test.ts tests/github-commands.test.ts
+git commit -m "feat(github): add shared pr review read primitives"
+```
+
+### Task 3: Implement review decision submission
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Test: `tests/github-client.test.ts`
+- Test: `tests/github-commands.test.ts`
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+
+- `approve`, `comment`, and `request_changes` review submission
+- required summary body validation
+- stable success payload formatting
+
+**Step 2: Run targeted tests to verify failure**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: FAIL because review submission endpoints and command parsing are missing.
+
+**Step 3: Implement the minimal review submission flow**
+
+Add:
+
+- client call for GitHub review submission
+- command parsing and output formatting
+- docs for the new supported review workflow
+
+**Step 4: Re-run tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: PASS for review submission coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts tests/github-client.test.ts tests/github-commands.test.ts docs/extensions.md docs/cli.md
+git commit -m "feat(github): add review decision workflow"
+```
+
+### Task 4: Expand PR update flow beyond upsert
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Test: `tests/github-client.test.ts`
+- Test: `tests/github-commands.test.ts`
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+
+- PR metadata read-before-write behavior
+- title/body/base updates
+- draft -> ready and ready -> draft transitions
+- optional comment attach-on-update behavior
+
+**Step 2: Run targeted tests to verify failure**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: FAIL because the state-transition surface is incomplete.
+
+**Step 3: Implement the minimal PR update workflow**
+
+Extend the current `pr-upsert` path or split it into clearer commands, but keep support limited to:
+
+- create/update
+- draft/ready transitions
+- optional top-level comment
+
+**Step 4: Re-run tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: PASS for the expanded PR update coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts tests/github-client.test.ts tests/github-commands.test.ts docs/extensions.md docs/cli.md
+git commit -m "feat(github): expand pr update workflow"
+```
+
+### Task 5: Add standalone PR comment workflow
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Test: `tests/github-client.test.ts`
+- Test: `tests/github-commands.test.ts`
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+
+- creating a top-level PR comment
+- validating repo/pr target resolution
+- emitting durable remote identifiers in output
+
+**Step 2: Run targeted tests to verify failure**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: FAIL because standalone comment workflow is not yet exposed.
+
+**Step 3: Implement the minimal standalone comment flow**
+
+Support only top-level PR comments in this task. Do not add full inline diff-thread comment support.
+
+**Step 4: Re-run tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: PASS for standalone comment coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts tests/github-client.test.ts tests/github-commands.test.ts docs/extensions.md docs/cli.md
+git commit -m "feat(github): add standalone pr comments"
+```
+
+### Task 6: Add PR-adjacent repo handoff actions
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Modify: `src/lib/project.ts`
+- Test: `tests/github-client.test.ts`
+- Test: `tests/github-commands.test.ts`
+- Test: `tests/project-execution-routing.test.ts`
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+
+- resolving PR head/base refs from GitHub state
+- mapping a PR to a local branch/worktree handoff target
+- presenting changed-file and checks summary as read-only repo context
+
+**Step 2: Run targeted tests to verify failure**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts tests/project-execution-routing.test.ts` Expected: FAIL because PR-to-local handoff actions are not implemented.
+
+**Step 3: Implement the minimal repo handoff flow**
+
+Support:
+
+- PR/ref resolution
+- local branch/worktree handoff target generation
+- PR URL and changed-file/check summary output
+
+Do not add merge, rebase, rerun, or admin actions.
+
+**Step 4: Re-run tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts tests/project-execution-routing.test.ts` Expected: PASS for the handoff coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts src/lib/project.ts tests/github-client.test.ts tests/github-commands.test.ts tests/project-execution-routing.test.ts docs/extensions.md docs/cli.md
+git commit -m "feat(github): add pr repo handoff actions"
+```
+
+### Task 7: Run full quality gates for the GitHub workflow milestone
+
+**Files:**
+
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Modify: `tests/github-client.test.ts`
+- Modify: `tests/github-commands.test.ts`
+
+**Step 1: Run formatter/linter**
+
+Run: `bun x ultracite fix` Expected: formatting and autofix pass cleanly.
+
+**Step 2: Run focused tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts tests/project-execution-routing.test.ts` Expected: PASS.
+
+**Step 3: Run broader repository validation**
+
+Run: `bun x ultracite check` Expected: PASS with no new lint or formatting regressions.
+
+**Step 4: Review scope against the design doc**
+
+Verify each implemented action still maps to:
+
+- review intake/decision
+- PR update
+- PR comments
+- PR-adjacent repo handoff
+
+Expected: no extra GitHub surface added beyond the design boundary.
+
+**Step 5: Commit**
+
+```bash
+git add docs/extensions.md docs/cli.md src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts tests/github-client.test.ts tests/github-commands.test.ts tests/project-execution-routing.test.ts
+git commit -m "feat(github): deliver first-class workflow milestone"
+```

From e22be091523d36ffea35ef3423504ce4e5bd99f0 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 22:34:11 +0000
Subject: [PATCH 003/134] fix: explain env storage without contract

---
 src/commands/env.ts               |  14 +-
 tests/env-backend-command.test.ts | 513 +++++++++++++++++-------------
 2 files changed, 304 insertions(+), 223 deletions(-)

diff --git a/src/commands/env.ts b/src/commands/env.ts
index 03c217f53..5d031d3c9 100644
--- a/src/commands/env.ts
+++ b/src/commands/env.ts
@@ -264,13 +264,6 @@ const handleEnvList: CommandHandlerFor<typeof listSpec> = async ({
     return resolved.missingRequired.length > 0 ? 1 : 0;
   }
 
-  if (resolved.contract.vars.length === 0) {
-    logger.info({
-      message: `No ${project.projectDir}/hack.env.json contract found (or it has no vars).`,
-    });
-    return 0;
-  }
-
   await display.kv({
     title: "Env storage",
     entries: [
@@ -293,6 +286,13 @@ const handleEnvList: CommandHandlerFor<typeof listSpec> = async ({
     ],
   });
 
+  if (resolved.contract.vars.length === 0) {
+    logger.info({
+      message: `No ${project.projectDir}/hack.env.json contract found (or it has no vars).`,
+    });
+    return 0;
+  }
+
   await display.section("Resolved env vars");
 
   for (const v of resolved.values) {
diff --git a/tests/env-backend-command.test.ts b/tests/env-backend-command.test.ts
index 4600b1693..8e09194b5 100644
--- a/tests/env-backend-command.test.ts
+++ b/tests/env-backend-command.test.ts
@@ -130,240 +130,321 @@ test("env backend use encrypted_file can provision a stable key file", async ()
   expect(configText).toContain(keyPath);
 });
 
-test("env backend use cloud requires provider and stores cloud settings", async () => {
-  const invalid = await runHack({
-    args: ["env", "backend", "use", "cloud"],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-    },
-  });
-  expect(invalid.exitCode).toBe(1);
-  expect(`${invalid.stdout}\n${invalid.stderr}`).toContain(
-    "Cloud backend requires --provider"
-  );
+test(
+  "env backend use cloud requires provider and stores cloud settings",
+  { timeout: 10_000 },
+  async () => {
+    const invalid = await runHack({
+      args: ["env", "backend", "use", "cloud"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+      },
+    });
+    expect(invalid.exitCode).toBe(1);
+    expect(`${invalid.stdout}\n${invalid.stderr}`).toContain(
+      "Cloud backend requires --provider"
+    );
 
-  const valid = await runHack({
-    args: [
-      "env",
-      "backend",
-      "use",
-      "cloud",
-      "--provider",
-      "aws",
-      "--secret-project",
-      "dev-account",
-      "--secret-prefix",
-      "hack-cli",
-      "--json",
-    ],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-    },
-  });
-  expect(valid.exitCode).toBe(0);
-  const json = JSON.parse(valid.stdout) as {
-    readonly backend: string;
-    readonly cloud: {
-      readonly provider?: string;
-      readonly project?: string;
-      readonly secretPrefix: string;
+    const valid = await runHack({
+      args: [
+        "env",
+        "backend",
+        "use",
+        "cloud",
+        "--provider",
+        "aws",
+        "--secret-project",
+        "dev-account",
+        "--secret-prefix",
+        "hack-cli",
+        "--json",
+      ],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+      },
+    });
+    expect(valid.exitCode).toBe(0);
+    const json = JSON.parse(valid.stdout) as {
+      readonly backend: string;
+      readonly cloud: {
+        readonly provider?: string;
+        readonly project?: string;
+        readonly secretPrefix: string;
+      };
     };
-  };
-  expect(json.backend).toBe("cloud");
-  expect(json.cloud.provider).toBe("aws");
-  expect(json.cloud.project).toBe("dev-account");
-  expect(json.cloud.secretPrefix).toBe("hack-cli");
-});
-
-test("env set --secret stores value using encrypted backend", async () => {
-  if (!tempDir) {
-    throw new Error("Missing temp dir");
+    expect(json.backend).toBe("cloud");
+    expect(json.cloud.provider).toBe("aws");
+    expect(json.cloud.project).toBe("dev-account");
+    expect(json.cloud.secretPrefix).toBe("hack-cli");
   }
-  process.env.HACK_SECRETS_FILE_KEY = "env-backend-command-key";
-  const projectRoot = resolve(tempDir, "repo");
-  const projectDir = resolve(projectRoot, ".hack");
-  await mkdir(projectDir, { recursive: true });
-  await writeFile(resolve(projectDir, "docker-compose.yml"), "services: {}\n");
-  await writeFile(
-    resolve(projectDir, "hack.config.json"),
-    `${JSON.stringify(
-      {
-        name: "env-backend-project",
-        controlPlane: {
-          secrets: {
-            backend: "encrypted_file",
-            encryptedFile: {
-              path: resolve(tempDir, "secrets.enc.json"),
+);
+
+test(
+  "env set --secret stores value using encrypted backend",
+  { timeout: 20_000 },
+  async () => {
+    if (!tempDir) {
+      throw new Error("Missing temp dir");
+    }
+    process.env.HACK_SECRETS_FILE_KEY = "env-backend-command-key";
+    const projectRoot = resolve(tempDir, "repo");
+    const projectDir = resolve(projectRoot, ".hack");
+    await mkdir(projectDir, { recursive: true });
+    await writeFile(
+      resolve(projectDir, "docker-compose.yml"),
+      "services: {}\n"
+    );
+    await writeFile(
+      resolve(projectDir, "hack.config.json"),
+      `${JSON.stringify(
+        {
+          name: "env-backend-project",
+          controlPlane: {
+            secrets: {
+              backend: "encrypted_file",
+              encryptedFile: {
+                path: resolve(tempDir, "secrets.enc.json"),
+              },
             },
           },
         },
-      },
-      null,
-      2
-    )}\n`
-  );
-  await writeFile(
-    resolve(projectDir, "hack.env.json"),
-    `${JSON.stringify(
-      {
-        version: 1,
-        vars: [
-          {
-            key: "API_KEY",
-            required: false,
-            source: "keychain",
-          },
-        ],
-      },
-      null,
-      2
-    )}\n`
-  );
-
-  const setResult = await runHack({
-    args: ["env", "set", "--secret", "API_KEY=super-secret"],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-      HACK_SECRETS_FILE_KEY: "env-backend-command-key",
-    },
-    cwd: projectRoot,
-  });
-  expect(setResult.exitCode).toBe(0);
-  expect(`${setResult.stdout}\n${setResult.stderr}`).toContain(
-    "encrypted_file"
-  );
+        null,
+        2
+      )}\n`
+    );
+    await writeFile(
+      resolve(projectDir, "hack.env.json"),
+      `${JSON.stringify(
+        {
+          version: 1,
+          vars: [
+            {
+              key: "API_KEY",
+              required: false,
+              source: "keychain",
+            },
+          ],
+        },
+        null,
+        2
+      )}\n`
+    );
 
-  const listResult = await runHack({
-    args: ["env", "list", "--show-secrets", "--json"],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-      HACK_SECRETS_FILE_KEY: "env-backend-command-key",
-    },
-    cwd: projectRoot,
-  });
-  expect(listResult.exitCode).toBe(0);
-  const listJson = JSON.parse(listResult.stdout) as {
-    readonly vars: ReadonlyArray<{
-      readonly key: string;
-      readonly value: string | null;
-      readonly source: string;
-    }>;
-  };
-  const apiKey = listJson.vars.find((entry) => entry.key === "API_KEY");
-  expect(apiKey?.source).toBe("keychain");
-  expect(apiKey?.value).toBe("super-secret");
-});
+    const setResult = await runHack({
+      args: ["env", "set", "--secret", "API_KEY=super-secret"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+        HACK_SECRETS_FILE_KEY: "env-backend-command-key",
+      },
+      cwd: projectRoot,
+    });
+    expect(setResult.exitCode).toBe(0);
+    expect(`${setResult.stdout}\n${setResult.stderr}`).toContain(
+      "encrypted_file"
+    );
 
-test("env list --json explains storage and trust boundaries", async () => {
-  if (!tempDir) {
-    throw new Error("Missing temp dir");
+    const listResult = await runHack({
+      args: ["env", "list", "--show-secrets", "--json"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+        HACK_SECRETS_FILE_KEY: "env-backend-command-key",
+      },
+      cwd: projectRoot,
+    });
+    expect(listResult.exitCode).toBe(0);
+    const listJson = JSON.parse(listResult.stdout) as {
+      readonly vars: ReadonlyArray<{
+        readonly key: string;
+        readonly value: string | null;
+        readonly source: string;
+      }>;
+    };
+    const apiKey = listJson.vars.find((entry) => entry.key === "API_KEY");
+    expect(apiKey?.source).toBe("keychain");
+    expect(apiKey?.value).toBe("super-secret");
   }
-  process.env.HACK_SECRETS_FILE_KEY = "env-storage-summary-key";
-  const projectRoot = resolve(tempDir, "storage-repo");
-  const projectDir = resolve(projectRoot, ".hack");
-  const encryptedStorePath = resolve(tempDir, "storage-secrets.enc.json");
-  await mkdir(projectDir, { recursive: true });
-  await writeFile(resolve(projectDir, "docker-compose.yml"), "services: {}\n");
-  await writeFile(resolve(projectDir, ".env"), 'PUBLIC_TOKEN="hello world"\n');
-  await writeFile(
-    resolve(projectDir, "hack.config.json"),
-    `${JSON.stringify(
-      {
-        name: "storage-summary-project",
-        controlPlane: {
-          secrets: {
-            backend: "encrypted_file",
-            encryptedFile: {
-              path: encryptedStorePath,
+);
+
+test(
+  "env list --json explains storage and trust boundaries",
+  { timeout: 20_000 },
+  async () => {
+    if (!tempDir) {
+      throw new Error("Missing temp dir");
+    }
+    process.env.HACK_SECRETS_FILE_KEY = "env-storage-summary-key";
+    const projectRoot = resolve(tempDir, "storage-repo");
+    const projectDir = resolve(projectRoot, ".hack");
+    const encryptedStorePath = resolve(tempDir, "storage-secrets.enc.json");
+    await mkdir(projectDir, { recursive: true });
+    await writeFile(
+      resolve(projectDir, "docker-compose.yml"),
+      "services: {}\n"
+    );
+    await writeFile(
+      resolve(projectDir, ".env"),
+      'PUBLIC_TOKEN="hello world"\n'
+    );
+    await writeFile(
+      resolve(projectDir, "hack.config.json"),
+      `${JSON.stringify(
+        {
+          name: "storage-summary-project",
+          controlPlane: {
+            secrets: {
+              backend: "encrypted_file",
+              encryptedFile: {
+                path: encryptedStorePath,
+              },
             },
           },
         },
-      },
-      null,
-      2
-    )}\n`
-  );
-  await writeFile(
-    resolve(projectDir, "hack.env.json"),
-    `${JSON.stringify(
-      {
-        version: 1,
-        vars: [
-          {
-            key: "PUBLIC_TOKEN",
-            required: true,
-            source: "plain_env",
-          },
-          {
-            key: "DATABASE_URL",
-            required: true,
-            source: "keychain",
-          },
-        ],
-      },
-      null,
-      2
-    )}\n`
-  );
+        null,
+        2
+      )}\n`
+    );
+    await writeFile(
+      resolve(projectDir, "hack.env.json"),
+      `${JSON.stringify(
+        {
+          version: 1,
+          vars: [
+            {
+              key: "PUBLIC_TOKEN",
+              required: true,
+              source: "plain_env",
+            },
+            {
+              key: "DATABASE_URL",
+              required: true,
+              source: "keychain",
+            },
+          ],
+        },
+        null,
+        2
+      )}\n`
+    );
 
-  const result = await runHack({
-    args: ["env", "list", "--json"],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-      HACK_SECRETS_FILE_KEY: "env-storage-summary-key",
-    },
-    cwd: projectRoot,
-  });
+    const result = await runHack({
+      args: ["env", "list", "--json"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+        HACK_SECRETS_FILE_KEY: "env-storage-summary-key",
+      },
+      cwd: projectRoot,
+    });
 
-  expect(result.exitCode).toBe(1);
+    expect(result.exitCode).toBe(1);
 
-  const json = JSON.parse(result.stdout) as {
-    readonly storage?: {
-      readonly contract?: {
-        readonly path: string;
-        readonly trust_model: string;
-      };
-      readonly local_plaintext?: {
-        readonly path: string;
-        readonly exists: boolean;
-        readonly trust_model: string;
-      };
-      readonly local_secrets?: {
-        readonly backend: string;
-        readonly location: string;
-        readonly mode: string;
-        readonly trust_model: string;
-      };
-      readonly portable_state?: {
-        readonly status: string;
-        readonly trust_model: string;
-        readonly message: string;
+    const json = JSON.parse(result.stdout) as {
+      readonly storage?: {
+        readonly contract?: {
+          readonly path: string;
+          readonly trust_model: string;
+        };
+        readonly local_plaintext?: {
+          readonly path: string;
+          readonly exists: boolean;
+          readonly trust_model: string;
+        };
+        readonly local_secrets?: {
+          readonly backend: string;
+          readonly location: string;
+          readonly mode: string;
+          readonly trust_model: string;
+        };
+        readonly portable_state?: {
+          readonly status: string;
+          readonly trust_model: string;
+          readonly message: string;
+        };
       };
     };
-  };
 
-  expect(json.storage?.contract?.path).toBe(
-    resolve(projectDir, "hack.env.json")
-  );
-  expect(json.storage?.contract?.trust_model).toBe("committed_no_values");
-  expect(json.storage?.local_plaintext?.path).toBe(resolve(projectDir, ".env"));
-  expect(json.storage?.local_plaintext?.exists).toBe(true);
-  expect(json.storage?.local_plaintext?.trust_model).toBe(
-    "gitignored_plaintext"
-  );
-  expect(json.storage?.local_secrets?.backend).toBe("encrypted_file");
-  expect(json.storage?.local_secrets?.location).toBe(encryptedStorePath);
-  expect(json.storage?.local_secrets?.mode).toBe("native");
-  expect(json.storage?.local_secrets?.trust_model).toBe("local_secret_backend");
-  expect(json.storage?.portable_state?.status).toBe("not_configured");
-  expect(json.storage?.portable_state?.trust_model).toBe("local_only");
-  expect(json.storage?.portable_state?.message).toContain("not portable");
-});
+    expect(json.storage?.contract?.path).toBe(
+      resolve(projectDir, "hack.env.json")
+    );
+    expect(json.storage?.contract?.trust_model).toBe("committed_no_values");
+    expect(json.storage?.local_plaintext?.path).toBe(
+      resolve(projectDir, ".env")
+    );
+    expect(json.storage?.local_plaintext?.exists).toBe(true);
+    expect(json.storage?.local_plaintext?.trust_model).toBe(
+      "gitignored_plaintext"
+    );
+    expect(json.storage?.local_secrets?.backend).toBe("encrypted_file");
+    expect(json.storage?.local_secrets?.location).toBe(encryptedStorePath);
+    expect(json.storage?.local_secrets?.mode).toBe("native");
+    expect(json.storage?.local_secrets?.trust_model).toBe(
+      "local_secret_backend"
+    );
+    expect(json.storage?.portable_state?.status).toBe("not_configured");
+    expect(json.storage?.portable_state?.trust_model).toBe("local_only");
+    expect(json.storage?.portable_state?.message).toContain("not portable");
+  }
+);
+
+test(
+  "env list shows storage summary even when no contract exists",
+  { timeout: 20_000 },
+  async () => {
+    if (!tempDir) {
+      throw new Error("Missing temp dir");
+    }
+    process.env.HACK_SECRETS_FILE_KEY = "env-storage-no-contract-key";
+    const projectRoot = resolve(tempDir, "no-contract-repo");
+    const projectDir = resolve(projectRoot, ".hack");
+    const encryptedStorePath = resolve(tempDir, "no-contract-secrets.enc.json");
+    await mkdir(projectDir, { recursive: true });
+    await writeFile(
+      resolve(projectDir, "docker-compose.yml"),
+      "services: {}\n"
+    );
+    await writeFile(
+      resolve(projectDir, "hack.config.json"),
+      `${JSON.stringify(
+        {
+          name: "no-contract-project",
+          controlPlane: {
+            secrets: {
+              backend: "encrypted_file",
+              encryptedFile: {
+                path: encryptedStorePath,
+              },
+            },
+          },
+        },
+        null,
+        2
+      )}\n`
+    );
+
+    const result = await runHack({
+      args: ["env", "list"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+        HACK_LOGGER: "console",
+        HACK_SECRETS_FILE_KEY: "env-storage-no-contract-key",
+      },
+      cwd: projectRoot,
+    });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("Env storage");
+    expect(result.stdout).toContain(resolve(projectDir, "hack.env.json"));
+    expect(result.stdout).toContain(resolve(projectDir, ".env"));
+    expect(result.stdout).toContain("not_configured");
+    expect(result.stderr).toContain("No");
+    expect(result.stderr).toContain("hack.env.json contract found");
+  }
+);
 
 async function runHack(input: {
   readonly args: readonly string[];

From 1f984b2c9edfa028406312d95d00b9e758e13cba Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 22:37:19 +0000
Subject: [PATCH 004/134] docs: add tickets normalization core plan

---
 ...03-13-tickets-normalization-core-design.md | 426 ++++++++++++++++++
 ...6-03-13-tickets-normalization-core-plan.md | 382 ++++++++++++++++
 2 files changed, 808 insertions(+)
 create mode 100644 docs/plans/2026-03-13-tickets-normalization-core-design.md
 create mode 100644 docs/plans/2026-03-13-tickets-normalization-core-plan.md

diff --git a/docs/plans/2026-03-13-tickets-normalization-core-design.md b/docs/plans/2026-03-13-tickets-normalization-core-design.md
new file mode 100644
index 000000000..dfc62c2c6
--- /dev/null
+++ b/docs/plans/2026-03-13-tickets-normalization-core-design.md
@@ -0,0 +1,426 @@
+# Tickets Normalization Core Design
+
+## Program Outcome
+
+This program ticket does not attempt to land the full normalization rewrite in one branch. Its implementation outcome is:
+
+- a repo-visible design that makes storage direction, sync direction, and normalized entities explicit
+- a concrete child-workstream breakdown for storage, provenance, sync, and documents
+- hidden-ref ticket records that preserve the work breakdown inside Hack Tickets itself
+
+The functional implementation should land incrementally through the child tickets rather than as an all-at-once migration under `HACK-431`.
+
+## Context
+
+Hack Tickets already has a useful local-first shape:
+
+- append-only JSONL events under `.hack/tickets/events/`
+- git portability via the dedicated tickets ref managed by `src/control-plane/extensions/tickets/tickets-git-channel.ts`
+- an in-memory materialized store in `src/control-plane/extensions/tickets/store.ts`
+- sync metadata already embedded in ticket records through `external*`, checkpoint, conflict, and review-note events
+
+That is enough for manual workflows and the current Linear integration, but it leaves a structural gap:
+
+- the normalized ticket entity is implicit in event reducers instead of being a first-class model
+- provenance is spread across ad hoc fields instead of a consistent identity/change-authority model
+- materialization is process-local rather than durable
+- richer ticket documents are flattened into `body` instead of being tracked as typed projections
+
+This stream should make Tickets the canonical normalized work model without losing the properties that already matter:
+
+- local-first operation
+- git portability
+- hidden-ref sync
+- append-only auditability
+- compatibility with current ticket commands and integrations
+
+## Goals
+
+- Define an explicit normalized ticket entity and provenance model.
+- Introduce a durable SQLite projection fed by the append-only journal.
+- Keep the journal and hidden-ref sync as the portable source format.
+- Make sync direction and conflict semantics explicit and idempotent.
+- Add a path for markdown-backed ticket documents and specs as first-class records.
+
+## Non-Goals
+
+- Replacing git-backed event storage with SQLite as the transport format.
+- Building every downstream integration in this ticket.
+- Changing the current CLI UX beyond what is needed to expose the normalized model.
+- Introducing rich-text or binary document storage in the first normalization pass.
+
+## Current State
+
+Today the source of truth is effectively:
+
+1. append JSONL events to `.hack/tickets/events/events-YYYY-MM.jsonl`
+2. normalize and sync those logs through `tickets-git-channel.ts`
+3. read all events into memory and materialize `TicketSummary`, comments, review notes, checkpoints, and conflicts in `store.ts`
+
+That model is simple and portable, but it conflates three concerns:
+
+- journal transport
+- normalized domain state
+- process-local query projection
+
+The result is that sync and provenance rules exist, but they are encoded as reducer behavior instead of a documented durable model.
+
+## Approaches Considered
+
+### 1. Keep JSONL-only and improve reducer structure
+
+Pros:
+
+- lowest migration cost
+- preserves current portability
+
+Cons:
+
+- no durable local projection
+- expensive cold reads keep growing with log size
+- provenance and document support stay implicit
+
+### 2. Make SQLite the new primary store and export JSONL from it
+
+Pros:
+
+- simpler local querying
+- easier relational modeling
+
+Cons:
+
+- portability becomes derived instead of native
+- hidden-ref sync becomes a secondary export path
+- raises trust questions around journal determinism and merge behavior
+
+### 3. Keep the append-only journal as canonical, add a deterministic SQLite projection, and model normalized entities/provenance explicitly
+
+Pros:
+
+- preserves local-first git portability
+- gives durable query performance
+- makes sync semantics and document support explicit
+- allows idempotent rebuild from journal at any time
+
+Cons:
+
+- two storage layers to maintain
+- needs careful projection versioning and replay semantics
+
+### Recommendation
+
+Choose option 3.
+
+The journal should remain the canonical transport and audit format. SQLite should be a deterministic projection cache plus query layer, never the only copy of portable ticket state.
+
+## Proposed Model
+
+### Source-of-truth direction
+
+The storage direction should be explicit:
+
+1. Commands and integrations append normalized events to the journal.
+2. The journal is the portable canonical record synced through the hidden git ref.
+3. SQLite is rebuilt or incrementally updated from journal events.
+4. Read paths prefer SQLite once present, with replay fallback if projection state is absent or stale.
+
+This keeps portability intact while removing the requirement that every read rebuild state from scratch.
+
+### Layering
+
+#### 1. Journal layer
+
+Stored under `.hack/tickets/events/` as append-only JSONL segments.
+
+Responsibilities:
+
+- preserve all state transitions as immutable facts
+- remain mergeable and git-syncable
+- carry enough event metadata for deterministic projection
+
+Required additions:
+
+- explicit journal envelope version
+- stable event ids for idempotent replay
+- causality metadata for external sync events
+- typed document events instead of overloading `ticket.updated` body changes
+
+#### 2. Normalized domain layer
+
+New first-class model for:
+
+- ticket identity
+- ticket fields
+- provenance and authority
+- external links and remote mappings
+- typed documents
+- sync checkpoints and conflicts
+
+This layer is conceptual and code-level. It should not depend on whether the backing read path is replay or SQLite.
+
+#### 3. SQLite projection layer
+
+Stored locally under `.hack/tickets/` as a rebuildable projection database.
+
+Responsibilities:
+
+- durable materialized reads
+- indexed lookup by ticket id, external identity, status, assignee, project, and updated time
+- document lookup and search metadata
+- replay bookkeeping for incremental projection
+
+SQLite is not a sync target. If deleted, it must be recreated from the journal without losing correctness.
+
+## Normalized Entities
+
+### Ticket
+
+Core ticket row with stable Hack identity:
+
+- `ticket_id`
+- `project_id`
+- `project_name`
+- `status`
+- `title`
+- `current_document_id`
+- `created_at`
+- `updated_at`
+- `closed_at`
+
+This should no longer carry every remote-specific field directly. Remote linkage belongs in provenance tables.
+
+### Ticket provenance
+
+Explicit provenance should answer:
+
+- where this ticket originated
+- which system owns which field
+- which remote objects correspond to this local ticket
+- which event last changed a field
+
+Recommended normalized concepts:
+
+- `ticket_origins`
+  - first local source for a ticket such as `hack` or `linear`
+- `ticket_remotes`
+  - one row per provider/profile/remote object link
+- `ticket_field_authority`
+  - per-field authority rule such as `local`, `remote`, `append_only`, `derived`, `review_required`
+- `ticket_field_versions`
+  - last-applied value, source event id, actor, and timestamp for conflict detection/audit
+
+This replaces the current mixed use of `owner`, `source`, and `external*` fields as the only provenance representation.
+
+### Ticket documents
+
+The current `body` field should become a convenience projection over a typed document model.
+
+Recommended normalized concepts:
+
+- `ticket_documents`
+  - immutable markdown snapshots with `document_id`, `ticket_id`, `kind`, `content_sha256`, `content`, `created_at`, `actor`
+- `ticket_document_links`
+  - logical roles such as `description`, `spec`, `notes`, `handoff`
+
+`kind` should start with:
+
+- `description`
+- `spec`
+- `notes`
+
+This keeps markdown-backed ticket docs portable while allowing richer behavior later.
+
+### Activity streams
+
+Retain append-only records for:
+
+- comments
+- review notes
+- sync checkpoints
+- sync conflicts
+- conflict resolutions
+
+These can remain event-backed and project into dedicated SQLite tables with stable ids.
+
+## Journal Envelope
+
+Every event should project from a normalized journal envelope:
+
+- `eventId`
+- `schemaVersion`
+- `eventType`
+- `ticketId`
+- `occurredAt`
+- `recordedAt`
+- `actor`
+- `sourceSystem`
+- `sourceOperation`
+- `idempotencyKey`
+- `causationId`
+- `correlationId`
+- `payload`
+
+Notes:
+
+- `eventId` and `idempotencyKey` must make replay safe.
+- `occurredAt` preserves remote source ordering when known.
+- `recordedAt` preserves local append time.
+- `sourceOperation` distinguishes local edits, remote pulls, webhook applies, and repair flows.
+
+## SQLite Projection
+
+### Proposed tables
+
+- `projection_meta`
+- `journal_events`
+- `tickets`
+- `ticket_origins`
+- `ticket_remotes`
+- `ticket_field_authority`
+- `ticket_field_versions`
+- `ticket_documents`
+- `ticket_document_links`
+- `ticket_comments`
+- `ticket_review_notes`
+- `ticket_sync_checkpoints`
+- `ticket_sync_conflicts`
+
+### Projection rules
+
+- Journal replay is strictly append-only by `eventId`.
+- `journal_events` stores applied ids and replay metadata.
+- Rebuild mode drops and recreates derived tables from journal files.
+- Incremental mode applies only unseen events.
+- Projection version changes trigger a rebuild.
+
+### Read-path rules
+
+- CLI read commands should prefer SQLite snapshots.
+- If SQLite is missing or projection metadata is incompatible, rebuild from journal automatically.
+- A JSONL-only fallback should remain available for recovery and tests.
+
+## Sync Semantics
+
+### Portable sync
+
+Portable sync remains journal-first:
+
+- sync pushes the journal through the hidden ref
+- no SQLite files are pushed
+- peers rebuild their projection locally after fetch or on first read
+
+### Idempotent external sync
+
+External sync must treat journal append as the local mutation boundary.
+
+Rules:
+
+- remote changes map to deterministic journal events
+- repeated delivery of the same remote mutation must reuse the same `idempotencyKey` or remote event identity
+- applying the same remote change twice must be a no-op at the projection layer
+- outbound sync checkpoints must record the last remote cursor or updated-at observed per remote link
+
+### Conflict semantics
+
+Conflicts should become explicit policy instead of inferred behavior.
+
+Per field, choose one of:
+
+- `local`
+- `remote`
+- `append_only`
+- `derived`
+- `review_required`
+
+Initial policy:
+
+- comments: `append_only`
+- review notes: `local`
+- sync checkpoints: `derived`
+- conflict records: `derived`
+- title/status/assignee/description: provider-specific, but persisted as explicit authority rules per remote link
+
+When a field marked `review_required` diverges, the system should:
+
+1. append a conflict event
+2. leave the current materialized value unchanged
+3. require an explicit resolution event
+
+## Markdown-Backed Ticket Documents
+
+Markdown-backed docs should be first-class without breaking the current CLI shape.
+
+### Storage model
+
+- keep documents as UTF-8 markdown in the journal payload and SQLite projection
+- expose the current description as the compatibility `body` projection
+- allow additional docs like `spec` and `notes` to exist alongside the default description
+
+### File materialization
+
+The first pass should not require checked-in document files on the main branch.
+
+Instead:
+
+- documents live in the ticket journal and SQLite projection
+- optional file export/import can come later as a projection or command
+
+This preserves hidden-ref portability and avoids creating a second source of truth immediately.
+
+## Migration Strategy
+
+### Phase 1
+
+- Introduce normalized domain types and journal envelope versioning.
+- Keep current JSONL file layout.
+- Add SQLite projection schema and rebuild path.
+- Backfill current `TicketSummary` reads from the projection adapter.
+
+### Phase 2
+
+- Migrate external sync logic to provenance and authority tables.
+- Introduce typed document events and compatibility body projection.
+
+### Phase 3
+
+- Add richer queries and optional document-oriented commands or exports.
+
+## Child Workstreams
+
+This program should be decomposed into four child tickets:
+
+1. `T-00001` Storage: normalized entity schema plus SQLite projection and replay.
+2. `T-00002` Provenance: ticket origin, remote identity, field authority, and field version audit model.
+3. `T-00003` Sync: idempotent external sync, checkpoint semantics, and conflict policy.
+4. `T-00004` Documents: markdown-backed description/spec/notes support and compatibility projection.
+
+### Execution order
+
+- Start with `T-00001` because it defines the normalized storage and projection contract.
+- Take `T-00002` next because provenance and field authority depend on the storage shape.
+- After `T-00001` and `T-00002`, `T-00003` and `T-00004` can proceed independently.
+
+### Program completion semantics
+
+`HACK-431` is complete when this design is landed, the implementation plan is landed, and the child tickets exist with the dependencies above. The code changes for normalization itself belong to the child tickets.
+
+## Risks
+
+- SQLite can accidentally become the de facto source of truth if write paths bypass the journal.
+- Rebuild logic must be deterministic across machines and Bun versions.
+- Existing integrations may implicitly rely on ad hoc `external*` fields and need a compatibility layer.
+- Document typing can become over-designed if the first pass tries to support too many document kinds.
+
+## Validation
+
+The implementation should prove:
+
+- deleting the SQLite file does not lose state
+- replaying the same journal twice is idempotent
+- hidden-ref sync transfers all portable ticket state without the SQLite database
+- conflicting remote updates create explicit conflict rows/events
+- description/spec markdown documents round-trip through journal, projection, and CLI reads
+
+## Recommended Next Step
+
+Implement the program as journal-first normalization, not as a database migration away from git-backed tickets.
diff --git a/docs/plans/2026-03-13-tickets-normalization-core-plan.md b/docs/plans/2026-03-13-tickets-normalization-core-plan.md
new file mode 100644
index 000000000..6ba5a5c8f
--- /dev/null
+++ b/docs/plans/2026-03-13-tickets-normalization-core-plan.md
@@ -0,0 +1,382 @@
+# Tickets Normalization Core Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+## Program Scope
+
+This plan is the implementation handoff for `HACK-431`, not an instruction to land the entire normalization effort in one branch. The branch-level deliverable for the program ticket is:
+
+- land this plan and the paired design doc in the repo
+- create and link the child tickets in Hack Tickets
+- identify the execution order so the normalization work can proceed incrementally
+
+**Goal:** Define and implement a journal-first normalized ticket model with a durable SQLite projection, explicit provenance semantics, idempotent sync behavior, and markdown-backed ticket documents.
+
+**Architecture:** Keep `.hack/tickets/events/*.jsonl` and hidden-ref sync as the canonical portable record. Introduce normalized ticket/provenance/document domain types and a rebuildable SQLite projection under `.hack/tickets/`, then migrate current read paths and sync logic onto that model behind compatibility adapters.
+
+**Tech Stack:** Bun, TypeScript, `bun:sqlite`, current tickets extension modules in `src/control-plane/extensions/tickets/`, current Linear sync code in `src/control-plane/extensions/linear/commands.ts`, Bun tests.
+
+---
+
+## Child Ticket Mapping
+
+- `T-00001`: Implement normalized tickets storage and SQLite projection
+- `T-00002`: Implement normalized ticket provenance and field authority model
+- `T-00003`: Implement idempotent ticket sync and explicit conflict semantics
+- `T-00004`: Implement markdown-backed ticket documents and spec support
+
+Recommended execution order:
+
+- `T-00001`
+- `T-00002`
+- `T-00003` and `T-00004` in parallel after the first two land
+
+Program closeout checklist:
+
+- design doc committed
+- implementation plan committed
+- `T-00001` through `T-00004` created with dependency edges
+- next execution step set to `T-00001`
+
+---
+
+### Task 1: Define the normalized tickets domain module
+
+**Files:**
+
+- Create: `src/control-plane/extensions/tickets/domain.ts`
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Modify: `src/control-plane/extensions/tickets/util.ts`
+- Test: `tests/tickets-store.test.ts`
+
+**Step 1: Write the failing test**
+
+Add assertions in `tests/tickets-store.test.ts` for a normalized domain adapter that can represent:
+
+- stable ticket identity
+- provenance metadata
+- typed ticket documents
+- explicit authority/conflict state
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/tickets-store.test.ts` Expected: FAIL because the normalized domain module and adapter do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Create `src/control-plane/extensions/tickets/domain.ts` with:
+
+- journal envelope types
+- normalized ticket types
+- provenance types
+- document types
+- compatibility helpers that map the new normalized model to current `TicketSummary`
+
+Keep `store.ts` using current public return shapes while routing internal state through the new types.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/tickets-store.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/domain.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/util.ts tests/tickets-store.test.ts
+git commit -m "feat: define normalized tickets domain model"
+```
+
+### Task 2: Add journal envelope versioning and deterministic replay ids
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Modify: `src/control-plane/extensions/tickets/tickets-git-channel.ts`
+- Modify: `src/control-plane/extensions/tickets/util.ts`
+- Test: `tests/tickets-store.test.ts`
+- Test: `tests/tickets-git-channel.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests proving:
+
+- every written event carries schema version and stable replay identity
+- replaying duplicate external events is ignored
+- log normalization preserves the new envelope fields
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/tickets-store.test.ts tests/tickets-git-channel.test.ts` Expected: FAIL because existing event writes do not include the full normalized envelope.
+
+**Step 3: Write minimal implementation**
+
+Update event creation helpers so every journal event records:
+
+- `eventId`
+- `schemaVersion`
+- `occurredAt`
+- `recordedAt`
+- `sourceSystem`
+- `sourceOperation`
+- `idempotencyKey`
+- `causationId`
+- `correlationId`
+
+Keep backward-compatible replay support for legacy events during migration.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/tickets-store.test.ts tests/tickets-git-channel.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/tickets-git-channel.ts src/control-plane/extensions/tickets/util.ts tests/tickets-store.test.ts tests/tickets-git-channel.test.ts
+git commit -m "feat: version ticket journal envelopes"
+```
+
+### Task 3: Implement the SQLite projection
+
+**Files:**
+
+- Create: `src/control-plane/extensions/tickets/sqlite-projection.ts`
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Modify: `src/control-plane/extensions/tickets/extension.ts`
+- Test: `tests/tickets-store.test.ts`
+- Test: `tests/tickets-extension.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests proving:
+
+- the projection database is created under `.hack/tickets/`
+- reads come back after process restart without replaying the full reducer in memory
+- deleting the SQLite file triggers a rebuild from journal files
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/tickets-store.test.ts tests/tickets-extension.test.ts` Expected: FAIL because there is no SQLite projection layer yet.
+
+**Step 3: Write minimal implementation**
+
+Create `src/control-plane/extensions/tickets/sqlite-projection.ts` using `bun:sqlite` with:
+
+- projection metadata table
+- journal event bookkeeping
+- tickets table
+- activity tables for comments, review notes, checkpoints, and conflicts
+
+Update `store.ts` so writes still append to journal first, then project into SQLite.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/tickets-store.test.ts tests/tickets-extension.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/sqlite-projection.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/extension.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts
+git commit -m "feat: add tickets sqlite projection"
+```
+
+### Task 4: Normalize provenance and remote identity
+
+**Files:**
+
+- Create: `src/control-plane/extensions/tickets/provenance.ts`
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Modify: `src/control-plane/extensions/linear/commands.ts`
+- Test: `tests/tickets-store.test.ts`
+- Test: `tests/linear-commands.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests that require:
+
+- one ticket to link to one or more remote provider objects
+- per-field authority to be explicit
+- sync conflict creation to cite the last known local and remote field versions
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/tickets-store.test.ts tests/linear-commands.test.ts` Expected: FAIL because provenance is still inferred from ad hoc fields.
+
+**Step 3: Write minimal implementation**
+
+Create `src/control-plane/extensions/tickets/provenance.ts` with:
+
+- remote link types
+- authority enums
+- field version records
+- helpers for mapping current `external*` values into the normalized provenance model
+
+Update Linear sync code to read and write through the new provenance layer instead of relying only on top-level `external*` fields.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/tickets-store.test.ts tests/linear-commands.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/provenance.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/linear/commands.ts tests/tickets-store.test.ts tests/linear-commands.test.ts
+git commit -m "feat: normalize ticket provenance"
+```
+
+### Task 5: Add typed markdown-backed ticket documents
+
+**Files:**
+
+- Create: `src/control-plane/extensions/tickets/documents.ts`
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Modify: `src/control-plane/extensions/tickets/commands.ts`
+- Modify: `src/tui/tickets-tui.ts`
+- Test: `tests/tickets-store.test.ts`
+- Test: `tests/tickets-extension.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests proving:
+
+- a ticket can have a `description` document and a `spec` document
+- the current `body` field remains available as the compatibility projection of the active description document
+- document updates append immutable document events instead of mutating prior content
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/tickets-store.test.ts tests/tickets-extension.test.ts` Expected: FAIL because ticket documents are still just a mutable `body` field.
+
+**Step 3: Write minimal implementation**
+
+Create `src/control-plane/extensions/tickets/documents.ts` with:
+
+- document kind enum
+- immutable document snapshot types
+- compatibility helpers for `body`
+
+Update commands and TUI reads so they can show the active description now and later expose additional document kinds safely.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/tickets-store.test.ts tests/tickets-extension.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/documents.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/commands.ts src/tui/tickets-tui.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts
+git commit -m "feat: add markdown-backed ticket documents"
+```
+
+### Task 6: Make external sync idempotent against the normalized model
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/linear/commands.ts`
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Modify: `src/control-plane/extensions/tickets/provenance.ts`
+- Test: `tests/linear-commands.test.ts`
+- Test: `tests/tickets-store.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+
+- duplicate webhook or poll deliveries
+- repeated outbound checkpoint updates
+- review-required conflicts when authority cannot resolve a field automatically
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/linear-commands.test.ts tests/tickets-store.test.ts` Expected: FAIL because idempotency and authority are not fully normalized yet.
+
+**Step 3: Write minimal implementation**
+
+Update Linear sync handlers so remote operations derive deterministic idempotency keys and only append journal events when the remote mutation is genuinely new. Persist checkpoint and conflict semantics against the provenance model.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/linear-commands.test.ts tests/tickets-store.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/linear/commands.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/provenance.ts tests/linear-commands.test.ts tests/tickets-store.test.ts
+git commit -m "feat: make ticket sync idempotent"
+```
+
+### Task 7: Validate hidden-ref portability and rebuild behavior end to end
+
+**Files:**
+
+- Modify: `tests/tickets-git-channel.test.ts`
+- Modify: `tests/tickets-extension.test.ts`
+- Modify: `docs/guides/tickets.md`
+
+**Step 1: Write the failing test**
+
+Add coverage that proves:
+
+- the hidden-ref sync moves journal files only
+- peers rebuild local projection state after sync
+- deleting local SQLite state does not affect synced ticket history
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts` Expected: FAIL until projection rebuild and docs are aligned.
+
+**Step 3: Write minimal implementation**
+
+Adjust tests and docs so the portability contract is explicit: JSONL journal is portable, SQLite is local and rebuildable, and read paths repair projection state automatically.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts` Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts docs/guides/tickets.md
+git commit -m "docs: clarify normalized tickets portability"
+```
+
+### Task 8: Full verification
+
+**Files:**
+
+- Verify all touched tickets and Linear files
+- Modify: docs if verification reveals contract drift
+
+**Step 1: Run verification gates**
+
+Run:
+
+```bash
+bun test tests/tickets-store.test.ts tests/tickets-extension.test.ts tests/tickets-git-channel.test.ts tests/linear-commands.test.ts
+bun run check
+```
+
+Expected: PASS
+
+**Step 2: Perform manual sanity checks**
+
+Verify:
+
+- `hack tickets create/list/show/update/status` still work
+- journal files remain under `.hack/tickets/events/`
+- projection rebuild happens when the SQLite file is removed
+- remote sync behavior remains idempotent for repeated inbound changes
+- description/spec documents render correctly through the current CLI compatibility path
+
+**Step 3: Commit final integrated changes**
+
+```bash
+git add src/control-plane/extensions/tickets/domain.ts src/control-plane/extensions/tickets/sqlite-projection.ts src/control-plane/extensions/tickets/provenance.ts src/control-plane/extensions/tickets/documents.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/tickets-git-channel.ts src/control-plane/extensions/tickets/commands.ts src/control-plane/extensions/tickets/util.ts src/control-plane/extensions/tickets/extension.ts src/control-plane/extensions/linear/commands.ts src/tui/tickets-tui.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts tests/tickets-git-channel.test.ts tests/linear-commands.test.ts docs/guides/tickets.md
+git commit -m "feat: normalize tickets storage and sync"
+```
+
+Plan complete and saved to `docs/plans/2026-03-13-tickets-normalization-core-plan.md`. Two execution options:
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+**Which approach?**

From b192f04a0febd134f0b477d00d6d913ebc23da3e Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 22:37:32 +0000
Subject: [PATCH 005/134] feat(tickets): normalize ticket replay metadata

---
 .../extensions/tickets/domain.ts              | 336 ++++++++++++++++++
 src/control-plane/extensions/tickets/store.ts | 309 ++++++++++------
 .../extensions/tickets/tickets-git-channel.ts |  33 +-
 src/control-plane/extensions/tickets/util.ts  |   6 +
 tests/tickets-git-channel.test.ts             | 106 +++++-
 tests/tickets-store.test.ts                   | 206 +++++++++++
 6 files changed, 892 insertions(+), 104 deletions(-)
 create mode 100644 src/control-plane/extensions/tickets/domain.ts

diff --git a/src/control-plane/extensions/tickets/domain.ts b/src/control-plane/extensions/tickets/domain.ts
new file mode 100644
index 000000000..4e11cd67e
--- /dev/null
+++ b/src/control-plane/extensions/tickets/domain.ts
@@ -0,0 +1,336 @@
+import { sha256Hex } from "./util.ts";
+
+export type TicketStatus = "open" | "in_progress" | "blocked" | "done";
+
+export type TicketSummaryCompatibility = {
+  readonly ticketId: string;
+  readonly title: string;
+  readonly body?: string;
+  readonly status: TicketStatus;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly dependsOn: readonly string[];
+  readonly blocks: readonly string[];
+  readonly owner: string;
+  readonly source: string;
+  readonly assignee?: string;
+  readonly tags: readonly string[];
+  readonly externalSystem?: string;
+  readonly externalId?: string;
+  readonly externalKey?: string;
+  readonly externalUrl?: string;
+  readonly externalProjectId?: string;
+  readonly externalProjectName?: string;
+  readonly externalTeamId?: string;
+  readonly projectId?: string;
+  readonly projectName?: string;
+};
+
+export type TicketMetadataValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly TicketMetadataValue[]
+  | { readonly [key: string]: TicketMetadataValue };
+
+export type TicketSyncCheckpointCompatibility = {
+  readonly checkpointId: string;
+  readonly ticketId: string;
+  readonly provider: string;
+  readonly profileId?: string;
+  readonly direction?: string;
+  readonly remoteCursor?: string;
+  readonly remoteUpdatedAt?: string;
+  readonly localUpdatedAt?: string;
+  readonly actor: string;
+  readonly createdAt: string;
+};
+
+export type TicketSyncConflictCompatibility = {
+  readonly conflictId: string;
+  readonly ticketId: string;
+  readonly provider: string;
+  readonly field: string;
+  readonly status: "open" | "resolved";
+  readonly authority?: string;
+  readonly summary?: string;
+  readonly localValue?: TicketMetadataValue;
+  readonly remoteValue?: TicketMetadataValue;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly resolution?: "accept_local" | "accept_remote" | "merged" | "ignore";
+  readonly resolutionSummary?: string;
+  readonly resolvedAt?: string;
+  readonly resolvedBy?: string;
+};
+
+export type NormalizedTicketIdentity = {
+  readonly ticketId: string;
+  readonly projectId?: string;
+  readonly projectName?: string;
+};
+
+export type TicketOrigin = {
+  readonly owner: string;
+  readonly source: string;
+  readonly system: string;
+};
+
+export type TicketRemoteLink = {
+  readonly provider: string;
+  readonly remoteId?: string;
+  readonly remoteKey?: string;
+  readonly remoteUrl?: string;
+  readonly projectId?: string;
+  readonly projectName?: string;
+  readonly teamId?: string;
+};
+
+export type TicketDocumentKind = "description" | "spec" | "notes";
+export type TicketDocumentRole = TicketDocumentKind | "handoff";
+
+export type TicketDocument = {
+  readonly documentId: string;
+  readonly ticketId: string;
+  readonly kind: TicketDocumentKind;
+  readonly role: TicketDocumentRole;
+  readonly content: string;
+  readonly contentSha256: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+export type TicketFieldState = {
+  readonly field: string;
+  readonly authority: string;
+  readonly conflictIds: readonly string[];
+};
+
+export type NormalizedTicket = {
+  readonly identity: NormalizedTicketIdentity;
+  readonly title: string;
+  readonly status: TicketStatus;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly dependsOn: readonly string[];
+  readonly blocks: readonly string[];
+  readonly assignee?: string;
+  readonly tags: readonly string[];
+  readonly provenance: {
+    readonly origin: TicketOrigin;
+    readonly remotes: readonly TicketRemoteLink[];
+  };
+  readonly documents: readonly TicketDocument[];
+  readonly fieldStates: readonly TicketFieldState[];
+  readonly sync: {
+    readonly checkpoints: readonly TicketSyncCheckpointCompatibility[];
+    readonly conflicts: readonly TicketSyncConflictCompatibility[];
+  };
+};
+
+export function createNormalizedTicket(input: {
+  readonly ticket: TicketSummaryCompatibility;
+  readonly syncCheckpoints?: readonly TicketSyncCheckpointCompatibility[];
+  readonly conflicts?: readonly TicketSyncConflictCompatibility[];
+}): NormalizedTicket {
+  const sourceSystem = inferSourceSystem({ ticket: input.ticket });
+  const documents = buildDocuments({ ticket: input.ticket });
+  const remotes = buildRemoteLinks({
+    ticket: input.ticket,
+    sourceSystem,
+  });
+  const checkpoints = input.syncCheckpoints ?? [];
+  const conflicts = input.conflicts ?? [];
+
+  return {
+    identity: {
+      ticketId: input.ticket.ticketId,
+      ...(input.ticket.projectId ? { projectId: input.ticket.projectId } : {}),
+      ...(input.ticket.projectName
+        ? { projectName: input.ticket.projectName }
+        : {}),
+    },
+    title: input.ticket.title,
+    status: input.ticket.status,
+    createdAt: input.ticket.createdAt,
+    updatedAt: input.ticket.updatedAt,
+    dependsOn: [...input.ticket.dependsOn],
+    blocks: [...input.ticket.blocks],
+    ...(input.ticket.assignee ? { assignee: input.ticket.assignee } : {}),
+    tags: [...input.ticket.tags],
+    provenance: {
+      origin: {
+        owner: input.ticket.owner,
+        source: input.ticket.source,
+        system: sourceSystem,
+      },
+      remotes,
+    },
+    documents,
+    fieldStates: buildFieldStates({ remotes, conflicts }),
+    sync: {
+      checkpoints: [...checkpoints],
+      conflicts: [...conflicts],
+    },
+  };
+}
+
+export function projectNormalizedTicketSummary(input: {
+  readonly ticket: NormalizedTicket;
+}): TicketSummaryCompatibility {
+  const description = input.ticket.documents.find(
+    (document) => document.role === "description"
+  );
+  const primaryRemote = input.ticket.provenance.remotes[0];
+
+  return {
+    ticketId: input.ticket.identity.ticketId,
+    title: input.ticket.title,
+    ...(description ? { body: description.content } : {}),
+    status: input.ticket.status,
+    createdAt: input.ticket.createdAt,
+    updatedAt: input.ticket.updatedAt,
+    dependsOn: [...input.ticket.dependsOn],
+    blocks: [...input.ticket.blocks],
+    owner: input.ticket.provenance.origin.owner,
+    source: input.ticket.provenance.origin.source,
+    ...(input.ticket.assignee ? { assignee: input.ticket.assignee } : {}),
+    tags: [...input.ticket.tags],
+    ...(primaryRemote
+      ? {
+          externalSystem: primaryRemote.provider,
+          ...(primaryRemote.remoteId
+            ? { externalId: primaryRemote.remoteId }
+            : {}),
+          ...(primaryRemote.remoteKey
+            ? { externalKey: primaryRemote.remoteKey }
+            : {}),
+          ...(primaryRemote.remoteUrl
+            ? { externalUrl: primaryRemote.remoteUrl }
+            : {}),
+          ...(primaryRemote.projectId
+            ? { externalProjectId: primaryRemote.projectId }
+            : {}),
+          ...(primaryRemote.projectName
+            ? { externalProjectName: primaryRemote.projectName }
+            : {}),
+          ...(primaryRemote.teamId
+            ? { externalTeamId: primaryRemote.teamId }
+            : {}),
+        }
+      : {}),
+    ...(input.ticket.identity.projectId
+      ? { projectId: input.ticket.identity.projectId }
+      : {}),
+    ...(input.ticket.identity.projectName
+      ? { projectName: input.ticket.identity.projectName }
+      : {}),
+  };
+}
+
+function inferSourceSystem(input: {
+  readonly ticket: TicketSummaryCompatibility;
+}): string {
+  if (input.ticket.externalSystem) {
+    return input.ticket.externalSystem;
+  }
+  if (input.ticket.source !== "hack") {
+    return input.ticket.source;
+  }
+  if (input.ticket.owner !== "hack") {
+    return input.ticket.owner;
+  }
+  return "hack";
+}
+
+function buildDocuments(input: {
+  readonly ticket: TicketSummaryCompatibility;
+}): TicketDocument[] {
+  if (!input.ticket.body) {
+    return [];
+  }
+
+  const contentSha256 = sha256Hex({ value: input.ticket.body });
+  return [
+    {
+      documentId: `${input.ticket.ticketId}:description:${contentSha256.slice(0, 12)}`,
+      ticketId: input.ticket.ticketId,
+      kind: "description",
+      role: "description",
+      content: input.ticket.body,
+      contentSha256,
+      createdAt: input.ticket.createdAt,
+      updatedAt: input.ticket.updatedAt,
+    },
+  ];
+}
+
+function buildRemoteLinks(input: {
+  readonly ticket: TicketSummaryCompatibility;
+  readonly sourceSystem: string;
+}): TicketRemoteLink[] {
+  if (
+    !(
+      input.ticket.externalSystem ||
+      input.ticket.externalId ||
+      input.ticket.externalKey ||
+      input.ticket.externalUrl ||
+      input.ticket.externalProjectId ||
+      input.ticket.externalProjectName ||
+      input.ticket.externalTeamId
+    )
+  ) {
+    return [];
+  }
+
+  return [
+    {
+      provider: input.ticket.externalSystem ?? input.sourceSystem,
+      ...(input.ticket.externalId ? { remoteId: input.ticket.externalId } : {}),
+      ...(input.ticket.externalKey
+        ? { remoteKey: input.ticket.externalKey }
+        : {}),
+      ...(input.ticket.externalUrl
+        ? { remoteUrl: input.ticket.externalUrl }
+        : {}),
+      ...(input.ticket.externalProjectId
+        ? { projectId: input.ticket.externalProjectId }
+        : {}),
+      ...(input.ticket.externalProjectName
+        ? { projectName: input.ticket.externalProjectName }
+        : {}),
+      ...(input.ticket.externalTeamId
+        ? { teamId: input.ticket.externalTeamId }
+        : {}),
+    },
+  ];
+}
+
+function buildFieldStates(input: {
+  readonly remotes: readonly TicketRemoteLink[];
+  readonly conflicts: readonly TicketSyncConflictCompatibility[];
+}): TicketFieldState[] {
+  const defaultAuthority = input.remotes.length > 0 ? "remote" : "local";
+  const byField = new Map<string, TicketFieldState>();
+
+  for (const field of ["title", "status", "assignee", "description"]) {
+    byField.set(field, {
+      field,
+      authority: defaultAuthority,
+      conflictIds: [],
+    });
+  }
+
+  for (const conflict of input.conflicts) {
+    const current = byField.get(conflict.field);
+    const conflictIds = [...(current?.conflictIds ?? []), conflict.conflictId];
+    byField.set(conflict.field, {
+      field: conflict.field,
+      authority: conflict.authority ?? current?.authority ?? defaultAuthority,
+      conflictIds,
+    });
+  }
+
+  return [...byField.values()];
+}
diff --git a/src/control-plane/extensions/tickets/store.ts b/src/control-plane/extensions/tickets/store.ts
index cdf69ba2c..aa855a129 100644
--- a/src/control-plane/extensions/tickets/store.ts
+++ b/src/control-plane/extensions/tickets/store.ts
@@ -5,6 +5,10 @@ import { resolve } from "node:path";
 
 import { isRecord } from "../../../lib/guards.ts";
 import type { ControlPlaneConfig } from "../../sdk/config.ts";
+import {
+  createNormalizedTicket,
+  projectNormalizedTicketSummary,
+} from "./domain.ts";
 import { createGitTicketsChannel } from "./tickets-git-channel.ts";
 import {
   formatTicketId,
@@ -106,9 +110,18 @@ export type TicketSyncConflict = {
 
 export type TicketEvent = {
   readonly eventId: string;
+  readonly schemaVersion: number;
   readonly ts: number;
   readonly tsIso: string;
+  readonly eventType: string;
+  readonly occurredAt: string;
+  readonly recordedAt: string;
   readonly actor: string;
+  readonly sourceSystem: string;
+  readonly sourceOperation: string;
+  readonly idempotencyKey: string;
+  readonly causationId?: string;
+  readonly correlationId?: string;
   readonly orderKey?: string;
   readonly projectId?: string;
   readonly projectName?: string;
@@ -157,6 +170,16 @@ type MaterializedTicketState = {
   readonly conflictsByTicket: Map<string, TicketSyncConflict[]>;
 };
 
+function normalizeTicketSummaryCompatibility(input: {
+  readonly ticket: TicketSummary;
+}): TicketSummary {
+  return projectNormalizedTicketSummary({
+    ticket: createNormalizedTicket({
+      ticket: input.ticket,
+    }),
+  });
+}
+
 export function createTicketsStore(opts: {
   readonly projectRoot: string;
   readonly projectId?: string;
@@ -316,15 +339,32 @@ export function createTicketsStore(opts: {
     readonly type: string;
     readonly payload: Record<string, unknown>;
     readonly actor?: string;
+    readonly occurredAt?: string;
+    readonly sourceSystem?: string;
+    readonly sourceOperation?: string;
+    readonly idempotencyKey?: string;
+    readonly causationId?: string;
+    readonly correlationId?: string;
   }): TicketEvent => {
     const ts = unixSeconds();
+    const recordedAt = new Date(ts * 1000).toISOString();
+    const eventId = randomUUID();
     const orderKey = `${Date.now()}-${String(eventSequence).padStart(6, "0")}`;
     eventSequence += 1;
     return {
-      eventId: randomUUID(),
+      eventId,
+      schemaVersion: 1,
       ts,
-      tsIso: new Date(ts * 1000).toISOString(),
+      tsIso: recordedAt,
+      eventType: input.type,
+      occurredAt: input.occurredAt ?? recordedAt,
+      recordedAt,
       actor: resolveActor(input.actor),
+      sourceSystem: input.sourceSystem ?? "hack",
+      sourceOperation: input.sourceOperation ?? "local_command",
+      idempotencyKey: input.idempotencyKey ?? eventId,
+      ...(input.causationId ? { causationId: input.causationId } : {}),
+      ...(input.correlationId ? { correlationId: input.correlationId } : {}),
       orderKey,
       ...(opts.projectId ? { projectId: opts.projectId } : {}),
       ...(opts.projectName ? { projectName: opts.projectName } : {}),
@@ -346,6 +386,8 @@ export function createTicketsStore(opts: {
     }
 
     const events: TicketEvent[] = [];
+    const seenEventIds = new Set<string>();
+    const seenIdempotencyKeys = new Set<string>();
     for (const filename of entries.sort()) {
       const path = resolve(eventsDir, filename);
       const text = await Bun.file(path)
@@ -358,13 +400,27 @@ export function createTicketsStore(opts: {
         }
         const parsed = safeJsonParse(trimmed);
         const event = parseEvent(parsed);
-        if (event) {
-          events.push(event);
+        if (!event || seenEventIds.has(event.eventId)) {
+          continue;
         }
+        if (seenIdempotencyKeys.has(event.idempotencyKey)) {
+          continue;
+        }
+        seenEventIds.add(event.eventId);
+        seenIdempotencyKeys.add(event.idempotencyKey);
+        events.push(event);
       }
     }
 
     events.sort((a, b) => {
+      if (a.ticketId === b.ticketId && a.type !== b.type) {
+        if (a.type === "ticket.created") {
+          return -1;
+        }
+        if (b.type === "ticket.created") {
+          return 1;
+        }
+      }
       if (a.ts !== b.ts) {
         return a.ts - b.ts;
       }
@@ -539,29 +595,31 @@ export function createTicketsStore(opts: {
 
       return {
         ok: true,
-        ticket: {
-          ticketId,
-          title: input.title,
-          ...(input.body ? { body: input.body } : {}),
-          status: "open",
-          createdAt: event.tsIso,
-          updatedAt: event.tsIso,
-          dependsOn,
-          blocks,
-          owner,
-          source,
-          ...(assignee ? { assignee } : {}),
-          tags,
-          ...(externalSystem ? { externalSystem } : {}),
-          ...(externalId ? { externalId } : {}),
-          ...(externalKey ? { externalKey } : {}),
-          ...(externalUrl ? { externalUrl } : {}),
-          ...(externalProjectId ? { externalProjectId } : {}),
-          ...(externalProjectName ? { externalProjectName } : {}),
-          ...(externalTeamId ? { externalTeamId } : {}),
-          ...(opts.projectId ? { projectId: opts.projectId } : {}),
-          ...(opts.projectName ? { projectName: opts.projectName } : {}),
-        },
+        ticket: normalizeTicketSummaryCompatibility({
+          ticket: {
+            ticketId,
+            title: input.title,
+            ...(input.body ? { body: input.body } : {}),
+            status: "open",
+            createdAt: event.tsIso,
+            updatedAt: event.tsIso,
+            dependsOn,
+            blocks,
+            owner,
+            source,
+            ...(assignee ? { assignee } : {}),
+            tags,
+            ...(externalSystem ? { externalSystem } : {}),
+            ...(externalId ? { externalId } : {}),
+            ...(externalKey ? { externalKey } : {}),
+            ...(externalUrl ? { externalUrl } : {}),
+            ...(externalProjectId ? { externalProjectId } : {}),
+            ...(externalProjectName ? { externalProjectName } : {}),
+            ...(externalTeamId ? { externalTeamId } : {}),
+            ...(opts.projectId ? { projectId: opts.projectId } : {}),
+            ...(opts.projectName ? { projectName: opts.projectName } : {}),
+          },
+        }),
       };
     },
 
@@ -1145,31 +1203,36 @@ function applyTicketCreatedEvent(input: {
     value: input.event.payload.externalTeamId,
   });
 
-  input.tickets.set(input.event.ticketId, {
-    ticketId: input.event.ticketId,
-    title,
-    body,
-    status: "open",
-    createdAt: input.event.tsIso,
-    updatedAt: input.event.tsIso,
-    dependsOn,
-    blocks,
-    owner,
-    source,
-    ...(assignee ? { assignee } : {}),
-    tags,
-    ...(externalSystem ? { externalSystem } : {}),
-    ...(externalId ? { externalId } : {}),
-    ...(externalKey ? { externalKey } : {}),
-    ...(externalUrl ? { externalUrl } : {}),
-    ...(externalProjectId ? { externalProjectId } : {}),
-    ...(externalProjectName ? { externalProjectName } : {}),
-    ...(externalTeamId ? { externalTeamId } : {}),
-    ...(input.event.projectId ? { projectId: input.event.projectId } : {}),
-    ...(input.event.projectName
-      ? { projectName: input.event.projectName }
-      : {}),
-  });
+  input.tickets.set(
+    input.event.ticketId,
+    normalizeTicketSummaryCompatibility({
+      ticket: {
+        ticketId: input.event.ticketId,
+        title,
+        body,
+        status: "open",
+        createdAt: input.event.tsIso,
+        updatedAt: input.event.tsIso,
+        dependsOn,
+        blocks,
+        owner,
+        source,
+        ...(assignee ? { assignee } : {}),
+        tags,
+        ...(externalSystem ? { externalSystem } : {}),
+        ...(externalId ? { externalId } : {}),
+        ...(externalKey ? { externalKey } : {}),
+        ...(externalUrl ? { externalUrl } : {}),
+        ...(externalProjectId ? { externalProjectId } : {}),
+        ...(externalProjectName ? { externalProjectName } : {}),
+        ...(externalTeamId ? { externalTeamId } : {}),
+        ...(input.event.projectId ? { projectId: input.event.projectId } : {}),
+        ...(input.event.projectName
+          ? { projectName: input.event.projectName }
+          : {}),
+      },
+    })
+  );
 }
 
 function applyTicketStatusChangedEvent(input: {
@@ -1186,11 +1249,16 @@ function applyTicketStatusChangedEvent(input: {
     return;
   }
 
-  input.tickets.set(input.event.ticketId, {
-    ...current,
-    status,
-    updatedAt: input.event.tsIso,
-  });
+  input.tickets.set(
+    input.event.ticketId,
+    normalizeTicketSummaryCompatibility({
+      ticket: {
+        ...current,
+        status,
+        updatedAt: input.event.tsIso,
+      },
+    })
+  );
 }
 
 function applyTicketUpdatedEvent(input: {
@@ -1263,47 +1331,56 @@ function applyTicketUpdatedEvent(input: {
     key: "externalTeamId",
   });
 
-  input.tickets.set(input.event.ticketId, {
-    ...current,
-    ...(title ? { title } : {}),
-    ...(body !== undefined ? { body } : {}),
-    ...(dependsOn !== null ? { dependsOn } : {}),
-    ...(blocks !== null ? { blocks } : {}),
-    ...(owner !== null
-      ? {
-          owner: normalizeOwnerOrSource({
-            value: owner,
-            fallback: current.owner,
-          }),
-        }
-      : {}),
-    ...(source !== null
-      ? {
-          source: normalizeOwnerOrSource({
-            value: source,
-            fallback: current.source,
-          }),
-        }
-      : {}),
-    ...(assignee !== null ? { assignee: assignee || undefined } : {}),
-    ...(tags !== null ? { tags } : {}),
-    ...(externalSystem !== null
-      ? { externalSystem: externalSystem || undefined }
-      : {}),
-    ...(externalId !== null ? { externalId: externalId || undefined } : {}),
-    ...(externalKey !== null ? { externalKey: externalKey || undefined } : {}),
-    ...(externalUrl !== null ? { externalUrl: externalUrl || undefined } : {}),
-    ...(externalProjectId !== null
-      ? { externalProjectId: externalProjectId || undefined }
-      : {}),
-    ...(externalProjectName !== null
-      ? { externalProjectName: externalProjectName || undefined }
-      : {}),
-    ...(externalTeamId !== null
-      ? { externalTeamId: externalTeamId || undefined }
-      : {}),
-    updatedAt: input.event.tsIso,
-  });
+  input.tickets.set(
+    input.event.ticketId,
+    normalizeTicketSummaryCompatibility({
+      ticket: {
+        ...current,
+        ...(title ? { title } : {}),
+        ...(body !== undefined ? { body } : {}),
+        ...(dependsOn !== null ? { dependsOn } : {}),
+        ...(blocks !== null ? { blocks } : {}),
+        ...(owner !== null
+          ? {
+              owner: normalizeOwnerOrSource({
+                value: owner,
+                fallback: current.owner,
+              }),
+            }
+          : {}),
+        ...(source !== null
+          ? {
+              source: normalizeOwnerOrSource({
+                value: source,
+                fallback: current.source,
+              }),
+            }
+          : {}),
+        ...(assignee !== null ? { assignee: assignee || undefined } : {}),
+        ...(tags !== null ? { tags } : {}),
+        ...(externalSystem !== null
+          ? { externalSystem: externalSystem || undefined }
+          : {}),
+        ...(externalId !== null ? { externalId: externalId || undefined } : {}),
+        ...(externalKey !== null
+          ? { externalKey: externalKey || undefined }
+          : {}),
+        ...(externalUrl !== null
+          ? { externalUrl: externalUrl || undefined }
+          : {}),
+        ...(externalProjectId !== null
+          ? { externalProjectId: externalProjectId || undefined }
+          : {}),
+        ...(externalProjectName !== null
+          ? { externalProjectName: externalProjectName || undefined }
+          : {}),
+        ...(externalTeamId !== null
+          ? { externalTeamId: externalTeamId || undefined }
+          : {}),
+        updatedAt: input.event.tsIso,
+      },
+    })
+  );
 }
 
 function applyTicketCommentAppendedEvent(input: {
@@ -1782,12 +1859,35 @@ function parseEvent(value: unknown): TicketEvent | null {
     return null;
   }
   const eventId = typeof value.eventId === "string" ? value.eventId : "";
+  const schemaVersion =
+    typeof value.schemaVersion === "number" ? value.schemaVersion : 0;
   const ts = typeof value.ts === "number" ? value.ts : Number.NaN;
+  const tsIso = new Date(ts * 1000).toISOString();
   const actor = typeof value.actor === "string" ? value.actor : "";
+  const eventTypeCandidate =
+    typeof value.eventType === "string" ? value.eventType : undefined;
+  const typeCandidate = typeof value.type === "string" ? value.type : undefined;
+  const eventType = eventTypeCandidate ?? typeCandidate ?? "";
+  const occurredAt =
+    typeof value.occurredAt === "string" ? value.occurredAt : tsIso;
+  const recordedAt =
+    typeof value.recordedAt === "string" ? value.recordedAt : tsIso;
   const orderKey =
     typeof value.orderKey === "string" ? value.orderKey : undefined;
+  const sourceSystem =
+    typeof value.sourceSystem === "string" ? value.sourceSystem : "hack";
+  const sourceOperation =
+    typeof value.sourceOperation === "string"
+      ? value.sourceOperation
+      : eventType;
+  const idempotencyKey =
+    typeof value.idempotencyKey === "string" ? value.idempotencyKey : eventId;
+  const causationId =
+    typeof value.causationId === "string" ? value.causationId : undefined;
+  const correlationId =
+    typeof value.correlationId === "string" ? value.correlationId : undefined;
   const ticketId = typeof value.ticketId === "string" ? value.ticketId : "";
-  const type = typeof value.type === "string" ? value.type : "";
+  const type = typeCandidate ?? eventType;
   const payload = isRecord(value.payload)
     ? (value.payload as Record<string, unknown>)
     : null;
@@ -1805,9 +1905,18 @@ function parseEvent(value: unknown): TicketEvent | null {
 
   return {
     eventId,
+    schemaVersion,
     ts,
-    tsIso: new Date(ts * 1000).toISOString(),
+    tsIso,
+    eventType,
+    occurredAt,
+    recordedAt,
     actor,
+    sourceSystem,
+    sourceOperation,
+    idempotencyKey,
+    ...(causationId ? { causationId } : {}),
+    ...(correlationId ? { correlationId } : {}),
     ...(orderKey ? { orderKey } : {}),
     ...(projectId ? { projectId } : {}),
     ...(projectName ? { projectName } : {}),
diff --git a/src/control-plane/extensions/tickets/tickets-git-channel.ts b/src/control-plane/extensions/tickets/tickets-git-channel.ts
index 7517170e2..cff02ff1b 100644
--- a/src/control-plane/extensions/tickets/tickets-git-channel.ts
+++ b/src/control-plane/extensions/tickets/tickets-git-channel.ts
@@ -631,6 +631,7 @@ export function createGitTicketsChannel(opts: {
         .text()
         .catch(() => "");
       const existingIds = new Set<string>();
+      const existingIdempotencyKeys = new Set<string>();
       for (const line of existing.split("\n")) {
         const trimmed = line.trim();
         if (!trimmed) {
@@ -639,15 +640,29 @@ export function createGitTicketsChannel(opts: {
         const parsed = safeJsonParse(trimmed);
         if (isRecord(parsed) && typeof parsed.eventId === "string") {
           existingIds.add(parsed.eventId);
+          const idempotencyKey =
+            typeof parsed.idempotencyKey === "string"
+              ? parsed.idempotencyKey
+              : parsed.eventId;
+          existingIdempotencyKeys.add(idempotencyKey);
         }
       }
 
       const lines: string[] = [];
+      const pendingIdempotencyKeys = new Set<string>();
       for (const ev of events) {
         const id = typeof ev.eventId === "string" ? ev.eventId : "";
-        if (!id || existingIds.has(id)) {
+        const idempotencyKey =
+          typeof ev.idempotencyKey === "string" ? ev.idempotencyKey : id;
+        if (
+          !id ||
+          existingIds.has(id) ||
+          existingIdempotencyKeys.has(idempotencyKey) ||
+          pendingIdempotencyKeys.has(idempotencyKey)
+        ) {
           continue;
         }
+        pendingIdempotencyKeys.add(idempotencyKey);
         lines.push(stableStringify(ev));
       }
 
@@ -684,6 +699,7 @@ export function createGitTicketsChannel(opts: {
         .catch(() => "");
       const parsed: Record<string, unknown>[] = [];
       const seen = new Set<string>();
+      const seenIdempotencyKeys = new Set<string>();
 
       for (const line of text.split("\n")) {
         const trimmed = line.trim();
@@ -695,14 +711,19 @@ export function createGitTicketsChannel(opts: {
           continue;
         }
         const eventId = typeof value.eventId === "string" ? value.eventId : "";
+        const idempotencyKey =
+          typeof value.idempotencyKey === "string"
+            ? value.idempotencyKey
+            : eventId;
         const ts = typeof value.ts === "number" ? value.ts : Number.NaN;
         if (!(eventId && Number.isFinite(ts))) {
           continue;
         }
-        if (seen.has(eventId)) {
+        if (seen.has(eventId) || seenIdempotencyKeys.has(idempotencyKey)) {
           continue;
         }
         seen.add(eventId);
+        seenIdempotencyKeys.add(idempotencyKey);
         parsed.push(value);
       }
 
@@ -1178,6 +1199,7 @@ function mergeTicketEventLogs(input: {
 }): string {
   const parsed: Record<string, unknown>[] = [];
   const seen = new Set<string>();
+  const seenIdempotencyKeys = new Set<string>();
 
   for (const text of [input.existing, input.incoming]) {
     for (const line of text.split("\n")) {
@@ -1190,14 +1212,19 @@ function mergeTicketEventLogs(input: {
         continue;
       }
       const eventId = typeof value.eventId === "string" ? value.eventId : "";
+      const idempotencyKey =
+        typeof value.idempotencyKey === "string"
+          ? value.idempotencyKey
+          : eventId;
       const ts = typeof value.ts === "number" ? value.ts : Number.NaN;
       if (!(eventId && Number.isFinite(ts))) {
         continue;
       }
-      if (seen.has(eventId)) {
+      if (seen.has(eventId) || seenIdempotencyKeys.has(idempotencyKey)) {
         continue;
       }
       seen.add(eventId);
+      seenIdempotencyKeys.add(idempotencyKey);
       parsed.push(value);
     }
   }
diff --git a/src/control-plane/extensions/tickets/util.ts b/src/control-plane/extensions/tickets/util.ts
index 1e4e3e981..baadb87f2 100644
--- a/src/control-plane/extensions/tickets/util.ts
+++ b/src/control-plane/extensions/tickets/util.ts
@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 const DIGITS_ONLY_PATTERN = /^\d+$/;
 
 export function unixSeconds(): number {
@@ -75,6 +77,10 @@ export function stableStringify(value: unknown): string {
   return JSON.stringify(stableSort(value));
 }
 
+export function sha256Hex(input: { readonly value: string }): string {
+  return createHash("sha256").update(input.value).digest("hex");
+}
+
 function stableSort(value: unknown): unknown {
   if (Array.isArray(value)) {
     return value.map(stableSort);
diff --git a/tests/tickets-git-channel.test.ts b/tests/tickets-git-channel.test.ts
index c93f8419f..9b184843b 100644
--- a/tests/tickets-git-channel.test.ts
+++ b/tests/tickets-git-channel.test.ts
@@ -7,30 +7,62 @@ test("mergeTicketEventLogs dedupes by event id and preserves chronological order
     existing: [
       JSON.stringify({
         eventId: "event-2",
+        schemaVersion: 1,
         ts: 2,
+        occurredAt: "2026-03-13T00:00:02.000Z",
+        recordedAt: "2026-03-13T00:00:02.000Z",
+        sourceSystem: "hack",
+        sourceOperation: "ticket.created",
+        idempotencyKey: "event-2",
         ticketId: "T-00002",
+        eventType: "ticket.created",
         type: "ticket.created",
+        payload: {},
       }),
       JSON.stringify({
         eventId: "event-3",
+        schemaVersion: 1,
         ts: 3,
+        occurredAt: "2026-03-13T00:00:03.000Z",
+        recordedAt: "2026-03-13T00:00:03.000Z",
+        sourceSystem: "hack",
+        sourceOperation: "ticket.created",
+        idempotencyKey: "event-3",
         ticketId: "T-00003",
+        eventType: "ticket.created",
         type: "ticket.created",
+        payload: {},
       }),
       "",
     ].join("\n"),
     incoming: [
       JSON.stringify({
         eventId: "event-1",
+        schemaVersion: 1,
         ts: 1,
+        occurredAt: "2026-03-13T00:00:01.000Z",
+        recordedAt: "2026-03-13T00:00:01.000Z",
+        sourceSystem: "linear",
+        sourceOperation: "issue.import",
+        idempotencyKey: "linear:issue:1",
         ticketId: "T-00001",
+        eventType: "ticket.created",
         type: "ticket.created",
+        payload: {},
       }),
       JSON.stringify({
         eventId: "event-2",
+        schemaVersion: 1,
         ts: 2,
+        occurredAt: "2026-03-13T00:00:02.000Z",
+        recordedAt: "2026-03-13T00:00:02.000Z",
+        sourceSystem: "hack",
+        sourceOperation: "ticket.created",
+        idempotencyKey: "event-2",
         ticketId: "T-00002",
+        eventType: "ticket.created",
         type: "ticket.created",
+        payload: {},
       }),
       "",
     ].join("\n"),
@@ -41,7 +73,15 @@ test("mergeTicketEventLogs dedupes by event id and preserves chronological order
     .split("\n")
     .map(
       (line) =>
-        JSON.parse(line) as { readonly eventId: string; readonly ts: number }
+        JSON.parse(line) as {
+          readonly eventId: string;
+          readonly ts: number;
+          readonly schemaVersion: number;
+          readonly sourceSystem: string;
+          readonly sourceOperation: string;
+          readonly idempotencyKey: string;
+          readonly eventType: string;
+        }
     );
 
   expect(lines.map((line) => line.eventId)).toEqual([
@@ -50,6 +90,70 @@ test("mergeTicketEventLogs dedupes by event id and preserves chronological order
     "event-3",
   ]);
   expect(lines.map((line) => line.ts)).toEqual([1, 2, 3]);
+  expect(lines[0]).toMatchObject({
+    schemaVersion: 1,
+    sourceSystem: "linear",
+    sourceOperation: "issue.import",
+    idempotencyKey: "linear:issue:1",
+    eventType: "ticket.created",
+  });
+});
+
+test("mergeTicketEventLogs preserves normalized journal envelope fields", () => {
+  const merged = __testOnly.mergeTicketEventLogs({
+    existing: [
+      JSON.stringify({
+        eventId: "event-2",
+        schemaVersion: 1,
+        ts: 2,
+        occurredAt: "2026-03-13T10:00:02.000Z",
+        recordedAt: "2026-03-13T10:00:03.000Z",
+        ticketId: "T-00002",
+        type: "ticket.created",
+        sourceSystem: "linear",
+        sourceOperation: "webhook_pull",
+        idempotencyKey: "linear:event-2",
+      }),
+      "",
+    ].join("\n"),
+    incoming: [
+      JSON.stringify({
+        eventId: "event-1",
+        schemaVersion: 1,
+        ts: 1,
+        occurredAt: "2026-03-13T10:00:01.000Z",
+        recordedAt: "2026-03-13T10:00:01.500Z",
+        ticketId: "T-00001",
+        type: "ticket.created",
+        sourceSystem: "hack",
+        sourceOperation: "local_command",
+        idempotencyKey: "hack:event-1",
+      }),
+      "",
+    ].join("\n"),
+  });
+
+  const lines = merged
+    .trim()
+    .split("\n")
+    .map((line) => JSON.parse(line) as Record<string, unknown>);
+
+  expect(lines).toEqual([
+    expect.objectContaining({
+      eventId: "event-1",
+      schemaVersion: 1,
+      sourceSystem: "hack",
+      sourceOperation: "local_command",
+      idempotencyKey: "hack:event-1",
+    }),
+    expect.objectContaining({
+      eventId: "event-2",
+      schemaVersion: 1,
+      sourceSystem: "linear",
+      sourceOperation: "webhook_pull",
+      idempotencyKey: "linear:event-2",
+    }),
+  ]);
 });
 
 test("resolvePushRefForCheckoutRef prefers legacy branch when checkout came from legacy tracking ref", () => {
diff --git a/tests/tickets-store.test.ts b/tests/tickets-store.test.ts
index 099e38e01..b5f94d7a1 100644
--- a/tests/tickets-store.test.ts
+++ b/tests/tickets-store.test.ts
@@ -9,6 +9,10 @@ import {
 } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import {
+  createNormalizedTicket,
+  projectNormalizedTicketSummary,
+} from "../src/control-plane/extensions/tickets/domain.ts";
 import { createTicketsStore } from "../src/control-plane/extensions/tickets/store.ts";
 import { readControlPlaneConfig } from "../src/control-plane/sdk/config.ts";
 
@@ -218,6 +222,15 @@ test("tickets store materializes assignee, review notes, comments, checkpoints,
     "ticket.sync_conflict_recorded",
     "ticket.sync_conflict_resolved",
   ]);
+  expect(events[0]).toMatchObject({
+    schemaVersion: 1,
+    eventType: "ticket.created",
+    occurredAt: events[0]?.tsIso,
+    recordedAt: events[0]?.tsIso,
+    sourceSystem: "hack",
+    sourceOperation: "local_command",
+  });
+  expect(events[0]?.idempotencyKey).toBe(events[0]?.eventId);
 }, 20_000);
 
 test("tickets show json includes materialized sync metadata", async () => {
@@ -340,6 +353,199 @@ test("tickets store recovers from a stale tickets bare repo index.lock", async (
   expect(tickets.map((ticket) => ticket.title)).toContain("Stale lock ticket");
 }, 20_000);
 
+test("tickets store writes normalized journal envelope metadata and ignores duplicate idempotency keys", async () => {
+  const projectRoot = await createTempGitProject({
+    prefix: "hack-cli-tickets-envelope-",
+  });
+  const store = await createStore({ projectRoot });
+
+  const created = await store.createTicket({
+    title: "Envelope ticket",
+    owner: "hack",
+    source: "hack",
+    actor: "creator@hack",
+  });
+  expect(created.ok).toBe(true);
+  if (!created.ok) {
+    throw new Error(created.error);
+  }
+
+  const eventsDir = join(
+    projectRoot,
+    ".hack/tickets/git/worktree/.hack/tickets/events"
+  );
+  const [eventsFile] = (await readdir(eventsDir)).filter((entry) =>
+    entry.endsWith(".jsonl")
+  );
+  expect(eventsFile).toBeString();
+  if (!eventsFile) {
+    throw new Error("Missing tickets event log");
+  }
+
+  const eventsPath = join(eventsDir, eventsFile);
+  const rawLines = (await readFile(eventsPath, "utf8"))
+    .trim()
+    .split("\n")
+    .map((line) => JSON.parse(line) as Record<string, unknown>);
+
+  expect(rawLines[0]).toMatchObject({
+    schemaVersion: 1,
+    ticketId: created.ticket.ticketId,
+    occurredAt: created.ticket.createdAt,
+    recordedAt: created.ticket.createdAt,
+    sourceSystem: "hack",
+    sourceOperation: "local_command",
+  });
+  expect(rawLines[0]?.idempotencyKey).toBe(rawLines[0]?.eventId);
+  const baseTs = Number(rawLines[0]?.ts ?? 0) + 1;
+
+  const duplicateBaseEvent = {
+    schemaVersion: 1,
+    ticketId: created.ticket.ticketId,
+    type: "ticket.comment_appended",
+    payload: {
+      commentId: "comment-1",
+      body: "Imported from Linear.",
+      source: "linear",
+    },
+    actor: "linear@app",
+    sourceSystem: "linear",
+    sourceOperation: "webhook_pull",
+    idempotencyKey: "linear:comment:1",
+    occurredAt: "2026-03-13T11:00:00.000Z",
+    recordedAt: "2026-03-13T11:00:01.000Z",
+  };
+
+  await writeFile(
+    eventsPath,
+    [
+      await readFile(eventsPath, "utf8"),
+      JSON.stringify({
+        ...duplicateBaseEvent,
+        eventId: "event-comment-1",
+        ts: baseTs,
+        orderKey: `${baseTs}-000000`,
+      }),
+      JSON.stringify({
+        ...duplicateBaseEvent,
+        eventId: "event-comment-2",
+        ts: baseTs + 1,
+        orderKey: `${baseTs + 1}-000000`,
+      }),
+      "",
+    ].join("\n")
+  );
+
+  const snapshot = await store.readSnapshot();
+  const comments = snapshot.commentsByTicket.get(created.ticket.ticketId) ?? [];
+  expect(comments).toHaveLength(1);
+  expect(comments[0]).toMatchObject({
+    commentId: "comment-1",
+    body: "Imported from Linear.",
+    source: "linear",
+  });
+}, 20_000);
+
+test("normalized ticket adapter preserves compatibility while exposing provenance and documents", () => {
+  const summary = {
+    ticketId: "T-00042",
+    title: "Normalize ticket metadata",
+    body: "## Context\nDocument-backed description",
+    status: "in_progress" as const,
+    createdAt: "2026-03-13T10:00:00.000Z",
+    updatedAt: "2026-03-13T11:00:00.000Z",
+    dependsOn: ["T-00001"],
+    blocks: ["T-00009"],
+    owner: "hack",
+    source: "linear",
+    assignee: "alice@hack",
+    tags: ["core", "tickets"],
+    externalSystem: "linear",
+    externalId: "lin_123",
+    externalKey: "HACK-431",
+    externalUrl: "https://linear.app/hack/issue/HACK-431",
+    externalProjectId: "project-1",
+    externalProjectName: "Hack App",
+    externalTeamId: "team-1",
+    projectId: "hack-cli",
+    projectName: "hack-cli",
+  };
+
+  const normalized = createNormalizedTicket({
+    ticket: summary,
+    syncCheckpoints: [
+      {
+        checkpointId: "checkpoint-1",
+        ticketId: summary.ticketId,
+        provider: "linear",
+        profileId: "default",
+        direction: "pull",
+        remoteCursor: "issue/lin_123#v2",
+        remoteUpdatedAt: "2026-03-13T10:59:00.000Z",
+        localUpdatedAt: "2026-03-13T11:00:00.000Z",
+        actor: "sync@app",
+        createdAt: "2026-03-13T11:00:00.000Z",
+      },
+    ],
+    conflicts: [
+      {
+        conflictId: "conflict-1",
+        ticketId: summary.ticketId,
+        provider: "linear",
+        field: "title",
+        status: "open",
+        authority: "review_required",
+        summary: "Local title drifted from Linear.",
+        localValue: summary.title,
+        remoteValue: "Normalize work model",
+        createdAt: "2026-03-13T11:00:00.000Z",
+        updatedAt: "2026-03-13T11:00:00.000Z",
+      },
+    ],
+  });
+
+  expect(normalized.identity).toEqual({
+    ticketId: "T-00042",
+    projectId: "hack-cli",
+    projectName: "hack-cli",
+  });
+  expect(normalized.provenance.origin).toEqual({
+    owner: "hack",
+    source: "linear",
+    system: "linear",
+  });
+  expect(normalized.provenance.remotes).toEqual([
+    expect.objectContaining({
+      provider: "linear",
+      remoteId: "lin_123",
+      remoteKey: "HACK-431",
+      remoteUrl: "https://linear.app/hack/issue/HACK-431",
+      projectId: "project-1",
+      projectName: "Hack App",
+      teamId: "team-1",
+    }),
+  ]);
+  expect(normalized.documents).toEqual([
+    expect.objectContaining({
+      kind: "description",
+      role: "description",
+      content: "## Context\nDocument-backed description",
+    }),
+  ]);
+  expect(normalized.fieldStates).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        field: "title",
+        authority: "review_required",
+        conflictIds: ["conflict-1"],
+      }),
+    ])
+  );
+  expect(projectNormalizedTicketSummary({ ticket: normalized })).toEqual(
+    summary
+  );
+});
+
 async function createStore(opts: { readonly projectRoot: string }) {
   const configResult = await readControlPlaneConfig({
     projectDir: join(opts.projectRoot, ".hack"),

From de42cea3705fb33182d878eb1a88841dba91b597 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 22:39:32 +0000
Subject: [PATCH 006/134] feat(tickets): define normalized ticket entity model

---
 .../guides/linear-integration-architecture.md |   4 +
 docs/guides/tickets-normalization.md          | 172 ++++
 docs/guides/tickets.md                        |   1 +
 .../extensions/tickets/normalized-model.ts    | 886 ++++++++++++++++++
 tests/tickets-normalized-model.test.ts        | 444 +++++++++
 5 files changed, 1507 insertions(+)
 create mode 100644 docs/guides/tickets-normalization.md
 create mode 100644 src/control-plane/extensions/tickets/normalized-model.ts
 create mode 100644 tests/tickets-normalized-model.test.ts

diff --git a/docs/guides/linear-integration-architecture.md b/docs/guides/linear-integration-architecture.md
index 02f3db9bd..07c6d11a7 100644
--- a/docs/guides/linear-integration-architecture.md
+++ b/docs/guides/linear-integration-architecture.md
@@ -35,6 +35,10 @@ Synced tickets always carry explicit ownership and lineage metadata:
 
 This guarantees filtering by local-only, Linear-only, or mixed sets without ambiguous state.
 
+The normalized replacement for these flat fields is defined in `docs/guides/tickets-normalization.md`
+and `src/control-plane/extensions/tickets/normalized-model.ts`. New sync/storage work should prefer
+that entity boundary over adding more `external*` fields to `TicketSummary`.
+
 ## Sync Mapping
 
 1. Status:
diff --git a/docs/guides/tickets-normalization.md b/docs/guides/tickets-normalization.md
new file mode 100644
index 000000000..b15ff83f3
--- /dev/null
+++ b/docs/guides/tickets-normalization.md
@@ -0,0 +1,172 @@
+# Tickets Normalization Model
+
+The normalized tickets model lives in `src/control-plane/extensions/tickets/normalized-model.ts`.
+It defines the canonical entity shape that storage and adapter sync should converge on before the
+legacy flat `TicketSummary` projection is retired.
+
+## Goals
+
+- Keep one canonical ticket entity for local-only and dual-homed work.
+- Make ticket origin, external links, and field authority explicit.
+- Keep provider-specific data out of canonical fields.
+- Stay generic enough for Linear, GitHub, and Asana.
+
+## Entity Shape
+
+```ts
+type NormalizedTicketEntity = {
+  schemaVersion: 1
+  kind: "ticket"
+  id: string
+  canonical: {
+    title: string
+    body?: string
+    status: "open" | "in_progress" | "blocked" | "done"
+    assignee?: string
+    project?: { id?: string; name?: string }
+    tags: string[]
+    relationships: {
+      dependsOn: string[]
+      blocks: string[]
+    }
+    timestamps: {
+      createdAt: string
+      updatedAt: string
+    }
+  }
+  provenance: {
+    origin:
+      | { kind: "local"; system: "hack" }
+      | { kind: "external"; system: "linear" | "github" | "asana"; linkId: string }
+    links: NormalizedTicketLink[]
+    authority: NormalizedTicketAuthority
+  }
+}
+```
+
+## Provenance
+
+`origin` answers where the ticket started:
+
+- `local` means the ticket originated in Hack and may or may not have synced links yet.
+- `external` means the ticket was imported from a provider and points at the authoritative link.
+
+`origin` is derived from source lineage, not current ownership. A ticket can stay `origin.local`
+while an external system is the current owner or sync target.
+
+`links` tracks each external relationship explicitly:
+
+```ts
+type NormalizedTicketLink = {
+  linkId: string
+  system: "linear" | "github" | "asana"
+  role: "origin" | "synced" | "reference"
+  syncDirection: "pull" | "push" | "bidirectional"
+  connection?: {
+    profileId?: string
+    accountId?: string
+    workspaceId?: string
+    workspaceName?: string
+  }
+  remote: {
+    id: string
+    key?: string
+    url?: string
+    containers: {
+      kind: "project" | "team" | "repo" | "workspace" | "board" | "list"
+      id: string
+      name?: string
+    }[]
+  }
+  adapterMetadata?: Record<string, TicketSchemaValue>
+}
+```
+
+Why generic containers matter:
+
+- Linear uses `project` and `team`
+- GitHub uses `repo`
+- Asana uses `workspace`, `project`, `board`, or `list`
+
+Those stay normalized instead of introducing more `externalProject*`-style top-level fields.
+
+## Authority
+
+Authority is modeled separately from origin because a linked ticket can still remain Hack-owned.
+
+```ts
+type NormalizedTicketAuthority = {
+  defaultRule: {
+    policy: "replace" | "append" | "set_union"
+    winner?: { kind: "local" } | { kind: "origin" } | { kind: "link"; linkId: string }
+  }
+  fieldRules: Partial<
+    Record<
+      | "title"
+      | "body"
+      | "status"
+      | "assignee"
+      | "project"
+      | "tags"
+      | "dependsOn"
+      | "blocks",
+      {
+        policy: "replace" | "append" | "set_union"
+        winner?: { kind: "local" } | { kind: "origin" } | { kind: "link"; linkId: string }
+      }
+    >
+  >
+}
+```
+
+Current defaults:
+
+- Local-origin tickets: `defaultRule = replace/local`
+- External-origin tickets: `defaultRule = replace/origin`
+- `tags`, `dependsOn`, `blocks`: `set_union`
+
+This matches current Linear sync behavior while leaving room for GitHub or Asana-specific field
+ownership later.
+
+## Schema Invariants
+
+The schema is intentionally stricter than a plain JSON shape. A valid normalized ticket must also
+satisfy these cross-record rules:
+
+- `provenance.links[*].linkId` values are unique within a ticket.
+- Local-origin tickets cannot carry an `origin`-role external link.
+- External-origin tickets must point at a matching `origin`-role link with the same `system` and
+  `linkId`.
+- Any authority winner with `{ kind: "link", linkId }` must reference a link that exists on the
+  same ticket.
+- `buildNormalizedTicketLink()` validates remote identifiers and URLs up front, so adapter code
+  cannot emit blank link records accidentally.
+- Legacy summaries with `source` set to an external provider must include matching
+  `externalSystem` and `externalId`; the bridge rejects incomplete external lineage instead of
+  rewriting it as a local ticket.
+
+Those invariants are what make the model precise enough for storage migration, conflict resolution,
+and multi-provider sync instead of just being a documentation-only shape.
+
+## Adapter Metadata Boundary
+
+Canonical fields stop at `canonical`, `provenance.origin`, `provenance.links[*].remote`, and
+`provenance.authority`.
+
+Everything provider-specific goes in `adapterMetadata`, for example:
+
+- Linear state ids or cycle ids
+- GitHub label payloads, milestone ids, or issue type metadata
+- Asana custom fields or section ids
+
+That boundary lets storage index the normalized fields without understanding every provider payload.
+
+## Migration Boundary
+
+The current git-backed tickets store still materializes `TicketSummary` with flat `external*`
+fields. `normalizeLegacyTicketSummary()` is the bridge layer that maps the legacy projection into
+the normalized entity until storage is migrated.
+
+Comments are intentionally out of scope for this core ticket entity. They remain separate ticket
+records in the current store and should become their own normalized sync surface rather than a
+field on `NormalizedTicketEntity`.
diff --git a/docs/guides/tickets.md b/docs/guides/tickets.md
index 279f60a02..a729262b2 100644
--- a/docs/guides/tickets.md
+++ b/docs/guides/tickets.md
@@ -129,6 +129,7 @@ Tip: use `--body-stdin` for multi-line markdown.
 - The extension reads events, materializes tickets in-memory, and renders `list/show` outputs.
 - Ticket writes automatically commit and push to the tickets ref when git sync is enabled and a remote exists.
 - `sync` normalizes the event logs, commits, and pushes the tickets ref.
+- The next-step normalized entity model is documented in `docs/guides/tickets-normalization.md`.
 
 ### Storage layout
 
diff --git a/src/control-plane/extensions/tickets/normalized-model.ts b/src/control-plane/extensions/tickets/normalized-model.ts
new file mode 100644
index 000000000..8e447f92c
--- /dev/null
+++ b/src/control-plane/extensions/tickets/normalized-model.ts
@@ -0,0 +1,886 @@
+import type { TicketSummary } from "./store.ts";
+
+export const NORMALIZED_TICKET_SCHEMA_VERSION = 1 as const;
+
+export const TICKET_STATUSES = [
+  "open",
+  "in_progress",
+  "blocked",
+  "done",
+] as const;
+
+export const EXTERNAL_TICKET_SYSTEMS = ["linear", "github", "asana"] as const;
+
+export const TICKET_LINK_CONTAINER_KINDS = [
+  "project",
+  "team",
+  "repo",
+  "workspace",
+  "board",
+  "list",
+] as const;
+
+export const TICKET_AUTHORITY_FIELDS = [
+  "title",
+  "body",
+  "status",
+  "assignee",
+  "project",
+  "tags",
+  "dependsOn",
+  "blocks",
+] as const;
+
+export type TicketStatus = (typeof TICKET_STATUSES)[number];
+export type ExternalTicketSystem = (typeof EXTERNAL_TICKET_SYSTEMS)[number];
+export type TicketLinkContainerKind =
+  (typeof TICKET_LINK_CONTAINER_KINDS)[number];
+export type TicketAuthorityField = (typeof TICKET_AUTHORITY_FIELDS)[number];
+
+export type TicketSchemaValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly TicketSchemaValue[]
+  | { readonly [key: string]: TicketSchemaValue };
+
+export type LegacyTicketSummary = TicketSummary;
+
+export type TicketLinkContainer = {
+  readonly kind: TicketLinkContainerKind;
+  readonly id: string;
+  readonly name?: string;
+};
+
+export type TicketLinkConnection = {
+  readonly profileId?: string;
+  readonly accountId?: string;
+  readonly workspaceId?: string;
+  readonly workspaceName?: string;
+};
+
+export type NormalizedTicketLink = {
+  readonly linkId: string;
+  readonly system: ExternalTicketSystem;
+  readonly role: "origin" | "synced" | "reference";
+  readonly syncDirection: "pull" | "push" | "bidirectional";
+  readonly connection?: TicketLinkConnection;
+  readonly remote: {
+    readonly id: string;
+    readonly key?: string;
+    readonly url?: string;
+    readonly containers: readonly TicketLinkContainer[];
+  };
+  readonly adapterMetadata?: { readonly [key: string]: TicketSchemaValue };
+};
+
+export type TicketAuthorityWinner =
+  | { readonly kind: "local" }
+  | { readonly kind: "origin" }
+  | { readonly kind: "link"; readonly linkId: string };
+
+export type TicketAuthorityRule = {
+  readonly policy: "replace" | "append" | "set_union";
+  readonly winner?: TicketAuthorityWinner;
+};
+
+export type NormalizedTicketAuthority = {
+  readonly defaultRule: TicketAuthorityRule;
+  readonly fieldRules: Partial<
+    Record<TicketAuthorityField, TicketAuthorityRule>
+  >;
+};
+
+export type NormalizedTicketOrigin =
+  | {
+      readonly kind: "local";
+      readonly system: "hack";
+    }
+  | {
+      readonly kind: "external";
+      readonly system: ExternalTicketSystem;
+      readonly linkId: string;
+    };
+
+export type NormalizedTicketEntity = {
+  readonly schemaVersion: typeof NORMALIZED_TICKET_SCHEMA_VERSION;
+  readonly kind: "ticket";
+  readonly id: string;
+  readonly canonical: {
+    readonly title: string;
+    readonly body?: string;
+    readonly status: TicketStatus;
+    readonly assignee?: string;
+    readonly project?: {
+      readonly id?: string;
+      readonly name?: string;
+    };
+    readonly tags: readonly string[];
+    readonly relationships: {
+      readonly dependsOn: readonly string[];
+      readonly blocks: readonly string[];
+    };
+    readonly timestamps: {
+      readonly createdAt: string;
+      readonly updatedAt: string;
+    };
+  };
+  readonly provenance: {
+    readonly origin: NormalizedTicketOrigin;
+    readonly links: readonly NormalizedTicketLink[];
+    readonly authority: NormalizedTicketAuthority;
+  };
+};
+
+export type NormalizedTicketLinkInput = {
+  readonly system: ExternalTicketSystem;
+  readonly remoteId: string;
+  readonly remoteKey?: string;
+  readonly remoteUrl?: string;
+  readonly containers?: readonly TicketLinkContainer[];
+  readonly role?: NormalizedTicketLink["role"];
+  readonly syncDirection?: NormalizedTicketLink["syncDirection"];
+  readonly connection?: TicketLinkConnection;
+  readonly adapterMetadata?: { readonly [key: string]: TicketSchemaValue };
+};
+
+export type NormalizeLegacyTicketSummaryInput = {
+  readonly ticket: LegacyTicketSummary;
+  readonly linkContext?: TicketLinkConnection & {
+    readonly adapterMetadata?: {
+      readonly [key: string]: TicketSchemaValue;
+    };
+  };
+};
+
+type Schema<T> = {
+  readonly parse: (input: unknown) => T;
+};
+
+export const normalizedTicketAuthoritySchema: Schema<NormalizedTicketAuthority> =
+  {
+    parse: (input) => parseNormalizedTicketAuthority(input),
+  };
+
+export const normalizedTicketEntitySchema: Schema<NormalizedTicketEntity> = {
+  parse: (input) => parseNormalizedTicketEntity(input),
+};
+
+/**
+ * Builds a provider-agnostic external link record that keeps provider-specific
+ * data inside `adapterMetadata` rather than the canonical ticket fields.
+ */
+export const buildNormalizedTicketLink = (
+  input: NormalizedTicketLinkInput
+): NormalizedTicketLink => {
+  const remoteId = input.remoteId.trim();
+  const remoteKey = normalizeOptionalString(input.remoteKey);
+  const remoteUrl = normalizeOptionalString(input.remoteUrl);
+  const containers = normalizeContainers(input.containers ?? []);
+  const connection = normalizeConnection(input.connection);
+  const adapterMetadata = normalizeAdapterMetadata(input.adapterMetadata);
+
+  const normalizedLink: NormalizedTicketLink = {
+    linkId: `${input.system}:${remoteId}`,
+    system: input.system,
+    role: input.role ?? "synced",
+    syncDirection: input.syncDirection ?? "bidirectional",
+    ...(connection ? { connection } : {}),
+    remote: {
+      id: remoteId,
+      ...(remoteKey ? { key: remoteKey } : {}),
+      ...(remoteUrl ? { url: remoteUrl } : {}),
+      containers,
+    },
+    ...(adapterMetadata ? { adapterMetadata } : {}),
+  };
+
+  return parseNormalizedTicketLink(normalizedLink);
+};
+
+/**
+ * Projects the current flat ticket summary into the normalized entity shape so
+ * storage and sync adapters can converge on one schema before the event store
+ * is migrated.
+ */
+export const normalizeLegacyTicketSummary = (
+  input: NormalizeLegacyTicketSummaryInput
+): NormalizedTicketEntity => {
+  assertLegacySummaryRemoteIdentity(input.ticket);
+  const link = buildLinkFromLegacySummary({
+    ticket: input.ticket,
+    linkContext: input.linkContext,
+  });
+  const origin = deriveOrigin({
+    ticket: input.ticket,
+    link,
+  });
+  const authority = deriveAuthority({
+    origin,
+  });
+  const project = normalizeProject({
+    id: input.ticket.projectId,
+    name: input.ticket.projectName,
+  });
+
+  const normalized: NormalizedTicketEntity = {
+    schemaVersion: NORMALIZED_TICKET_SCHEMA_VERSION,
+    kind: "ticket",
+    id: input.ticket.ticketId,
+    canonical: {
+      title: input.ticket.title.trim(),
+      ...(input.ticket.body !== undefined ? { body: input.ticket.body } : {}),
+      status: input.ticket.status,
+      ...(normalizeOptionalString(input.ticket.assignee)
+        ? { assignee: input.ticket.assignee.trim() }
+        : {}),
+      ...(project ? { project } : {}),
+      tags: normalizeStringList(input.ticket.tags),
+      relationships: {
+        dependsOn: normalizeStringList(input.ticket.dependsOn),
+        blocks: normalizeStringList(input.ticket.blocks),
+      },
+      timestamps: {
+        createdAt: input.ticket.createdAt,
+        updatedAt: input.ticket.updatedAt,
+      },
+    },
+    provenance: {
+      origin,
+      links: link ? [link] : [],
+      authority,
+    },
+  };
+
+  return normalizedTicketEntitySchema.parse(normalized);
+};
+
+const buildLinkFromLegacySummary = (input: {
+  readonly ticket: LegacyTicketSummary;
+  readonly linkContext?: NormalizeLegacyTicketSummaryInput["linkContext"];
+}): NormalizedTicketLink | undefined => {
+  const system = normalizeExternalSystem(input.ticket.externalSystem);
+  const remoteId = normalizeOptionalString(input.ticket.externalId);
+  if (!(system && remoteId)) {
+    return undefined;
+  }
+
+  const containers: TicketLinkContainer[] = [];
+  const projectId = normalizeOptionalString(input.ticket.externalProjectId);
+  const projectName = normalizeOptionalString(input.ticket.externalProjectName);
+  if (projectId) {
+    containers.push({
+      kind: "project",
+      id: projectId,
+      ...(projectName ? { name: projectName } : {}),
+    });
+  }
+
+  const teamId = normalizeOptionalString(input.ticket.externalTeamId);
+  if (teamId) {
+    containers.push({
+      kind: "team",
+      id: teamId,
+    });
+  }
+
+  return buildNormalizedTicketLink({
+    system,
+    remoteId,
+    remoteKey: input.ticket.externalKey,
+    remoteUrl: input.ticket.externalUrl,
+    containers,
+    role: isExternalOrigin({ ticket: input.ticket, system })
+      ? "origin"
+      : "synced",
+    syncDirection: "bidirectional",
+    connection: input.linkContext,
+    adapterMetadata: input.linkContext?.adapterMetadata,
+  });
+};
+
+const deriveOrigin = (input: {
+  readonly ticket: LegacyTicketSummary;
+  readonly link?: NormalizedTicketLink;
+}): NormalizedTicketOrigin => {
+  if (
+    input.link &&
+    input.link.role === "origin" &&
+    normalizeOwnerLikeValue(input.ticket.source) === input.link.system
+  ) {
+    return {
+      kind: "external",
+      system: input.link.system,
+      linkId: input.link.linkId,
+    };
+  }
+
+  return {
+    kind: "local",
+    system: "hack",
+  };
+};
+
+const deriveAuthority = (input: {
+  readonly origin: NormalizedTicketOrigin;
+}): NormalizedTicketAuthority => {
+  const defaultRule: TicketAuthorityRule =
+    input.origin.kind === "external"
+      ? {
+          policy: "replace",
+          winner: { kind: "origin" },
+        }
+      : {
+          policy: "replace",
+          winner: { kind: "local" },
+        };
+
+  return {
+    defaultRule,
+    fieldRules: {
+      tags: {
+        policy: "set_union",
+      },
+      dependsOn: {
+        policy: "set_union",
+      },
+      blocks: {
+        policy: "set_union",
+      },
+    },
+  };
+};
+
+const assertLegacySummaryRemoteIdentity = (
+  ticket: LegacyTicketSummary
+): void => {
+  const sourceSystem = normalizeExternalSystem(ticket.source);
+  if (!sourceSystem) {
+    return;
+  }
+
+  const externalSystem = normalizeExternalSystem(ticket.externalSystem);
+  const remoteId = normalizeOptionalString(ticket.externalId);
+  assertValue(
+    externalSystem === sourceSystem && remoteId !== undefined,
+    "externally sourced legacy ticket requires externalSystem and externalId"
+  );
+};
+
+const isExternalOrigin = (input: {
+  readonly ticket: LegacyTicketSummary;
+  readonly system: ExternalTicketSystem;
+}): boolean => normalizeOwnerLikeValue(input.ticket.source) === input.system;
+
+const normalizeProject = (input: {
+  readonly id?: string;
+  readonly name?: string;
+}):
+  | {
+      readonly id?: string;
+      readonly name?: string;
+    }
+  | undefined => {
+  const id = normalizeOptionalString(input.id);
+  const name = normalizeOptionalString(input.name);
+  if (!(id || name)) {
+    return undefined;
+  }
+  return {
+    ...(id ? { id } : {}),
+    ...(name ? { name } : {}),
+  };
+};
+
+const normalizeConnection = (
+  input: TicketLinkConnection | undefined
+): TicketLinkConnection | undefined => {
+  if (!input) {
+    return undefined;
+  }
+
+  const profileId = normalizeOptionalString(input.profileId);
+  const accountId = normalizeOptionalString(input.accountId);
+  const workspaceId = normalizeOptionalString(input.workspaceId);
+  const workspaceName = normalizeOptionalString(input.workspaceName);
+
+  if (!(profileId || accountId || workspaceId || workspaceName)) {
+    return undefined;
+  }
+
+  return {
+    ...(profileId ? { profileId } : {}),
+    ...(accountId ? { accountId } : {}),
+    ...(workspaceId ? { workspaceId } : {}),
+    ...(workspaceName ? { workspaceName } : {}),
+  };
+};
+
+const normalizeContainers = (
+  input: readonly TicketLinkContainer[]
+): TicketLinkContainer[] => {
+  const normalized: TicketLinkContainer[] = [];
+  const seen = new Set<string>();
+
+  for (const container of input) {
+    const id = normalizeOptionalString(container.id);
+    if (!id) {
+      continue;
+    }
+    const name = normalizeOptionalString(container.name);
+    const key = `${container.kind}:${id}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    normalized.push({
+      kind: container.kind,
+      id,
+      ...(name ? { name } : {}),
+    });
+  }
+
+  return normalized;
+};
+
+const normalizeStringList = (input: readonly string[]): string[] => {
+  const normalized: string[] = [];
+  const seen = new Set<string>();
+
+  for (const item of input) {
+    const value = normalizeOptionalString(item);
+    if (!(value && !seen.has(value))) {
+      continue;
+    }
+    seen.add(value);
+    normalized.push(value);
+  }
+
+  return normalized;
+};
+
+const normalizeAdapterMetadata = (
+  input: { readonly [key: string]: TicketSchemaValue } | undefined
+): { readonly [key: string]: TicketSchemaValue } | undefined => {
+  if (!input) {
+    return undefined;
+  }
+
+  const entries = Object.entries(input)
+    .map(([key, value]) => [key.trim(), value] as const)
+    .filter(([key]) => key.length > 0);
+
+  if (entries.length === 0) {
+    return undefined;
+  }
+
+  return Object.fromEntries(entries);
+};
+
+const normalizeOptionalString = (
+  input: string | undefined
+): string | undefined => {
+  const value = input?.trim();
+  return value ? value : undefined;
+};
+
+const normalizeOwnerLikeValue = (
+  input: string | undefined
+): string | undefined => normalizeOptionalString(input)?.toLowerCase();
+
+const normalizeExternalSystem = (
+  input: string | undefined
+): ExternalTicketSystem | undefined => {
+  const value = normalizeOwnerLikeValue(input);
+  if (value === "linear" || value === "github" || value === "asana") {
+    return value;
+  }
+  return undefined;
+};
+
+const parseNormalizedTicketEntity = (
+  input: unknown
+): NormalizedTicketEntity => {
+  const record = asRecord(input, "normalized ticket entity");
+  assertValue(
+    record.schemaVersion === NORMALIZED_TICKET_SCHEMA_VERSION,
+    "normalized ticket entity schemaVersion must be 1"
+  );
+  assertValue(
+    record.kind === "ticket",
+    "normalized ticket entity kind must be ticket"
+  );
+
+  const canonicalRecord = asRecord(
+    record.canonical,
+    "normalized ticket entity canonical"
+  );
+  const provenanceRecord = asRecord(
+    record.provenance,
+    "normalized ticket entity provenance"
+  );
+
+  assertNonEmptyString(record.id, "normalized ticket entity id");
+  assertNonEmptyString(
+    canonicalRecord.title,
+    "normalized ticket canonical title"
+  );
+  if (canonicalRecord.body !== undefined) {
+    assertString(canonicalRecord.body, "normalized ticket canonical body");
+  }
+  assertTicketStatus(canonicalRecord.status);
+  if (canonicalRecord.assignee !== undefined) {
+    assertNonEmptyString(
+      canonicalRecord.assignee,
+      "normalized ticket canonical assignee"
+    );
+  }
+
+  if (canonicalRecord.project !== undefined) {
+    const projectRecord = asRecord(
+      canonicalRecord.project,
+      "normalized ticket canonical project"
+    );
+    assertValue(
+      typeof projectRecord.id === "string" ||
+        typeof projectRecord.name === "string",
+      "normalized ticket canonical project must include an id or name"
+    );
+    if (projectRecord.id !== undefined) {
+      assertNonEmptyString(
+        projectRecord.id,
+        "normalized ticket canonical project id"
+      );
+    }
+    if (projectRecord.name !== undefined) {
+      assertNonEmptyString(
+        projectRecord.name,
+        "normalized ticket canonical project name"
+      );
+    }
+  }
+
+  assertStringList(canonicalRecord.tags, "normalized ticket canonical tags");
+
+  const relationshipsRecord = asRecord(
+    canonicalRecord.relationships,
+    "normalized ticket canonical relationships"
+  );
+  assertStringList(
+    relationshipsRecord.dependsOn,
+    "normalized ticket canonical dependsOn"
+  );
+  assertStringList(
+    relationshipsRecord.blocks,
+    "normalized ticket canonical blocks"
+  );
+
+  const timestampsRecord = asRecord(
+    canonicalRecord.timestamps,
+    "normalized ticket canonical timestamps"
+  );
+  assertIsoTimestamp(timestampsRecord.createdAt, "normalized ticket createdAt");
+  assertIsoTimestamp(timestampsRecord.updatedAt, "normalized ticket updatedAt");
+
+  const origin = parseNormalizedTicketOrigin(provenanceRecord.origin);
+  assertValue(
+    Array.isArray(provenanceRecord.links),
+    "normalized ticket links must be an array"
+  );
+  const links = provenanceRecord.links.map((link) =>
+    parseNormalizedTicketLink(link)
+  );
+  const linkIds = new Set<string>();
+  const originLinks: NormalizedTicketLink[] = [];
+  for (const link of links) {
+    assertValue(
+      !linkIds.has(link.linkId),
+      `normalized ticket link ${link.linkId} must be unique`
+    );
+    linkIds.add(link.linkId);
+    if (link.role === "origin") {
+      originLinks.push(link);
+    }
+  }
+
+  if (origin.kind === "local") {
+    assertValue(
+      originLinks.length === 0,
+      "normalized ticket local origin cannot include origin links"
+    );
+  }
+
+  if (origin.kind === "external") {
+    const matchingOriginLink = originLinks.find(
+      (link) => link.linkId === origin.linkId && link.system === origin.system
+    );
+    assertValue(
+      matchingOriginLink !== undefined,
+      "normalized ticket external origin must reference a matching origin link"
+    );
+  }
+
+  parseNormalizedTicketAuthority(provenanceRecord.authority, linkIds);
+
+  return record as NormalizedTicketEntity;
+};
+
+const parseNormalizedTicketAuthority = (
+  input: unknown,
+  linkIds?: ReadonlySet<string>
+): NormalizedTicketAuthority => {
+  const record = asRecord(input, "normalized ticket authority");
+  parseTicketAuthorityRule(
+    record.defaultRule,
+    "normalized ticket authority defaultRule",
+    linkIds
+  );
+  const fieldRules = asRecord(
+    record.fieldRules,
+    "normalized ticket authority fieldRules"
+  );
+  for (const [key, value] of Object.entries(fieldRules)) {
+    assertValue(
+      (TICKET_AUTHORITY_FIELDS as readonly string[]).includes(key),
+      `normalized ticket authority field ${key} is not supported`
+    );
+    parseTicketAuthorityRule(
+      value,
+      `normalized ticket authority fieldRules.${key}`,
+      linkIds
+    );
+  }
+  return record as NormalizedTicketAuthority;
+};
+
+const parseNormalizedTicketOrigin = (
+  input: unknown
+): NormalizedTicketOrigin => {
+  const record = asRecord(input, "normalized ticket origin");
+  assertValue(
+    record.kind === "local" || record.kind === "external",
+    "normalized ticket origin kind must be local or external"
+  );
+
+  if (record.kind === "local") {
+    assertValue(
+      record.system === "hack",
+      "local ticket origin system must be hack"
+    );
+    return record as NormalizedTicketOrigin;
+  }
+
+  assertExternalTicketSystem(record.system);
+  assertNonEmptyString(record.linkId, "external ticket origin linkId");
+  return record as NormalizedTicketOrigin;
+};
+
+const parseNormalizedTicketLink = (input: unknown): NormalizedTicketLink => {
+  const record = asRecord(input, "normalized ticket link");
+  assertNonEmptyString(record.linkId, "normalized ticket linkId");
+  assertExternalTicketSystem(record.system);
+  assertValue(
+    record.role === "origin" ||
+      record.role === "synced" ||
+      record.role === "reference",
+    "normalized ticket link role must be origin, synced, or reference"
+  );
+  assertValue(
+    record.syncDirection === "pull" ||
+      record.syncDirection === "push" ||
+      record.syncDirection === "bidirectional",
+    "normalized ticket link syncDirection must be pull, push, or bidirectional"
+  );
+
+  if (record.connection !== undefined) {
+    const connectionRecord = asRecord(
+      record.connection,
+      "normalized ticket connection"
+    );
+    const values = [
+      connectionRecord.profileId,
+      connectionRecord.accountId,
+      connectionRecord.workspaceId,
+      connectionRecord.workspaceName,
+    ].filter((value) => typeof value === "string");
+    assertValue(
+      values.length > 0,
+      "normalized ticket connection must include at least one identifier"
+    );
+    for (const [key, value] of Object.entries(connectionRecord)) {
+      assertNonEmptyString(value, `normalized ticket connection ${key}`);
+    }
+  }
+
+  const remoteRecord = asRecord(record.remote, "normalized ticket remote");
+  assertNonEmptyString(remoteRecord.id, "normalized ticket remote id");
+  if (remoteRecord.key !== undefined) {
+    assertNonEmptyString(remoteRecord.key, "normalized ticket remote key");
+  }
+  if (remoteRecord.url !== undefined) {
+    assertUrl(remoteRecord.url, "normalized ticket remote url");
+  }
+  assertValue(
+    Array.isArray(remoteRecord.containers),
+    "normalized ticket remote containers must be an array"
+  );
+  for (const container of remoteRecord.containers) {
+    const containerRecord = asRecord(container, "normalized ticket container");
+    assertValue(
+      (TICKET_LINK_CONTAINER_KINDS as readonly string[]).includes(
+        String(containerRecord.kind)
+      ),
+      "normalized ticket container kind is invalid"
+    );
+    assertNonEmptyString(containerRecord.id, "normalized ticket container id");
+    if (containerRecord.name !== undefined) {
+      assertNonEmptyString(
+        containerRecord.name,
+        "normalized ticket container name"
+      );
+    }
+  }
+
+  if (record.adapterMetadata !== undefined) {
+    const metadataRecord = asRecord(
+      record.adapterMetadata,
+      "normalized ticket adapter metadata"
+    );
+    for (const [key, value] of Object.entries(metadataRecord)) {
+      assertNonEmptyString(key, "normalized ticket adapter metadata key");
+      assertTicketSchemaValue(
+        value,
+        `normalized ticket adapter metadata ${key}`
+      );
+    }
+  }
+
+  return record as NormalizedTicketLink;
+};
+
+const parseTicketAuthorityRule = (
+  input: unknown,
+  label: string,
+  linkIds?: ReadonlySet<string>
+): TicketAuthorityRule => {
+  const record = asRecord(input, label);
+  assertValue(
+    record.policy === "replace" ||
+      record.policy === "append" ||
+      record.policy === "set_union",
+    `${label} policy must be replace, append, or set_union`
+  );
+
+  if (record.winner !== undefined) {
+    const winnerRecord = asRecord(record.winner, `${label} winner`);
+    assertValue(
+      winnerRecord.kind === "local" ||
+        winnerRecord.kind === "origin" ||
+        winnerRecord.kind === "link",
+      `${label} winner kind must be local, origin, or link`
+    );
+    if (winnerRecord.kind === "link") {
+      assertNonEmptyString(winnerRecord.linkId, `${label} winner linkId`);
+      if (linkIds) {
+        assertValue(
+          linkIds.has(winnerRecord.linkId),
+          `${label} winner linkId must reference an existing link`
+        );
+      }
+    }
+  }
+
+  return record as TicketAuthorityRule;
+};
+
+const assertTicketSchemaValue = (input: unknown, label: string): void => {
+  if (
+    input === null ||
+    typeof input === "string" ||
+    typeof input === "number" ||
+    typeof input === "boolean"
+  ) {
+    return;
+  }
+
+  if (Array.isArray(input)) {
+    for (const [index, value] of input.entries()) {
+      assertTicketSchemaValue(value, `${label}[${index}]`);
+    }
+    return;
+  }
+
+  if (typeof input === "object") {
+    for (const [key, value] of Object.entries(asRecord(input, label))) {
+      assertNonEmptyString(key, `${label} key`);
+      assertTicketSchemaValue(value, `${label}.${key}`);
+    }
+    return;
+  }
+
+  throw new Error(`${label} must be a JSON-like metadata value`);
+};
+
+const assertStringList = (input: unknown, label: string): void => {
+  assertValue(Array.isArray(input), `${label} must be an array`);
+  for (const [index, value] of input.entries()) {
+    assertNonEmptyString(value, `${label}[${index}]`);
+  }
+};
+
+const assertTicketStatus = (input: unknown): asserts input is TicketStatus => {
+  assertValue(
+    (TICKET_STATUSES as readonly string[]).includes(String(input)),
+    "ticket status must be open, in_progress, blocked, or done"
+  );
+};
+
+const assertExternalTicketSystem = (
+  input: unknown
+): asserts input is ExternalTicketSystem => {
+  assertValue(
+    (EXTERNAL_TICKET_SYSTEMS as readonly string[]).includes(String(input)),
+    "external ticket system must be linear, github, or asana"
+  );
+};
+
+const assertIsoTimestamp = (input: unknown, label: string): void => {
+  assertNonEmptyString(input, label);
+  assertValue(
+    !Number.isNaN(Date.parse(input)),
+    `${label} must be an ISO timestamp`
+  );
+};
+
+const assertUrl = (input: unknown, label: string): void => {
+  assertNonEmptyString(input, label);
+  try {
+    new URL(input);
+  } catch {
+    throw new Error(`${label} must be a valid URL`);
+  }
+};
+
+const assertString = (input: unknown, label: string): void => {
+  assertValue(typeof input === "string", `${label} must be a string`);
+};
+
+const assertNonEmptyString = (input: unknown, label: string): void => {
+  assertString(input, label);
+  assertValue(input.trim().length > 0, `${label} must be a non-empty string`);
+};
+
+const asRecord = (input: unknown, label: string): Record<string, unknown> => {
+  assertValue(
+    Boolean(input) && typeof input === "object" && !Array.isArray(input),
+    `${label} must be an object`
+  );
+  return input as Record<string, unknown>;
+};
+
+const assertValue = (condition: boolean, message: string): void => {
+  if (!condition) {
+    throw new Error(message);
+  }
+};
diff --git a/tests/tickets-normalized-model.test.ts b/tests/tickets-normalized-model.test.ts
new file mode 100644
index 000000000..a9fec0f98
--- /dev/null
+++ b/tests/tickets-normalized-model.test.ts
@@ -0,0 +1,444 @@
+import { expect, test } from "bun:test";
+
+import {
+  buildNormalizedTicketLink,
+  normalizedTicketAuthoritySchema,
+  normalizedTicketEntitySchema,
+  normalizeLegacyTicketSummary,
+  TICKET_AUTHORITY_FIELDS,
+} from "../src/control-plane/extensions/tickets/normalized-model.ts";
+
+const createMinimalNormalizedTicket = () =>
+  ({
+    schemaVersion: 1,
+    kind: "ticket",
+    id: "T-00099",
+    canonical: {
+      title: "Normalized ticket",
+      status: "open",
+      tags: [],
+      relationships: {
+        dependsOn: [],
+        blocks: [],
+      },
+      timestamps: {
+        createdAt: "2026-03-13T18:00:00.000Z",
+        updatedAt: "2026-03-13T18:05:00.000Z",
+      },
+    },
+    provenance: {
+      origin: {
+        kind: "local",
+        system: "hack",
+      },
+      links: [],
+      authority: {
+        defaultRule: {
+          policy: "replace",
+          winner: { kind: "local" },
+        },
+        fieldRules: {},
+      },
+    },
+  }) as const;
+
+test("normalizes a local-only ticket with local authority defaults", () => {
+  const normalized = normalizeLegacyTicketSummary({
+    ticket: {
+      ticketId: "T-00042",
+      title: "Keep local-only work local",
+      body: "No remote linkage yet.",
+      status: "open",
+      createdAt: "2026-03-13T18:00:00.000Z",
+      updatedAt: "2026-03-13T18:05:00.000Z",
+      dependsOn: [],
+      blocks: [],
+      owner: "hack",
+      source: "hack",
+      tags: ["core"],
+      projectId: "proj_local",
+      projectName: "Hack App",
+    },
+  });
+
+  expect(normalizedTicketEntitySchema.parse(normalized)).toEqual(normalized);
+  expect(normalized.provenance.origin).toEqual({
+    kind: "local",
+    system: "hack",
+  });
+  expect(normalized.provenance.links).toEqual([]);
+  expect(normalized.provenance.authority.defaultRule).toEqual({
+    policy: "replace",
+    winner: { kind: "local" },
+  });
+  expect(normalized.canonical.project).toEqual({
+    id: "proj_local",
+    name: "Hack App",
+  });
+});
+
+test("normalizes a Linear-origin ticket into generic provenance, links, and authority", () => {
+  const normalized = normalizeLegacyTicketSummary({
+    ticket: {
+      ticketId: "T-00043",
+      title: "Imported from Linear",
+      body: "Remote source stays authoritative.",
+      status: "in_progress",
+      createdAt: "2026-03-13T18:10:00.000Z",
+      updatedAt: "2026-03-13T18:15:00.000Z",
+      dependsOn: ["T-00042"],
+      blocks: [],
+      owner: "linear",
+      source: "linear",
+      assignee: "alice@hack",
+      tags: ["sync", "linear"],
+      externalSystem: "linear",
+      externalId: "lin_123",
+      externalKey: "HACK-449",
+      externalUrl: "https://linear.app/hackdance/issue/HACK-449",
+      externalProjectId: "linear_project_1",
+      externalProjectName: "Tickets Normalization Core",
+      externalTeamId: "linear_team_1",
+      projectId: "proj_linear",
+      projectName: "Hack App",
+    },
+    linkContext: {
+      profileId: "default",
+      workspaceId: "linear_workspace_1",
+      workspaceName: "Hack Dance",
+      adapterMetadata: {
+        stateId: "started",
+        priority: 2,
+      },
+    },
+  });
+
+  expect(normalizedTicketEntitySchema.parse(normalized)).toEqual(normalized);
+  expect(normalized.provenance.origin).toEqual({
+    kind: "external",
+    system: "linear",
+    linkId: "linear:lin_123",
+  });
+  expect(normalized.provenance.authority.defaultRule).toEqual({
+    policy: "replace",
+    winner: { kind: "origin" },
+  });
+  expect(normalized.provenance.links).toEqual([
+    {
+      linkId: "linear:lin_123",
+      system: "linear",
+      role: "origin",
+      syncDirection: "bidirectional",
+      connection: {
+        profileId: "default",
+        workspaceId: "linear_workspace_1",
+        workspaceName: "Hack Dance",
+      },
+      remote: {
+        id: "lin_123",
+        key: "HACK-449",
+        url: "https://linear.app/hackdance/issue/HACK-449",
+        containers: [
+          {
+            kind: "project",
+            id: "linear_project_1",
+            name: "Tickets Normalization Core",
+          },
+          {
+            kind: "team",
+            id: "linear_team_1",
+          },
+        ],
+      },
+      adapterMetadata: {
+        stateId: "started",
+        priority: 2,
+      },
+    },
+  ]);
+});
+
+test("builds generic external links that keep adapter metadata outside canonical fields", () => {
+  const link = buildNormalizedTicketLink({
+    system: "github",
+    remoteId: "issue_987",
+    remoteKey: "hack-dance/hack-cli#987",
+    remoteUrl: "https://github.com/hack-dance/hack-cli/issues/987",
+    containers: [
+      {
+        kind: "repo",
+        id: "hack-dance/hack-cli",
+        name: "hack-dance/hack-cli",
+      },
+    ],
+    connection: {
+      profileId: "work",
+      accountId: "installation_1",
+      workspaceName: "hack-dance",
+    },
+    adapterMetadata: {
+      labels: ["tickets", "sync"],
+      milestone: "Tickets Normalization Core",
+    },
+  });
+
+  expect(link).toEqual({
+    linkId: "github:issue_987",
+    system: "github",
+    role: "synced",
+    syncDirection: "bidirectional",
+    connection: {
+      profileId: "work",
+      accountId: "installation_1",
+      workspaceName: "hack-dance",
+    },
+    remote: {
+      id: "issue_987",
+      key: "hack-dance/hack-cli#987",
+      url: "https://github.com/hack-dance/hack-cli/issues/987",
+      containers: [
+        {
+          kind: "repo",
+          id: "hack-dance/hack-cli",
+          name: "hack-dance/hack-cli",
+        },
+      ],
+    },
+    adapterMetadata: {
+      labels: ["tickets", "sync"],
+      milestone: "Tickets Normalization Core",
+    },
+  });
+});
+
+test("keeps Hack-origin tickets local while adding synced external links", () => {
+  const normalized = normalizeLegacyTicketSummary({
+    ticket: {
+      ticketId: "T-00044",
+      title: "Push to GitHub after local creation",
+      status: "open",
+      createdAt: "2026-03-13T18:20:00.000Z",
+      updatedAt: "2026-03-13T18:25:00.000Z",
+      dependsOn: [],
+      blocks: [],
+      owner: "hack",
+      source: "hack",
+      tags: ["github"],
+      externalSystem: "github",
+      externalId: "issue_44",
+      externalKey: "hack-dance/hack-cli#44",
+      externalUrl: "https://github.com/hack-dance/hack-cli/issues/44",
+    },
+  });
+
+  expect(normalized.provenance.origin).toEqual({
+    kind: "local",
+    system: "hack",
+  });
+  expect(normalized.provenance.links[0]).toMatchObject({
+    system: "github",
+    role: "synced",
+    linkId: "github:issue_44",
+  });
+  expect(normalized.provenance.authority.defaultRule).toEqual({
+    policy: "replace",
+    winner: { kind: "local" },
+  });
+});
+
+test("treats owner as separate from origin when a local ticket is synced externally", () => {
+  const normalized = normalizeLegacyTicketSummary({
+    ticket: {
+      ticketId: "T-00045",
+      title: "Locally created but externally owned",
+      status: "in_progress",
+      createdAt: "2026-03-13T18:30:00.000Z",
+      updatedAt: "2026-03-13T18:35:00.000Z",
+      dependsOn: [],
+      blocks: [],
+      owner: "linear",
+      source: "hack",
+      tags: ["linear"],
+      externalSystem: "linear",
+      externalId: "lin_45",
+      externalKey: "HACK-45",
+      externalUrl: "https://linear.app/hackdance/issue/HACK-45",
+    },
+  });
+
+  expect(normalized.provenance.origin).toEqual({
+    kind: "local",
+    system: "hack",
+  });
+  expect(normalized.provenance.links).toEqual([
+    expect.objectContaining({
+      linkId: "linear:lin_45",
+      system: "linear",
+      role: "synced",
+    }),
+  ]);
+});
+
+test("covers the canonical authority fields required by sync adapters", () => {
+  expect(TICKET_AUTHORITY_FIELDS).toEqual([
+    "title",
+    "body",
+    "status",
+    "assignee",
+    "project",
+    "tags",
+    "dependsOn",
+    "blocks",
+  ]);
+});
+
+test("rejects externally sourced legacy tickets that do not include remote identity", () => {
+  expect(() =>
+    normalizeLegacyTicketSummary({
+      ticket: {
+        ticketId: "T-00046",
+        title: "Imported but missing remote identity",
+        status: "open",
+        createdAt: "2026-03-13T18:40:00.000Z",
+        updatedAt: "2026-03-13T18:45:00.000Z",
+        dependsOn: [],
+        blocks: [],
+        owner: "linear",
+        source: "linear",
+        tags: ["linear"],
+        externalSystem: "linear",
+      },
+    })
+  ).toThrow(
+    "externally sourced legacy ticket requires externalSystem and externalId"
+  );
+});
+
+test("does not fabricate container ids from legacy project names", () => {
+  const normalized = normalizeLegacyTicketSummary({
+    ticket: {
+      ticketId: "T-00047",
+      title: "Imported with a project name only",
+      status: "open",
+      createdAt: "2026-03-13T18:50:00.000Z",
+      updatedAt: "2026-03-13T18:55:00.000Z",
+      dependsOn: [],
+      blocks: [],
+      owner: "linear",
+      source: "linear",
+      tags: ["linear"],
+      externalSystem: "linear",
+      externalId: "lin_47",
+      externalProjectName: "Name Without Stable Id",
+      externalTeamId: "team_47",
+    },
+  });
+
+  expect(normalized.provenance.links).toEqual([
+    {
+      linkId: "linear:lin_47",
+      system: "linear",
+      role: "origin",
+      syncDirection: "bidirectional",
+      remote: {
+        id: "lin_47",
+        containers: [
+          {
+            kind: "team",
+            id: "team_47",
+          },
+        ],
+      },
+    },
+  ]);
+});
+
+test("rejects external origin records that do not point at a matching origin link", () => {
+  const normalized = createMinimalNormalizedTicket();
+
+  expect(() =>
+    normalizedTicketEntitySchema.parse({
+      ...normalized,
+      provenance: {
+        ...normalized.provenance,
+        origin: {
+          kind: "external",
+          system: "linear",
+          linkId: "linear:lin_missing",
+        },
+        links: [
+          buildNormalizedTicketLink({
+            system: "linear",
+            remoteId: "lin_123",
+            role: "origin",
+          }),
+        ],
+      },
+    })
+  ).toThrow(
+    "normalized ticket external origin must reference a matching origin link"
+  );
+});
+
+test("rejects authority winners that reference unknown links", () => {
+  const normalized = createMinimalNormalizedTicket();
+
+  expect(() =>
+    normalizedTicketEntitySchema.parse({
+      ...normalized,
+      provenance: {
+        ...normalized.provenance,
+        links: [
+          buildNormalizedTicketLink({
+            system: "github",
+            remoteId: "issue_42",
+          }),
+        ],
+        authority: {
+          defaultRule: {
+            policy: "replace",
+            winner: { kind: "link", linkId: "github:issue_missing" },
+          },
+          fieldRules: {},
+        },
+      },
+    })
+  ).toThrow(
+    "normalized ticket authority defaultRule winner linkId must reference an existing link"
+  );
+});
+
+test("parses standalone authority rules with link winners without entity context", () => {
+  expect(
+    normalizedTicketAuthoritySchema.parse({
+      defaultRule: {
+        policy: "replace",
+        winner: { kind: "link", linkId: "github:issue_42" },
+      },
+      fieldRules: {
+        tags: {
+          policy: "set_union",
+        },
+      },
+    })
+  ).toEqual({
+    defaultRule: {
+      policy: "replace",
+      winner: { kind: "link", linkId: "github:issue_42" },
+    },
+    fieldRules: {
+      tags: {
+        policy: "set_union",
+      },
+    },
+  });
+});
+
+test("rejects blank remote identifiers when building normalized links", () => {
+  expect(() =>
+    buildNormalizedTicketLink({
+      system: "asana",
+      remoteId: "   ",
+    })
+  ).toThrow("normalized ticket remote id must be a non-empty string");
+});

From 57c479e1db1b47fdb2822faaea791fe349fca7d8 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 22:51:02 +0000
Subject: [PATCH 007/134] feat(tickets): persist sqlite projection cache

---
 .../extensions/tickets/sqlite-projection.ts   | 402 ++++++++++++++++++
 src/control-plane/extensions/tickets/store.ts | 207 +++++++--
 tests/tickets-extension.test.ts               |  52 +++
 tests/tickets-store.test.ts                   |  42 ++
 4 files changed, 656 insertions(+), 47 deletions(-)
 create mode 100644 src/control-plane/extensions/tickets/sqlite-projection.ts

diff --git a/src/control-plane/extensions/tickets/sqlite-projection.ts b/src/control-plane/extensions/tickets/sqlite-projection.ts
new file mode 100644
index 000000000..141299da2
--- /dev/null
+++ b/src/control-plane/extensions/tickets/sqlite-projection.ts
@@ -0,0 +1,402 @@
+import { Database } from "bun:sqlite";
+import { mkdir, readdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+import type {
+  TicketComment,
+  TicketEvent,
+  TicketReviewNote,
+  TicketStoreSnapshot,
+  TicketSummary,
+  TicketSyncCheckpoint,
+  TicketSyncConflict,
+} from "./store.ts";
+import { sha256Hex, stableStringify } from "./util.ts";
+
+const PROJECTION_SCHEMA_VERSION = 1;
+
+type ProjectionMetaRow = {
+  readonly key: string;
+  readonly value: string;
+};
+
+type ProjectionJsonRow = {
+  readonly ticket_id: string;
+  readonly json_value: string;
+};
+
+type ProjectionEventRow = {
+  readonly ticket_id: string;
+  readonly json_value: string;
+  readonly ts: number;
+  readonly order_key: string | null;
+};
+
+export function createTicketsSqliteProjection(opts: {
+  readonly projectRoot: string;
+}): {
+  readonly computeJournalSignature: (input: {
+    readonly ticketsRoot: string;
+  }) => Promise<string>;
+  readonly path: string;
+  readonly readSnapshot: (input: {
+    readonly journalSignature: string;
+  }) => Promise<TicketStoreSnapshot | null>;
+  readonly replaceSnapshot: (input: {
+    readonly journalSignature: string;
+    readonly snapshot: TicketStoreSnapshot;
+  }) => Promise<void>;
+} {
+  const path = resolve(opts.projectRoot, ".hack/tickets/projection.sqlite");
+
+  const computeJournalSignature = async (input: {
+    readonly ticketsRoot: string;
+  }): Promise<string> => {
+    const eventsDir = resolve(input.ticketsRoot, ".hack/tickets/events");
+    let entries: string[] = [];
+    try {
+      entries = (await readdir(eventsDir))
+        .filter((entry) => entry.endsWith(".jsonl"))
+        .sort();
+    } catch {
+      return sha256Hex({ value: "" });
+    }
+
+    const files = await Promise.all(
+      entries.map(async (entry) => {
+        const text = await Bun.file(resolve(eventsDir, entry))
+          .text()
+          .catch(() => "");
+        return {
+          entry,
+          text,
+        };
+      })
+    );
+
+    return sha256Hex({
+      value: stableStringify(
+        files.map((file) => ({
+          entry: file.entry,
+          text: file.text,
+        }))
+      ),
+    });
+  };
+
+  const replaceSnapshot = async (input: {
+    readonly journalSignature: string;
+    readonly snapshot: TicketStoreSnapshot;
+  }): Promise<void> => {
+    await mkdir(dirname(path), { recursive: true });
+    const db = new Database(path);
+    try {
+      initializeProjectionSchema({ db });
+
+      const insertMeta = db.query(
+        "INSERT INTO projection_meta (key, value) VALUES (?, ?)"
+      );
+      const insertTicket = db.query(
+        "INSERT INTO tickets (ticket_id, title, updated_at, json_value) VALUES (?, ?, ?, ?)"
+      );
+      const insertEvent = db.query(
+        "INSERT INTO journal_events (event_id, ticket_id, ts, order_key, event_type, idempotency_key, json_value) VALUES (?, ?, ?, ?, ?, ?, ?)"
+      );
+      const insertComment = db.query(
+        "INSERT INTO ticket_comments (comment_id, ticket_id, json_value) VALUES (?, ?, ?)"
+      );
+      const insertReviewNote = db.query(
+        "INSERT INTO ticket_review_notes (note_id, ticket_id, json_value) VALUES (?, ?, ?)"
+      );
+      const insertCheckpoint = db.query(
+        "INSERT INTO ticket_sync_checkpoints (checkpoint_id, ticket_id, json_value) VALUES (?, ?, ?)"
+      );
+      const insertConflict = db.query(
+        "INSERT INTO ticket_sync_conflicts (conflict_id, ticket_id, json_value) VALUES (?, ?, ?)"
+      );
+
+      const events = [...input.snapshot.eventsByTicket.values()].flat();
+
+      const transaction = db.transaction(() => {
+        db.exec(`
+          DELETE FROM projection_meta;
+          DELETE FROM tickets;
+          DELETE FROM journal_events;
+          DELETE FROM ticket_comments;
+          DELETE FROM ticket_review_notes;
+          DELETE FROM ticket_sync_checkpoints;
+          DELETE FROM ticket_sync_conflicts;
+        `);
+
+        insertMeta.run("schema_version", String(PROJECTION_SCHEMA_VERSION));
+        insertMeta.run("journal_signature", input.journalSignature);
+        insertMeta.run("rebuilt_at", new Date().toISOString());
+
+        for (const ticket of input.snapshot.tickets) {
+          insertTicket.run(
+            ticket.ticketId,
+            ticket.title,
+            ticket.updatedAt,
+            JSON.stringify(ticket)
+          );
+        }
+
+        for (const event of events) {
+          insertEvent.run(
+            event.eventId,
+            event.ticketId,
+            event.ts,
+            event.orderKey ?? null,
+            event.eventType,
+            event.idempotencyKey,
+            JSON.stringify(event)
+          );
+        }
+
+        writeMapEntries({
+          map: input.snapshot.commentsByTicket,
+          write: (comment: TicketComment) => {
+            insertComment.run(
+              comment.commentId,
+              comment.ticketId,
+              JSON.stringify(comment)
+            );
+          },
+        });
+
+        writeMapEntries({
+          map: input.snapshot.reviewNotesByTicket,
+          write: (reviewNote: TicketReviewNote) => {
+            insertReviewNote.run(
+              reviewNote.noteId,
+              reviewNote.ticketId,
+              JSON.stringify(reviewNote)
+            );
+          },
+        });
+
+        writeMapEntries({
+          map: input.snapshot.syncCheckpointsByTicket,
+          write: (checkpoint: TicketSyncCheckpoint) => {
+            insertCheckpoint.run(
+              checkpoint.checkpointId,
+              checkpoint.ticketId,
+              JSON.stringify(checkpoint)
+            );
+          },
+        });
+
+        writeMapEntries({
+          map: input.snapshot.conflictsByTicket,
+          write: (conflict: TicketSyncConflict) => {
+            insertConflict.run(
+              conflict.conflictId,
+              conflict.ticketId,
+              JSON.stringify(conflict)
+            );
+          },
+        });
+      });
+
+      transaction();
+    } finally {
+      db.close();
+    }
+  };
+
+  const readSnapshot = async (input: {
+    readonly journalSignature: string;
+  }): Promise<TicketStoreSnapshot | null> => {
+    if (!(await Bun.file(path).exists())) {
+      return null;
+    }
+
+    const db = new Database(path);
+    try {
+      initializeProjectionSchema({ db });
+      const metaRows = db
+        .query("SELECT key, value FROM projection_meta")
+        .all() as ProjectionMetaRow[];
+      const meta = new Map(
+        metaRows.map((row) => [row.key, row.value] as const)
+      );
+      if (
+        meta.get("schema_version") !== String(PROJECTION_SCHEMA_VERSION) ||
+        meta.get("journal_signature") !== input.journalSignature
+      ) {
+        return null;
+      }
+
+      const tickets = (
+        db
+          .query(
+            "SELECT ticket_id, json_value FROM tickets ORDER BY CAST(SUBSTR(ticket_id, 3) AS INTEGER), ticket_id"
+          )
+          .all() as ProjectionJsonRow[]
+      )
+        .map((row) =>
+          parseProjectionJson<TicketSummary>({ json: row.json_value })
+        )
+        .filter((ticket): ticket is TicketSummary => ticket !== null);
+
+      const eventsByTicket = readEventRows({ db });
+      const commentsByTicket = readRowsByTicket<TicketComment>({
+        db,
+        table: "ticket_comments",
+      });
+      const reviewNotesByTicket = readRowsByTicket<TicketReviewNote>({
+        db,
+        table: "ticket_review_notes",
+      });
+      const syncCheckpointsByTicket = readRowsByTicket<TicketSyncCheckpoint>({
+        db,
+        table: "ticket_sync_checkpoints",
+      });
+      const conflictsByTicket = readRowsByTicket<TicketSyncConflict>({
+        db,
+        table: "ticket_sync_conflicts",
+      });
+
+      return {
+        tickets,
+        eventsByTicket,
+        commentsByTicket,
+        reviewNotesByTicket,
+        syncCheckpointsByTicket,
+        conflictsByTicket,
+      };
+    } finally {
+      db.close();
+    }
+  };
+
+  return {
+    computeJournalSignature,
+    path,
+    readSnapshot,
+    replaceSnapshot,
+  };
+}
+
+function initializeProjectionSchema(input: { readonly db: Database }): void {
+  input.db.exec(`
+    PRAGMA journal_mode = WAL;
+    CREATE TABLE IF NOT EXISTS projection_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS tickets (
+      ticket_id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      json_value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS journal_events (
+      event_id TEXT PRIMARY KEY,
+      ticket_id TEXT NOT NULL,
+      ts INTEGER NOT NULL,
+      order_key TEXT,
+      event_type TEXT NOT NULL,
+      idempotency_key TEXT NOT NULL,
+      json_value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS ticket_comments (
+      comment_id TEXT PRIMARY KEY,
+      ticket_id TEXT NOT NULL,
+      json_value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS ticket_review_notes (
+      note_id TEXT PRIMARY KEY,
+      ticket_id TEXT NOT NULL,
+      json_value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS ticket_sync_checkpoints (
+      checkpoint_id TEXT PRIMARY KEY,
+      ticket_id TEXT NOT NULL,
+      json_value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS ticket_sync_conflicts (
+      conflict_id TEXT PRIMARY KEY,
+      ticket_id TEXT NOT NULL,
+      json_value TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS journal_events_ticket_id_idx
+      ON journal_events (ticket_id, ts, order_key);
+    CREATE INDEX IF NOT EXISTS ticket_comments_ticket_id_idx
+      ON ticket_comments (ticket_id);
+    CREATE INDEX IF NOT EXISTS ticket_review_notes_ticket_id_idx
+      ON ticket_review_notes (ticket_id);
+    CREATE INDEX IF NOT EXISTS ticket_sync_checkpoints_ticket_id_idx
+      ON ticket_sync_checkpoints (ticket_id);
+    CREATE INDEX IF NOT EXISTS ticket_sync_conflicts_ticket_id_idx
+      ON ticket_sync_conflicts (ticket_id);
+  `);
+}
+
+function parseProjectionJson<T>(input: { readonly json: string }): T | null {
+  try {
+    return JSON.parse(input.json) as T;
+  } catch {
+    return null;
+  }
+}
+
+function readEventRows(input: {
+  readonly db: Database;
+}): Map<string, TicketEvent[]> {
+  const rows = input.db
+    .query(
+      "SELECT ticket_id, json_value, ts, order_key FROM journal_events ORDER BY ts, order_key, event_id"
+    )
+    .all() as ProjectionEventRow[];
+
+  const grouped = new Map<string, TicketEvent[]>();
+  for (const row of rows) {
+    const event = parseProjectionJson<TicketEvent>({ json: row.json_value });
+    if (!event) {
+      continue;
+    }
+    const list = grouped.get(row.ticket_id) ?? [];
+    list.push(event);
+    grouped.set(row.ticket_id, list);
+  }
+  return grouped;
+}
+
+function readRowsByTicket<T>(input: {
+  readonly db: Database;
+  readonly table:
+    | "ticket_comments"
+    | "ticket_review_notes"
+    | "ticket_sync_checkpoints"
+    | "ticket_sync_conflicts";
+}): Map<string, T[]> {
+  const rows = input.db
+    .query(
+      `SELECT ticket_id, json_value FROM ${input.table} ORDER BY ticket_id, rowid`
+    )
+    .all() as ProjectionJsonRow[];
+
+  const grouped = new Map<string, T[]>();
+  for (const row of rows) {
+    const value = parseProjectionJson<T>({ json: row.json_value });
+    if (!value) {
+      continue;
+    }
+    const list = grouped.get(row.ticket_id) ?? [];
+    list.push(value);
+    grouped.set(row.ticket_id, list);
+  }
+  return grouped;
+}
+
+function writeMapEntries<T>(input: {
+  readonly map: ReadonlyMap<string, readonly T[]>;
+  readonly write: (value: T) => void;
+}): void {
+  for (const values of input.map.values()) {
+    for (const value of values) {
+      input.write(value);
+    }
+  }
+}
diff --git a/src/control-plane/extensions/tickets/store.ts b/src/control-plane/extensions/tickets/store.ts
index aa855a129..ef2851212 100644
--- a/src/control-plane/extensions/tickets/store.ts
+++ b/src/control-plane/extensions/tickets/store.ts
@@ -9,6 +9,7 @@ import {
   createNormalizedTicket,
   projectNormalizedTicketSummary,
 } from "./domain.ts";
+import { createTicketsSqliteProjection } from "./sqlite-projection.ts";
 import { createGitTicketsChannel } from "./tickets-git-channel.ts";
 import {
   formatTicketId,
@@ -170,6 +171,11 @@ type MaterializedTicketState = {
   readonly conflictsByTicket: Map<string, TicketSyncConflict[]>;
 };
 
+type TicketStoreContext = {
+  readonly events: readonly TicketEvent[];
+  readonly snapshot: TicketStoreSnapshot;
+};
+
 function normalizeTicketSummaryCompatibility(input: {
   readonly ticket: TicketSummary;
 }): TicketSummary {
@@ -323,6 +329,9 @@ export function createTicketsStore(opts: {
     config: opts.controlPlaneConfig.tickets.git,
     logger: opts.logger,
   });
+  const projection = createTicketsSqliteProjection({
+    projectRoot: opts.projectRoot,
+  });
   let eventSequence = 0;
 
   const resolveActor = (override?: string): string => {
@@ -374,9 +383,10 @@ export function createTicketsStore(opts: {
     };
   };
 
-  const readAllEvents = async (): Promise<readonly TicketEvent[]> => {
-    const root = await git.ensureCheckedOut();
-    const eventsDir = resolve(root, ".hack/tickets/events");
+  const readAllEventsFromRoot = async (input: {
+    readonly root: string;
+  }): Promise<readonly TicketEvent[]> => {
+    const eventsDir = resolve(input.root, ".hack/tickets/events");
 
     let entries: string[] = [];
     try {
@@ -432,11 +442,6 @@ export function createTicketsStore(opts: {
     return events;
   };
 
-  const materializeTickets = async (): Promise<Map<string, TicketSummary>> => {
-    const events = await readAllEvents();
-    return materializeSnapshotFromEvents({ events }).tickets;
-  };
-
   const materializeSnapshotFromEvents = (input: {
     readonly events: readonly TicketEvent[];
   }): MaterializedTicketState => {
@@ -490,12 +495,101 @@ export function createTicketsStore(opts: {
     return out;
   };
 
+  const buildStoreSnapshot = (input: {
+    readonly events: readonly TicketEvent[];
+    readonly materialized: MaterializedTicketState;
+  }): TicketStoreSnapshot => {
+    return {
+      tickets: sortTickets({ tickets: input.materialized.tickets.values() }),
+      eventsByTicket: groupEventsByTicket({ events: input.events }),
+      commentsByTicket: input.materialized.commentsByTicket,
+      reviewNotesByTicket: input.materialized.reviewNotesByTicket,
+      syncCheckpointsByTicket: input.materialized.syncCheckpointsByTicket,
+      conflictsByTicket: input.materialized.conflictsByTicket,
+    };
+  };
+
+  const rebuildProjectionFromJournal = async (): Promise<
+    | { readonly ok: true; readonly context: TicketStoreContext }
+    | {
+        readonly ok: false;
+        readonly error: string;
+      }
+  > => {
+    try {
+      const root = await git.ensureCheckedOut();
+      const events = await readAllEventsFromRoot({ root });
+      const materialized = materializeSnapshotFromEvents({ events });
+      const snapshot = buildStoreSnapshot({ events, materialized });
+      const journalSignature = await projection.computeJournalSignature({
+        ticketsRoot: root,
+      });
+      await projection.replaceSnapshot({
+        journalSignature,
+        snapshot,
+      });
+      return {
+        ok: true,
+        context: {
+          events,
+          snapshot,
+        },
+      };
+    } catch (error: unknown) {
+      const message =
+        error instanceof Error
+          ? error.message
+          : "Failed to rebuild tickets sqlite projection";
+      return {
+        ok: false,
+        error: message,
+      };
+    }
+  };
+
+  const loadStoreContext = async (): Promise<TicketStoreContext> => {
+    const root = await git.ensureCheckedOut();
+    const journalSignature = await projection.computeJournalSignature({
+      ticketsRoot: root,
+    });
+    const persisted = await projection.readSnapshot({
+      journalSignature,
+    });
+    if (persisted) {
+      const events = [...persisted.eventsByTicket.values()].flat();
+      return {
+        events,
+        snapshot: persisted,
+      };
+    }
+
+    const rebuilt = await rebuildProjectionFromJournal();
+    if (rebuilt.ok) {
+      return rebuilt.context;
+    }
+
+    const events = await readAllEventsFromRoot({ root });
+    const materialized = materializeSnapshotFromEvents({ events });
+    return {
+      events,
+      snapshot: buildStoreSnapshot({ events, materialized }),
+    };
+  };
+
+  const materializeTickets = async (): Promise<Map<string, TicketSummary>> => {
+    const context = await loadStoreContext();
+    return new Map(
+      context.snapshot.tickets.map(
+        (ticket) => [ticket.ticketId, ticket] as const
+      )
+    );
+  };
+
   const computeNextTicketId = async (): Promise<string> => {
-    const events = await readAllEvents();
-    const snapshot = materializeSnapshotFromEvents({ events });
+    const { snapshot } = await loadStoreContext();
     let max = 0;
-    for (const ticketId of snapshot.tickets.keys()) {
-      const n = parseTicketNumber(ticketId);
+    for (const ticket of snapshot.tickets) {
+      const n = parseTicketNumber(ticket.ticketId);
       if (n !== null && n > max) {
         max = n;
       }
@@ -523,7 +617,35 @@ export function createTicketsStore(opts: {
       actor: input.actor,
     });
 
-    return await git.appendEvents({ events: [event] });
+    const wrote = await git.appendEvents({ events: [event] });
+    if (!wrote.ok) {
+      return wrote;
+    }
+
+    const rebuilt = await rebuildProjectionFromJournal();
+    if (!rebuilt.ok) {
+      return rebuilt;
+    }
+
+    return { ok: true };
+  };
+
+  const appendEventsAndRefresh = async (input: {
+    readonly events: readonly TicketEvent[];
+  }): Promise<
+    { readonly ok: true } | { readonly ok: false; readonly error: string }
+  > => {
+    const wrote = await git.appendEvents({ events: input.events });
+    if (!wrote.ok) {
+      return wrote;
+    }
+
+    const rebuilt = await rebuildProjectionFromJournal();
+    if (!rebuilt.ok) {
+      return rebuilt;
+    }
+
+    return { ok: true };
   };
 
   return {
@@ -588,7 +710,7 @@ export function createTicketsStore(opts: {
         actor: input.actor,
       });
 
-      const wrote = await git.appendEvents({ events: [event] });
+      const wrote = await appendEventsAndRefresh({ events: [event] });
       if (!wrote.ok) {
         return wrote;
       }
@@ -715,32 +837,33 @@ export function createTicketsStore(opts: {
         actor: input.actor,
       });
 
-      return await git.appendEvents({ events: [event] });
+      return await appendEventsAndRefresh({ events: [event] });
     },
 
     listTickets: async () => {
-      const events = await readAllEvents();
-      const snapshot = materializeSnapshotFromEvents({ events });
-      return sortTickets({ tickets: snapshot.tickets.values() });
+      const { snapshot } = await loadStoreContext();
+      return snapshot.tickets;
     },
 
     getTicket: async ({ ticketId }) => {
-      const events = await readAllEvents();
-      const snapshot = materializeSnapshotFromEvents({ events });
-      return snapshot.tickets.get(ticketId) ?? null;
+      const { snapshot } = await loadStoreContext();
+      return (
+        snapshot.tickets.find((ticket) => ticket.ticketId === ticketId) ?? null
+      );
     },
 
     listEvents: async ({ ticketId }) => {
-      const events = await readAllEvents();
-      return events.filter((event) => event.ticketId === ticketId);
+      const { snapshot } = await loadStoreContext();
+      return snapshot.eventsByTicket.get(ticketId) ?? [];
     },
 
     getTicketDetail: async ({ ticketId }) => {
-      const events = await readAllEvents();
-      const snapshot = materializeSnapshotFromEvents({ events });
+      const { snapshot } = await loadStoreContext();
       return {
-        ticket: snapshot.tickets.get(ticketId) ?? null,
-        events: events.filter((event) => event.ticketId === ticketId),
+        ticket:
+          snapshot.tickets.find((ticket) => ticket.ticketId === ticketId) ??
+          null,
+        events: snapshot.eventsByTicket.get(ticketId) ?? [],
         comments: snapshot.commentsByTicket.get(ticketId) ?? [],
         reviewNotes: snapshot.reviewNotesByTicket.get(ticketId) ?? [],
         syncCheckpoints: snapshot.syncCheckpointsByTicket.get(ticketId) ?? [],
@@ -784,7 +907,7 @@ export function createTicketsStore(opts: {
         actor: input.actor,
       });
 
-      const wrote = await git.appendEvents({ events: [event] });
+      const wrote = await appendEventsAndRefresh({ events: [event] });
       if (!wrote.ok) {
         return wrote;
       }
@@ -830,7 +953,7 @@ export function createTicketsStore(opts: {
         actor: input.actor,
       });
 
-      const wrote = await git.appendEvents({ events: [event] });
+      const wrote = await appendEventsAndRefresh({ events: [event] });
       if (!wrote.ok) {
         return wrote;
       }
@@ -849,8 +972,7 @@ export function createTicketsStore(opts: {
     },
 
     linkCommentExternalId: async (input) => {
-      const detail = await readAllEvents();
-      const snapshot = materializeSnapshotFromEvents({ events: detail });
+      const { snapshot } = await loadStoreContext();
       const comments = snapshot.commentsByTicket.get(input.ticketId) ?? [];
       const current = comments.find(
         (comment) => comment.commentId === input.commentId
@@ -879,7 +1001,7 @@ export function createTicketsStore(opts: {
         actor: input.actor,
       });
 
-      return await git.appendEvents({ events: [event] });
+      return await appendEventsAndRefresh({ events: [event] });
     },
 
     recordSyncCheckpoint: async (input) => {
@@ -926,7 +1048,7 @@ export function createTicketsStore(opts: {
         actor: input.actor,
       });
 
-      const wrote = await git.appendEvents({ events: [event] });
+      const wrote = await appendEventsAndRefresh({ events: [event] });
       if (!wrote.ok) {
         return wrote;
       }
@@ -993,7 +1115,7 @@ export function createTicketsStore(opts: {
         actor: input.actor,
       });
 
-      const wrote = await git.appendEvents({ events: [event] });
+      const wrote = await appendEventsAndRefresh({ events: [event] });
       if (!wrote.ok) {
         return wrote;
       }
@@ -1021,8 +1143,7 @@ export function createTicketsStore(opts: {
     },
 
     resolveSyncConflict: async (input) => {
-      const detail = await readAllEvents();
-      const snapshot = materializeSnapshotFromEvents({ events: detail });
+      const { snapshot } = await loadStoreContext();
       const conflicts = snapshot.conflictsByTicket.get(input.ticketId) ?? [];
       const current = conflicts.find(
         (conflict) => conflict.conflictId === input.conflictId
@@ -1045,20 +1166,12 @@ export function createTicketsStore(opts: {
         actor: input.actor,
       });
 
-      return await git.appendEvents({ events: [event] });
+      return await appendEventsAndRefresh({ events: [event] });
     },
 
     readSnapshot: async () => {
-      const events = await readAllEvents();
-      const snapshot = materializeSnapshotFromEvents({ events });
-      return {
-        tickets: sortTickets({ tickets: snapshot.tickets.values() }),
-        eventsByTicket: groupEventsByTicket({ events }),
-        commentsByTicket: snapshot.commentsByTicket,
-        reviewNotesByTicket: snapshot.reviewNotesByTicket,
-        syncCheckpointsByTicket: snapshot.syncCheckpointsByTicket,
-        conflictsByTicket: snapshot.conflictsByTicket,
-      };
+      const { snapshot } = await loadStoreContext();
+      return snapshot;
     },
 
     sync: async () => {
diff --git a/tests/tickets-extension.test.ts b/tests/tickets-extension.test.ts
index dc336da44..e85e863cf 100644
--- a/tests/tickets-extension.test.ts
+++ b/tests/tickets-extension.test.ts
@@ -260,6 +260,58 @@ testIntegration(
   }
 );
 
+testIntegration(
+  "tickets extension: cli rebuilds sqlite projection after local deletion",
+  { timeout: 60_000 },
+  async () => {
+    const root = await mkdirTempDir({
+      prefix: "hack-cli-tickets-projection-e2e-",
+    });
+    const projectDir = join(root, "project");
+
+    await mkdir(projectDir, { recursive: true });
+    await copyDir({
+      from: resolve(import.meta.dir, "../examples/tickets"),
+      to: projectDir,
+    });
+
+    await run({ cwd: projectDir, cmd: ["git", "init"] });
+    await run({
+      cwd: projectDir,
+      cmd: ["git", "config", "user.email", "tests@hack"],
+    });
+    await run({
+      cwd: projectDir,
+      cmd: ["git", "config", "user.name", "hack-cli-tests"],
+    });
+    await run({ cwd: projectDir, cmd: ["git", "add", "-A"] });
+    await run({ cwd: projectDir, cmd: ["git", "commit", "-m", "init"] });
+
+    const created = await runHack({
+      cwd: projectDir,
+      args: ["tickets", "create", "--title", "Projection lifecycle", "--json"],
+    });
+    const createdJson = JSON.parse(created.stdout) as {
+      ticket: { ticketId: string };
+    };
+
+    const projectionPath = join(projectDir, ".hack/tickets/projection.sqlite");
+    expect(await Bun.file(projectionPath).exists()).toBe(true);
+
+    await rm(projectionPath, { force: true });
+    expect(await Bun.file(projectionPath).exists()).toBe(false);
+
+    const shown = await runHack({
+      cwd: projectDir,
+      args: ["tickets", "show", createdJson.ticket.ticketId, "--json"],
+    });
+    expect(shown.exitCode).toBe(0);
+    expect(await Bun.file(projectionPath).exists()).toBe(true);
+
+    await rm(root, { recursive: true, force: true });
+  }
+);
+
 interface RunResult {
   readonly stdout: string;
   readonly stderr: string;
diff --git a/tests/tickets-store.test.ts b/tests/tickets-store.test.ts
index b5f94d7a1..5250b78c0 100644
--- a/tests/tickets-store.test.ts
+++ b/tests/tickets-store.test.ts
@@ -446,6 +446,48 @@ test("tickets store writes normalized journal envelope metadata and ignores dupl
   });
 }, 20_000);
 
+test("tickets store persists a sqlite projection and rebuilds it when deleted", async () => {
+  const projectRoot = await createTempGitProject({
+    prefix: "hack-cli-tickets-projection-",
+  });
+  const projectionPath = join(projectRoot, ".hack/tickets/projection.sqlite");
+
+  const firstStore = await createStore({ projectRoot });
+  const created = await firstStore.createTicket({
+    title: "Projection ticket",
+    body: "Persisted through sqlite projection.",
+    owner: "hack",
+    source: "hack",
+    actor: "creator@hack",
+  });
+  expect(created.ok).toBe(true);
+  if (!created.ok) {
+    throw new Error(created.error);
+  }
+
+  const initialTickets = await firstStore.listTickets();
+  expect(initialTickets.map((ticket) => ticket.title)).toContain(
+    "Projection ticket"
+  );
+  expect(await Bun.file(projectionPath).exists()).toBe(true);
+
+  const secondStore = await createStore({ projectRoot });
+  const persistedTickets = await secondStore.listTickets();
+  expect(persistedTickets.map((ticket) => ticket.title)).toContain(
+    "Projection ticket"
+  );
+
+  await rm(projectionPath, { force: true });
+  expect(await Bun.file(projectionPath).exists()).toBe(false);
+
+  const rebuiltStore = await createStore({ projectRoot });
+  const rebuiltTickets = await rebuiltStore.listTickets();
+  expect(rebuiltTickets.map((ticket) => ticket.title)).toContain(
+    "Projection ticket"
+  );
+  expect(await Bun.file(projectionPath).exists()).toBe(true);
+}, 20_000);
+
 test("normalized ticket adapter preserves compatibility while exposing provenance and documents", () => {
   const summary = {
     ticketId: "T-00042",

From e6c8cb8389e9da23b289af7e366f778cc4fa3f7f Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 22:52:04 +0000
Subject: [PATCH 008/134] docs(tickets): document sqlite projection cache

---
 docs/guides/tickets.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/docs/guides/tickets.md b/docs/guides/tickets.md
index 279f60a02..c70da16d6 100644
--- a/docs/guides/tickets.md
+++ b/docs/guides/tickets.md
@@ -126,7 +126,9 @@ Tip: use `--body-stdin` for multi-line markdown.
 ## How it works
 
 - Ticket history is an append-only event log (`ticket.created`, etc.) stored as monthly JSONL files.
-- The extension reads events, materializes tickets in-memory, and renders `list/show` outputs.
+- Each event carries a normalized journal envelope (`eventId`, schema version, occurrence/recording times, source metadata, and idempotency key).
+- The journal is the portable source of truth for tickets.
+- The extension projects journal state into a local SQLite cache for durable reads and rebuilds that cache automatically when it is missing or stale.
 - Ticket writes automatically commit and push to the tickets ref when git sync is enabled and a remote exists.
 - `sync` normalizes the event logs, commits, and pushes the tickets ref.
 
@@ -135,9 +137,16 @@ Tip: use `--body-stdin` for multi-line markdown.
 In your project repo:
 
 - `.hack/tickets/events/events-YYYY-MM.jsonl` — event log segments (UTC month)
+- `.hack/tickets/projection.sqlite` — local SQLite projection cache rebuilt from the journal
 - `.hack/tickets/git/bare.git` — a bare repo used to manage the tickets ref
 - `.hack/tickets/git/worktree` — a worktree used for reading/writing ticket data
 
+Portability rules:
+
+- Only the journal under `.hack/tickets/events/` is portable ticket state.
+- The SQLite projection is local-only and can be deleted safely.
+- After sync or clone, peers rebuild `.hack/tickets/projection.sqlite` from the journal on first read.
+
 ## Configuration
 
 Tickets git configuration lives under `controlPlane.tickets.git`.

From 77e2c91d99ef29a7fcc6ad1cdc1dcc25070116c7 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 23:03:40 +0000
Subject: [PATCH 009/134] feat(tickets): normalize provenance helpers

---
 .../extensions/linear/commands.ts             | 114 +++--
 .../extensions/tickets/domain.ts              | 170 +++----
 .../extensions/tickets/provenance.ts          | 457 ++++++++++++++++++
 tests/linear-commands.test.ts                 | 147 ++++++
 tests/tickets-store.test.ts                   | 203 +++++++-
 5 files changed, 926 insertions(+), 165 deletions(-)
 create mode 100644 src/control-plane/extensions/tickets/provenance.ts

diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index ebaf9b342..26bd0c3b6 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -11,6 +11,10 @@ import {
 import { isRecord } from "../../../lib/guards.ts";
 import { openUrl } from "../../../lib/os.ts";
 import { display } from "../../../ui/display.ts";
+import {
+  findTicketRemoteLink,
+  projectRemoteLinkToCompatibilityFields,
+} from "../tickets/provenance.ts";
 import {
   createTicketsStore,
   type TicketComment,
@@ -3780,13 +3784,17 @@ async function syncTicketToLinearIssue(input: {
 
   const updated = await input.runtime.tickets.updateTicket({
     ticketId: ticket.ticketId,
-    externalSystem: "linear",
-    externalId: syncedIssue.data.id,
-    externalKey: syncedIssue.data.identifier,
-    externalUrl: syncedIssue.data.url,
-    externalProjectId: syncedIssue.data.projectId,
-    externalProjectName: syncedIssue.data.projectName,
-    externalTeamId: syncedIssue.data.teamId,
+    ...projectRemoteLinkToCompatibilityFields({
+      remote: {
+        provider: "linear",
+        remoteId: syncedIssue.data.id,
+        remoteKey: syncedIssue.data.identifier,
+        remoteUrl: syncedIssue.data.url,
+        projectId: syncedIssue.data.projectId,
+        projectName: syncedIssue.data.projectName,
+        teamId: syncedIssue.data.teamId,
+      },
+    }),
   });
   if (!updated.ok) {
     return { ok: false, error: updated.error };
@@ -3841,15 +3849,19 @@ async function resolveLinearTargetForTicketSync(input: {
     }
   | { readonly ok: false; readonly error: string }
 > {
+  const linearRemote = findTicketRemoteLink({
+    ticket: input.ticket,
+    provider: "linear",
+  });
   let projectId =
     input.explicitProjectId ??
     input.existingIssue?.projectId ??
-    input.ticket.externalProjectId ??
+    linearRemote?.projectId ??
     input.runtime.projectBinding.projectId;
   let teamId =
     input.explicitTeamId ??
     input.existingIssue?.teamId ??
-    input.ticket.externalTeamId ??
+    linearRemote?.teamId ??
     input.runtime.projectBinding.teamId;
 
   if (!(teamId || !projectId)) {
@@ -4743,13 +4755,17 @@ async function applyLinearIssueToExistingTicket(input: {
     ...(input.projection.dependsOn !== undefined
       ? { dependsOn: input.projection.dependsOn }
       : {}),
-    externalSystem: "linear",
-    externalId: input.issue.id,
-    externalKey: input.issue.identifier,
-    externalUrl: input.issue.url,
-    externalProjectId: input.issue.projectId,
-    externalProjectName: input.issue.projectName,
-    externalTeamId: input.issue.teamId,
+    ...projectRemoteLinkToCompatibilityFields({
+      remote: {
+        provider: "linear",
+        remoteId: input.issue.id,
+        remoteKey: input.issue.identifier,
+        remoteUrl: input.issue.url,
+        projectId: input.issue.projectId,
+        projectName: input.issue.projectName,
+        teamId: input.issue.teamId,
+      },
+    }),
   });
   if (!updated.ok) {
     return { ok: false, error: updated.error };
@@ -4817,13 +4833,17 @@ async function createTicketFromLinearIssueProjection(input: {
     ...(input.projection.dependsOn !== undefined
       ? { dependsOn: input.projection.dependsOn }
       : {}),
-    externalSystem: "linear",
-    externalId: input.issue.id,
-    externalKey: input.issue.identifier,
-    externalUrl: input.issue.url,
-    externalProjectId: input.issue.projectId,
-    externalProjectName: input.issue.projectName,
-    externalTeamId: input.issue.teamId,
+    ...projectRemoteLinkToCompatibilityFields({
+      remote: {
+        provider: "linear",
+        remoteId: input.issue.id,
+        remoteKey: input.issue.identifier,
+        remoteUrl: input.issue.url,
+        projectId: input.issue.projectId,
+        projectName: input.issue.projectName,
+        teamId: input.issue.teamId,
+      },
+    }),
   });
   if (!created.ok) {
     return created;
@@ -4880,14 +4900,18 @@ async function buildLinearDependencyIndex(input: {
   const byLinearId = new Map<string, string>();
   const byLinearIdentifier = new Map<string, string>();
   for (const ticket of tickets) {
-    if (ticket.externalSystem !== "linear") {
+    const linearRemote = findTicketRemoteLink({
+      ticket,
+      provider: "linear",
+    });
+    if (!linearRemote) {
       continue;
     }
-    if (ticket.externalId) {
-      byLinearId.set(ticket.externalId, ticket.ticketId);
+    if (linearRemote.remoteId) {
+      byLinearId.set(linearRemote.remoteId, ticket.ticketId);
     }
-    if (ticket.externalKey) {
-      byLinearIdentifier.set(ticket.externalKey, ticket.ticketId);
+    if (linearRemote.remoteKey) {
+      byLinearIdentifier.set(linearRemote.remoteKey, ticket.ticketId);
     }
   }
   return {
@@ -4908,12 +4932,16 @@ async function resolveLinkedLinearIssue(input: {
   | { readonly ok: true; readonly issue: LinearIssue | null }
   | { readonly ok: false; readonly error: string }
 > {
-  if (input.ticket.externalSystem !== "linear") {
+  const linearRemote = findTicketRemoteLink({
+    ticket: input.ticket,
+    provider: "linear",
+  });
+  if (!linearRemote) {
     return { ok: true, issue: null };
   }
-  if (input.ticket.externalId) {
+  if (linearRemote.remoteId) {
     const byId = await input.runtime.linear.getIssueById({
-      issueId: input.ticket.externalId,
+      issueId: linearRemote.remoteId,
     });
     if (!byId.ok) {
       return { ok: false, error: byId.error };
@@ -4922,9 +4950,9 @@ async function resolveLinkedLinearIssue(input: {
       return { ok: true, issue: byId.data };
     }
   }
-  if (input.ticket.externalKey) {
+  if (linearRemote.remoteKey) {
     const byKey = await input.runtime.linear.getIssueByIdentifier({
-      identifier: input.ticket.externalKey,
+      identifier: linearRemote.remoteKey,
     });
     if (!byKey.ok) {
       return { ok: false, error: byKey.error };
@@ -5029,8 +5057,12 @@ async function resolveLinearParentIssueId(input: {
   if (!parentTicket) {
     return { ok: true };
   }
-  if (parentTicket.externalSystem === "linear" && parentTicket.externalId) {
-    return { ok: true, value: parentTicket.externalId };
+  const linearRemote = findTicketRemoteLink({
+    ticket: parentTicket,
+    provider: "linear",
+  });
+  if (linearRemote?.remoteId) {
+    return { ok: true, value: linearRemote.remoteId };
   }
   return { ok: true };
 }
@@ -5058,15 +5090,19 @@ function isLinearLinkedTicket(input: {
   readonly ticket: TicketSummary;
   readonly issue: LinearIssue;
 }): boolean {
-  if (input.ticket.externalSystem !== "linear") {
+  const linearRemote = findTicketRemoteLink({
+    ticket: input.ticket,
+    provider: "linear",
+  });
+  if (!linearRemote) {
     return false;
   }
-  if (input.ticket.externalId && input.ticket.externalId === input.issue.id) {
+  if (linearRemote.remoteId && linearRemote.remoteId === input.issue.id) {
     return true;
   }
   if (
-    input.ticket.externalKey &&
-    input.ticket.externalKey === input.issue.identifier
+    linearRemote.remoteKey &&
+    linearRemote.remoteKey === input.issue.identifier
   ) {
     return true;
   }
diff --git a/src/control-plane/extensions/tickets/domain.ts b/src/control-plane/extensions/tickets/domain.ts
index 4e11cd67e..953b9daee 100644
--- a/src/control-plane/extensions/tickets/domain.ts
+++ b/src/control-plane/extensions/tickets/domain.ts
@@ -1,3 +1,7 @@
+import {
+  buildTicketProvenance,
+  projectRemoteLinkToCompatibilityFields,
+} from "./provenance.ts";
 import { sha256Hex } from "./util.ts";
 
 export type TicketStatus = "open" | "in_progress" | "blocked" | "done";
@@ -82,9 +86,32 @@ export type TicketRemoteLink = {
   readonly remoteId?: string;
   readonly remoteKey?: string;
   readonly remoteUrl?: string;
+  readonly profileId?: string;
   readonly projectId?: string;
   readonly projectName?: string;
   readonly teamId?: string;
+  readonly remoteCursor?: string;
+  readonly remoteUpdatedAt?: string;
+};
+
+export type TicketFieldAuthority =
+  | "local"
+  | "remote"
+  | "append_only"
+  | "derived"
+  | "review_required";
+
+export type TicketFieldAuthorityEntry = {
+  readonly field: string;
+  readonly authority: TicketFieldAuthority;
+};
+
+export type TicketFieldVersion = {
+  readonly field: string;
+  readonly source: "local" | "remote";
+  readonly provider?: string;
+  readonly recordedAt: string;
+  readonly value?: TicketMetadataValue;
 };
 
 export type TicketDocumentKind = "description" | "spec" | "notes";
@@ -120,6 +147,8 @@ export type NormalizedTicket = {
   readonly provenance: {
     readonly origin: TicketOrigin;
     readonly remotes: readonly TicketRemoteLink[];
+    readonly fieldAuthorities: readonly TicketFieldAuthorityEntry[];
+    readonly fieldVersions: readonly TicketFieldVersion[];
   };
   readonly documents: readonly TicketDocument[];
   readonly fieldStates: readonly TicketFieldState[];
@@ -134,14 +163,14 @@ export function createNormalizedTicket(input: {
   readonly syncCheckpoints?: readonly TicketSyncCheckpointCompatibility[];
   readonly conflicts?: readonly TicketSyncConflictCompatibility[];
 }): NormalizedTicket {
-  const sourceSystem = inferSourceSystem({ ticket: input.ticket });
   const documents = buildDocuments({ ticket: input.ticket });
-  const remotes = buildRemoteLinks({
-    ticket: input.ticket,
-    sourceSystem,
-  });
   const checkpoints = input.syncCheckpoints ?? [];
   const conflicts = input.conflicts ?? [];
+  const provenance = buildTicketProvenance({
+    ticket: input.ticket,
+    syncCheckpoints: checkpoints,
+    conflicts,
+  });
 
   return {
     identity: {
@@ -159,16 +188,12 @@ export function createNormalizedTicket(input: {
     blocks: [...input.ticket.blocks],
     ...(input.ticket.assignee ? { assignee: input.ticket.assignee } : {}),
     tags: [...input.ticket.tags],
-    provenance: {
-      origin: {
-        owner: input.ticket.owner,
-        source: input.ticket.source,
-        system: sourceSystem,
-      },
-      remotes,
-    },
+    provenance,
     documents,
-    fieldStates: buildFieldStates({ remotes, conflicts }),
+    fieldStates: buildFieldStates({
+      fieldAuthorities: provenance.fieldAuthorities,
+      conflicts,
+    }),
     sync: {
       checkpoints: [...checkpoints],
       conflicts: [...conflicts],
@@ -198,27 +223,9 @@ export function projectNormalizedTicketSummary(input: {
     ...(input.ticket.assignee ? { assignee: input.ticket.assignee } : {}),
     tags: [...input.ticket.tags],
     ...(primaryRemote
-      ? {
-          externalSystem: primaryRemote.provider,
-          ...(primaryRemote.remoteId
-            ? { externalId: primaryRemote.remoteId }
-            : {}),
-          ...(primaryRemote.remoteKey
-            ? { externalKey: primaryRemote.remoteKey }
-            : {}),
-          ...(primaryRemote.remoteUrl
-            ? { externalUrl: primaryRemote.remoteUrl }
-            : {}),
-          ...(primaryRemote.projectId
-            ? { externalProjectId: primaryRemote.projectId }
-            : {}),
-          ...(primaryRemote.projectName
-            ? { externalProjectName: primaryRemote.projectName }
-            : {}),
-          ...(primaryRemote.teamId
-            ? { externalTeamId: primaryRemote.teamId }
-            : {}),
-        }
+      ? projectRemoteLinkToCompatibilityFields({
+          remote: primaryRemote,
+        })
       : {}),
     ...(input.ticket.identity.projectId
       ? { projectId: input.ticket.identity.projectId }
@@ -229,21 +236,6 @@ export function projectNormalizedTicketSummary(input: {
   };
 }
 
-function inferSourceSystem(input: {
-  readonly ticket: TicketSummaryCompatibility;
-}): string {
-  if (input.ticket.externalSystem) {
-    return input.ticket.externalSystem;
-  }
-  if (input.ticket.source !== "hack") {
-    return input.ticket.source;
-  }
-  if (input.ticket.owner !== "hack") {
-    return input.ticket.owner;
-  }
-  return "hack";
-}
-
 function buildDocuments(input: {
   readonly ticket: TicketSummaryCompatibility;
 }): TicketDocument[] {
@@ -266,71 +258,21 @@ function buildDocuments(input: {
   ];
 }
 
-function buildRemoteLinks(input: {
-  readonly ticket: TicketSummaryCompatibility;
-  readonly sourceSystem: string;
-}): TicketRemoteLink[] {
-  if (
-    !(
-      input.ticket.externalSystem ||
-      input.ticket.externalId ||
-      input.ticket.externalKey ||
-      input.ticket.externalUrl ||
-      input.ticket.externalProjectId ||
-      input.ticket.externalProjectName ||
-      input.ticket.externalTeamId
-    )
-  ) {
-    return [];
-  }
-
-  return [
-    {
-      provider: input.ticket.externalSystem ?? input.sourceSystem,
-      ...(input.ticket.externalId ? { remoteId: input.ticket.externalId } : {}),
-      ...(input.ticket.externalKey
-        ? { remoteKey: input.ticket.externalKey }
-        : {}),
-      ...(input.ticket.externalUrl
-        ? { remoteUrl: input.ticket.externalUrl }
-        : {}),
-      ...(input.ticket.externalProjectId
-        ? { projectId: input.ticket.externalProjectId }
-        : {}),
-      ...(input.ticket.externalProjectName
-        ? { projectName: input.ticket.externalProjectName }
-        : {}),
-      ...(input.ticket.externalTeamId
-        ? { teamId: input.ticket.externalTeamId }
-        : {}),
-    },
-  ];
-}
-
 function buildFieldStates(input: {
-  readonly remotes: readonly TicketRemoteLink[];
+  readonly fieldAuthorities: readonly TicketFieldAuthorityEntry[];
   readonly conflicts: readonly TicketSyncConflictCompatibility[];
 }): TicketFieldState[] {
-  const defaultAuthority = input.remotes.length > 0 ? "remote" : "local";
-  const byField = new Map<string, TicketFieldState>();
-
-  for (const field of ["title", "status", "assignee", "description"]) {
-    byField.set(field, {
-      field,
-      authority: defaultAuthority,
-      conflictIds: [],
-    });
-  }
-
-  for (const conflict of input.conflicts) {
-    const current = byField.get(conflict.field);
-    const conflictIds = [...(current?.conflictIds ?? []), conflict.conflictId];
-    byField.set(conflict.field, {
-      field: conflict.field,
-      authority: conflict.authority ?? current?.authority ?? defaultAuthority,
-      conflictIds,
-    });
-  }
-
-  return [...byField.values()];
+  return input.fieldAuthorities
+    .filter((fieldAuthority) =>
+      ["title", "status", "assignee", "description"].includes(
+        fieldAuthority.field
+      )
+    )
+    .map((fieldAuthority) => ({
+      field: fieldAuthority.field,
+      authority: fieldAuthority.authority,
+      conflictIds: input.conflicts
+        .filter((conflict) => conflict.field === fieldAuthority.field)
+        .map((conflict) => conflict.conflictId),
+    }));
 }
diff --git a/src/control-plane/extensions/tickets/provenance.ts b/src/control-plane/extensions/tickets/provenance.ts
new file mode 100644
index 000000000..2407ab100
--- /dev/null
+++ b/src/control-plane/extensions/tickets/provenance.ts
@@ -0,0 +1,457 @@
+export type TicketMetadataValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly TicketMetadataValue[]
+  | { readonly [key: string]: TicketMetadataValue };
+
+export type TicketSyncCheckpointCompatibility = {
+  readonly checkpointId: string;
+  readonly ticketId: string;
+  readonly provider: string;
+  readonly profileId?: string;
+  readonly direction?: string;
+  readonly remoteCursor?: string;
+  readonly remoteUpdatedAt?: string;
+  readonly localUpdatedAt?: string;
+  readonly actor: string;
+  readonly createdAt: string;
+};
+
+export type TicketSyncConflictCompatibility = {
+  readonly conflictId: string;
+  readonly ticketId: string;
+  readonly provider: string;
+  readonly field: string;
+  readonly status: "open" | "resolved";
+  readonly authority?: string;
+  readonly summary?: string;
+  readonly localValue?: TicketMetadataValue;
+  readonly remoteValue?: TicketMetadataValue;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly resolution?: "accept_local" | "accept_remote" | "merged" | "ignore";
+  readonly resolutionSummary?: string;
+  readonly resolvedAt?: string;
+  readonly resolvedBy?: string;
+};
+
+export type TicketProvenanceCompatibility = {
+  readonly owner: string;
+  readonly source: string;
+  readonly updatedAt: string;
+  readonly title: string;
+  readonly status: string;
+  readonly body?: string;
+  readonly assignee?: string;
+  readonly externalSystem?: string;
+  readonly externalId?: string;
+  readonly externalKey?: string;
+  readonly externalUrl?: string;
+  readonly externalProjectId?: string;
+  readonly externalProjectName?: string;
+  readonly externalTeamId?: string;
+};
+
+export type TicketOrigin = {
+  readonly owner: string;
+  readonly source: string;
+  readonly system: string;
+};
+
+export type TicketRemoteLink = {
+  readonly provider: string;
+  readonly remoteId?: string;
+  readonly remoteKey?: string;
+  readonly remoteUrl?: string;
+  readonly profileId?: string;
+  readonly projectId?: string;
+  readonly projectName?: string;
+  readonly teamId?: string;
+  readonly remoteCursor?: string;
+  readonly remoteUpdatedAt?: string;
+};
+
+export type TicketFieldAuthority =
+  | "local"
+  | "remote"
+  | "append_only"
+  | "derived"
+  | "review_required";
+
+export type TicketFieldAuthorityEntry = {
+  readonly field: string;
+  readonly authority: TicketFieldAuthority;
+};
+
+export type TicketFieldVersion = {
+  readonly field: string;
+  readonly source: "local" | "remote";
+  readonly provider?: string;
+  readonly recordedAt: string;
+  readonly value?: TicketMetadataValue;
+};
+
+export function inferTicketSourceSystem(input: {
+  readonly ticket: Pick<
+    TicketProvenanceCompatibility,
+    "owner" | "source" | "externalSystem"
+  >;
+}): string {
+  if (input.ticket.externalSystem) {
+    return input.ticket.externalSystem;
+  }
+  if (input.ticket.source !== "hack") {
+    return input.ticket.source;
+  }
+  if (input.ticket.owner !== "hack") {
+    return input.ticket.owner;
+  }
+  return "hack";
+}
+
+export function buildTicketRemoteLinks(input: {
+  readonly ticket: Pick<
+    TicketProvenanceCompatibility,
+    | "owner"
+    | "source"
+    | "externalSystem"
+    | "externalId"
+    | "externalKey"
+    | "externalUrl"
+    | "externalProjectId"
+    | "externalProjectName"
+    | "externalTeamId"
+  >;
+  readonly syncCheckpoints?: readonly TicketSyncCheckpointCompatibility[];
+}): TicketRemoteLink[] {
+  const sourceSystem = inferTicketSourceSystem({
+    ticket: input.ticket,
+  });
+  const remotes: TicketRemoteLink[] = [];
+
+  if (ticketHasRemoteIdentity({ ticket: input.ticket })) {
+    remotes.push(
+      createPrimaryRemoteLink({
+        ticket: input.ticket,
+        sourceSystem,
+      })
+    );
+  }
+
+  for (const checkpoint of input.syncCheckpoints ?? []) {
+    const trackedIndex = remotes.findIndex((remote) =>
+      remoteMatchesCheckpoint({ remote, checkpoint })
+    );
+
+    if (trackedIndex >= 0) {
+      remotes[trackedIndex] = mergeCheckpointRemote({
+        remote: remotes[trackedIndex],
+        checkpoint,
+      });
+      continue;
+    }
+
+    remotes.push(createCheckpointRemoteLink({ checkpoint }));
+  }
+
+  return remotes;
+}
+
+function ticketHasRemoteIdentity(input: {
+  readonly ticket: Pick<
+    TicketProvenanceCompatibility,
+    | "externalSystem"
+    | "externalId"
+    | "externalKey"
+    | "externalUrl"
+    | "externalProjectId"
+    | "externalProjectName"
+    | "externalTeamId"
+  >;
+}): boolean {
+  return Boolean(
+    input.ticket.externalSystem ||
+      input.ticket.externalId ||
+      input.ticket.externalKey ||
+      input.ticket.externalUrl ||
+      input.ticket.externalProjectId ||
+      input.ticket.externalProjectName ||
+      input.ticket.externalTeamId
+  );
+}
+
+function createPrimaryRemoteLink(input: {
+  readonly ticket: Pick<
+    TicketProvenanceCompatibility,
+    | "externalSystem"
+    | "externalId"
+    | "externalKey"
+    | "externalUrl"
+    | "externalProjectId"
+    | "externalProjectName"
+    | "externalTeamId"
+  >;
+  readonly sourceSystem: string;
+}): TicketRemoteLink {
+  return {
+    provider: input.ticket.externalSystem ?? input.sourceSystem,
+    ...(input.ticket.externalId ? { remoteId: input.ticket.externalId } : {}),
+    ...(input.ticket.externalKey
+      ? { remoteKey: input.ticket.externalKey }
+      : {}),
+    ...(input.ticket.externalUrl
+      ? { remoteUrl: input.ticket.externalUrl }
+      : {}),
+    ...(input.ticket.externalProjectId
+      ? { projectId: input.ticket.externalProjectId }
+      : {}),
+    ...(input.ticket.externalProjectName
+      ? { projectName: input.ticket.externalProjectName }
+      : {}),
+    ...(input.ticket.externalTeamId
+      ? { teamId: input.ticket.externalTeamId }
+      : {}),
+  };
+}
+
+function remoteMatchesCheckpoint(input: {
+  readonly remote: TicketRemoteLink;
+  readonly checkpoint: TicketSyncCheckpointCompatibility;
+}): boolean {
+  return (
+    input.remote.provider === input.checkpoint.provider &&
+    (input.remote.profileId === input.checkpoint.profileId ||
+      input.remote.profileId === undefined ||
+      input.checkpoint.profileId === undefined)
+  );
+}
+
+function mergeCheckpointRemote(input: {
+  readonly remote: TicketRemoteLink;
+  readonly checkpoint: TicketSyncCheckpointCompatibility;
+}): TicketRemoteLink {
+  return {
+    ...input.remote,
+    ...(input.remote.profileId === undefined && input.checkpoint.profileId
+      ? { profileId: input.checkpoint.profileId }
+      : {}),
+    ...(input.checkpoint.remoteCursor
+      ? { remoteCursor: input.checkpoint.remoteCursor }
+      : {}),
+    ...(input.checkpoint.remoteUpdatedAt
+      ? { remoteUpdatedAt: input.checkpoint.remoteUpdatedAt }
+      : {}),
+  };
+}
+
+function createCheckpointRemoteLink(input: {
+  readonly checkpoint: TicketSyncCheckpointCompatibility;
+}): TicketRemoteLink {
+  return {
+    provider: input.checkpoint.provider,
+    ...(input.checkpoint.profileId
+      ? { profileId: input.checkpoint.profileId }
+      : {}),
+    ...(input.checkpoint.remoteCursor
+      ? { remoteCursor: input.checkpoint.remoteCursor }
+      : {}),
+    ...(input.checkpoint.remoteUpdatedAt
+      ? { remoteUpdatedAt: input.checkpoint.remoteUpdatedAt }
+      : {}),
+  };
+}
+
+export function buildTicketFieldAuthorities(input: {
+  readonly remotes: readonly TicketRemoteLink[];
+  readonly conflicts?: readonly TicketSyncConflictCompatibility[];
+}): TicketFieldAuthorityEntry[] {
+  const defaultAuthority = input.remotes.length > 0 ? "remote" : "local";
+  const byField = new Map<string, TicketFieldAuthorityEntry>();
+
+  for (const field of [
+    "title",
+    "status",
+    "assignee",
+    "description",
+    "project",
+  ]) {
+    byField.set(field, {
+      field,
+      authority: defaultAuthority,
+    });
+  }
+  byField.set("comment", {
+    field: "comment",
+    authority: "append_only",
+  });
+  byField.set("review_note", {
+    field: "review_note",
+    authority: "local",
+  });
+  byField.set("sync_checkpoint", {
+    field: "sync_checkpoint",
+    authority: "derived",
+  });
+  byField.set("sync_conflict", {
+    field: "sync_conflict",
+    authority: "derived",
+  });
+
+  for (const conflict of input.conflicts ?? []) {
+    const current = byField.get(conflict.field);
+    byField.set(conflict.field, {
+      field: conflict.field,
+      authority: conflict.authority ?? current?.authority ?? defaultAuthority,
+    });
+  }
+
+  return [...byField.values()];
+}
+
+export function buildTicketFieldVersions(input: {
+  readonly ticket: TicketProvenanceCompatibility;
+  readonly conflicts?: readonly TicketSyncConflictCompatibility[];
+}): TicketFieldVersion[] {
+  const versions: TicketFieldVersion[] = [
+    {
+      field: "title",
+      source: "local",
+      recordedAt: input.ticket.updatedAt,
+      value: input.ticket.title,
+    },
+    {
+      field: "status",
+      source: "local",
+      recordedAt: input.ticket.updatedAt,
+      value: input.ticket.status,
+    },
+    {
+      field: "description",
+      source: "local",
+      recordedAt: input.ticket.updatedAt,
+      ...(input.ticket.body ? { value: input.ticket.body } : {}),
+    },
+  ];
+
+  if (input.ticket.assignee) {
+    versions.push({
+      field: "assignee",
+      source: "local",
+      recordedAt: input.ticket.updatedAt,
+      value: input.ticket.assignee,
+    });
+  }
+
+  for (const conflict of input.conflicts ?? []) {
+    if (conflict.localValue !== undefined) {
+      versions.push({
+        field: conflict.field,
+        source: "local",
+        recordedAt: conflict.updatedAt,
+        value: conflict.localValue,
+      });
+    }
+    if (conflict.remoteValue !== undefined) {
+      versions.push({
+        field: conflict.field,
+        source: "remote",
+        provider: conflict.provider,
+        recordedAt: conflict.updatedAt,
+        value: conflict.remoteValue,
+      });
+    }
+  }
+
+  return versions;
+}
+
+export function buildTicketProvenance(input: {
+  readonly ticket: TicketProvenanceCompatibility;
+  readonly syncCheckpoints?: readonly TicketSyncCheckpointCompatibility[];
+  readonly conflicts?: readonly TicketSyncConflictCompatibility[];
+}): {
+  readonly origin: TicketOrigin;
+  readonly remotes: readonly TicketRemoteLink[];
+  readonly fieldAuthorities: readonly TicketFieldAuthorityEntry[];
+  readonly fieldVersions: readonly TicketFieldVersion[];
+} {
+  const system = inferTicketSourceSystem({
+    ticket: input.ticket,
+  });
+  const remotes = buildTicketRemoteLinks({
+    ticket: input.ticket,
+    syncCheckpoints: input.syncCheckpoints,
+  });
+
+  return {
+    origin: {
+      owner: input.ticket.owner,
+      source: input.ticket.source,
+      system,
+    },
+    remotes,
+    fieldAuthorities: buildTicketFieldAuthorities({
+      remotes,
+      conflicts: input.conflicts,
+    }),
+    fieldVersions: buildTicketFieldVersions({
+      ticket: input.ticket,
+      conflicts: input.conflicts,
+    }),
+  };
+}
+
+export function findTicketRemoteLink(input: {
+  readonly ticket: Pick<
+    TicketProvenanceCompatibility,
+    | "owner"
+    | "source"
+    | "updatedAt"
+    | "title"
+    | "status"
+    | "externalSystem"
+    | "externalId"
+    | "externalKey"
+    | "externalUrl"
+    | "externalProjectId"
+    | "externalProjectName"
+    | "externalTeamId"
+  >;
+  readonly provider: string;
+  readonly syncCheckpoints?: readonly TicketSyncCheckpointCompatibility[];
+}): TicketRemoteLink | null {
+  return (
+    buildTicketRemoteLinks({
+      ticket: input.ticket,
+      syncCheckpoints: input.syncCheckpoints,
+    }).find((remote) => remote.provider === input.provider) ?? null
+  );
+}
+
+export function projectRemoteLinkToCompatibilityFields(input: {
+  readonly remote: TicketRemoteLink;
+}): {
+  readonly externalSystem: string;
+  readonly externalId?: string;
+  readonly externalKey?: string;
+  readonly externalUrl?: string;
+  readonly externalProjectId?: string;
+  readonly externalProjectName?: string;
+  readonly externalTeamId?: string;
+} {
+  return {
+    externalSystem: input.remote.provider,
+    ...(input.remote.remoteId ? { externalId: input.remote.remoteId } : {}),
+    ...(input.remote.remoteKey ? { externalKey: input.remote.remoteKey } : {}),
+    ...(input.remote.remoteUrl ? { externalUrl: input.remote.remoteUrl } : {}),
+    ...(input.remote.projectId
+      ? { externalProjectId: input.remote.projectId }
+      : {}),
+    ...(input.remote.projectName
+      ? { externalProjectName: input.remote.projectName }
+      : {}),
+    ...(input.remote.teamId ? { externalTeamId: input.remote.teamId } : {}),
+  };
+}
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index 75eee414b..d39152f28 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -1310,6 +1310,153 @@ test("syncTicketToLinearIssue pushes missing local comments and records a checkp
   expect(updatedIssues[0]?.assigneeId).toBe("user-1");
 });
 
+test("syncTicketToLinearIssue reuses a linked Linear issue inferred from provenance metadata", async () => {
+  const updatedIssues: Record<string, unknown>[] = [];
+
+  const runtime = {
+    profileId: "default",
+    apiUrl: "https://api.linear.app/graphql",
+    projectBinding: {
+      teamId: "team-1",
+      additionalProjects: [],
+    },
+    assigneeMappings: [],
+    tickets: {
+      getTicket: async () => ({
+        ticketId: "T-00002",
+        title: "Synced from Linear",
+        body: "Keep using the existing Linear issue.",
+        status: "open" as const,
+        createdAt: "2026-03-05T10:00:00.000Z",
+        updatedAt: "2026-03-05T10:00:00.000Z",
+        dependsOn: [],
+        blocks: [],
+        owner: "hack",
+        source: "linear",
+        tags: [],
+        externalId: "issue-2",
+        externalKey: "ENG-222",
+        externalUrl: "https://linear.app/hack/issue/ENG-222",
+        externalProjectId: "proj-2",
+        externalTeamId: "team-1",
+      }),
+      updateTicket: async () => ({ ok: true as const }),
+      listTickets: async () => [],
+      getTicketDetail: async () => ({
+        ticket: null,
+        events: [],
+        comments: [],
+        reviewNotes: [],
+        syncCheckpoints: [],
+        conflicts: [],
+      }),
+      linkCommentExternalId: async () => ({ ok: true as const }),
+      recordSyncCheckpoint: async () => ({
+        ok: true as const,
+        checkpoint: {
+          checkpointId: "checkpoint-2",
+          ticketId: "T-00002",
+          provider: "linear",
+          direction: "hack_to_linear",
+          actor: "test",
+          createdAt: "2026-03-05T10:10:00.000Z",
+        },
+      }),
+      recordSyncConflict: async () => ({ ok: true as const, conflict: null }),
+    },
+    linear: {
+      getIssueById: async () => ({
+        ok: true as const,
+        data: {
+          id: "issue-2",
+          identifier: "ENG-222",
+          title: "Synced from Linear",
+          description: "Keep using the existing Linear issue.",
+          state: {
+            id: "state-1",
+            name: "Todo",
+            type: "unstarted" as const,
+          },
+          url: "https://linear.app/hack/issue/ENG-222",
+          teamId: "team-1",
+          projectId: "proj-2",
+          labels: [],
+        },
+      }),
+      getIssueByIdentifier: async () => ({ ok: true as const, data: null }),
+      updateIssue: async (input: Record<string, unknown>) => {
+        updatedIssues.push(input);
+        return {
+          ok: true as const,
+          data: {
+            id: "issue-2",
+            identifier: "ENG-222",
+            title: "Synced from Linear",
+            description: "Keep using the existing Linear issue.",
+            state: {
+              id: "state-1",
+              name: "Todo",
+              type: "unstarted" as const,
+            },
+            url: "https://linear.app/hack/issue/ENG-222",
+            teamId: "team-1",
+            projectId: "proj-2",
+            labels: [],
+          },
+        };
+      },
+      createIssue: async () => {
+        throw new Error("createIssue should not be called");
+      },
+      listTeamStates: async () => ({
+        ok: true as const,
+        data: [
+          {
+            id: "state-1",
+            name: "Todo",
+            type: "unstarted" as const,
+          },
+        ],
+      }),
+      listTeamLabels: async () => ({
+        ok: true as const,
+        data: [],
+      }),
+      listIssueComments: async () => ({
+        ok: true as const,
+        data: [],
+      }),
+      createComment: async () => {
+        throw new Error("createComment should not be called");
+      },
+      listTeamUsers: async () => ({
+        ok: true as const,
+        data: [],
+      }),
+      getProject: async () => ({ ok: true as const, data: null }),
+    },
+  };
+
+  const result = await __testOnly.syncTicketToLinearIssue({
+    runtime,
+    ticketId: "T-00002",
+    syncToggles: {
+      labels: false,
+      statuses: true,
+      dependencies: false,
+      projects: true,
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(result.operation).toBe("updated");
+  expect(updatedIssues).toHaveLength(1);
+});
+
 test("runProjectLinearAutosync syncs issue and project deliveries, then applies them", async () => {
   const appliedDeliveryIds: string[] = [];
   const issueSyncCalls: Array<{ issueIdentifier?: string; issueId?: string }> =
diff --git a/tests/tickets-store.test.ts b/tests/tickets-store.test.ts
index 5250b78c0..4ef4a6a63 100644
--- a/tests/tickets-store.test.ts
+++ b/tests/tickets-store.test.ts
@@ -13,6 +13,10 @@ import {
   createNormalizedTicket,
   projectNormalizedTicketSummary,
 } from "../src/control-plane/extensions/tickets/domain.ts";
+import {
+  buildTicketProvenance,
+  findTicketRemoteLink,
+} from "../src/control-plane/extensions/tickets/provenance.ts";
 import { createTicketsStore } from "../src/control-plane/extensions/tickets/store.ts";
 import { readControlPlaneConfig } from "../src/control-plane/sdk/config.ts";
 
@@ -231,7 +235,7 @@ test("tickets store materializes assignee, review notes, comments, checkpoints,
     sourceOperation: "local_command",
   });
   expect(events[0]?.idempotencyKey).toBe(events[0]?.eventId);
-}, 20_000);
+}, 30_000);
 
 test("tickets show json includes materialized sync metadata", async () => {
   const projectRoot = await createTempGitProject({
@@ -556,17 +560,24 @@ test("normalized ticket adapter preserves compatibility while exposing provenanc
     source: "linear",
     system: "linear",
   });
-  expect(normalized.provenance.remotes).toEqual([
-    expect.objectContaining({
-      provider: "linear",
-      remoteId: "lin_123",
-      remoteKey: "HACK-431",
-      remoteUrl: "https://linear.app/hack/issue/HACK-431",
-      projectId: "project-1",
-      projectName: "Hack App",
-      teamId: "team-1",
-    }),
-  ]);
+  expect(normalized.provenance.remotes).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        provider: "linear",
+        remoteId: "lin_123",
+        remoteKey: "HACK-431",
+        remoteUrl: "https://linear.app/hack/issue/HACK-431",
+        projectId: "project-1",
+        projectName: "Hack App",
+        teamId: "team-1",
+      }),
+      expect.objectContaining({
+        provider: "linear",
+        profileId: "default",
+        remoteCursor: "issue/lin_123#v2",
+      }),
+    ])
+  );
   expect(normalized.documents).toEqual([
     expect.objectContaining({
       kind: "description",
@@ -588,6 +599,174 @@ test("normalized ticket adapter preserves compatibility while exposing provenanc
   );
 });
 
+test("normalized ticket provenance captures multiple remotes, field authority, and field versions", () => {
+  const normalized = createNormalizedTicket({
+    ticket: {
+      ticketId: "T-00077",
+      title: "Normalize provenance",
+      body: "Track provenance explicitly.",
+      status: "open",
+      createdAt: "2026-03-13T09:00:00.000Z",
+      updatedAt: "2026-03-13T12:00:00.000Z",
+      dependsOn: [],
+      blocks: [],
+      owner: "hack",
+      source: "linear",
+      assignee: "alice@hack",
+      tags: ["normalization"],
+      externalSystem: "linear",
+      externalId: "lin-77",
+      externalKey: "HACK-77",
+      externalUrl: "https://linear.app/hack/issue/HACK-77",
+      externalProjectId: "proj-77",
+      externalProjectName: "Hack App",
+      externalTeamId: "team-77",
+      projectId: "hack-cli",
+      projectName: "hack-cli",
+    },
+    syncCheckpoints: [
+      {
+        checkpointId: "checkpoint-linear",
+        ticketId: "T-00077",
+        provider: "linear",
+        profileId: "default",
+        direction: "pull",
+        remoteCursor: "issue/lin-77#v3",
+        remoteUpdatedAt: "2026-03-13T11:59:00.000Z",
+        actor: "sync@app",
+        createdAt: "2026-03-13T12:00:00.000Z",
+      },
+      {
+        checkpointId: "checkpoint-github",
+        ticketId: "T-00077",
+        provider: "github",
+        profileId: "mirror",
+        direction: "push",
+        remoteCursor: "issue/gh-77#v1",
+        remoteUpdatedAt: "2026-03-13T11:45:00.000Z",
+        actor: "sync@app",
+        createdAt: "2026-03-13T12:00:00.000Z",
+      },
+    ],
+    conflicts: [
+      {
+        conflictId: "conflict-title",
+        ticketId: "T-00077",
+        provider: "linear",
+        field: "title",
+        status: "open",
+        authority: "review_required",
+        summary: "Title changed in both places.",
+        localValue: "Normalize provenance",
+        remoteValue: "Normalize explicit provenance",
+        createdAt: "2026-03-13T12:00:00.000Z",
+        updatedAt: "2026-03-13T12:00:00.000Z",
+      },
+    ],
+  });
+
+  expect(normalized.provenance.remotes).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        provider: "linear",
+        remoteId: "lin-77",
+        remoteKey: "HACK-77",
+      }),
+      expect.objectContaining({
+        provider: "github",
+        profileId: "mirror",
+        remoteCursor: "issue/gh-77#v1",
+      }),
+    ])
+  );
+  expect(normalized.provenance.fieldAuthorities).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        field: "title",
+        authority: "review_required",
+      }),
+      expect.objectContaining({
+        field: "comment",
+        authority: "append_only",
+      }),
+    ])
+  );
+  expect(normalized.provenance.fieldVersions).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        field: "title",
+        source: "local",
+        recordedAt: "2026-03-13T12:00:00.000Z",
+      }),
+      expect.objectContaining({
+        field: "title",
+        source: "remote",
+        provider: "linear",
+        value: "Normalize explicit provenance",
+      }),
+    ])
+  );
+});
+
+test("ticket provenance infers a remote provider from source metadata when externalSystem is absent", () => {
+  const ticket = {
+    ticketId: "T-00088",
+    title: "Infer remote provider",
+    body: "Link a remote without an explicit external system field.",
+    status: "open" as const,
+    createdAt: "2026-03-13T09:00:00.000Z",
+    updatedAt: "2026-03-13T12:00:00.000Z",
+    dependsOn: [],
+    blocks: [],
+    owner: "hack",
+    source: "linear",
+    tags: ["normalization"],
+    externalId: "lin-88",
+    externalKey: "HACK-88",
+    externalUrl: "https://linear.app/hack/issue/HACK-88",
+    externalProjectId: "proj-88",
+    externalProjectName: "Hack App",
+    externalTeamId: "team-88",
+  };
+
+  const provenance = buildTicketProvenance({
+    ticket,
+    syncCheckpoints: [
+      {
+        checkpointId: "checkpoint-linear",
+        ticketId: "T-00088",
+        provider: "linear",
+        direction: "pull",
+        remoteCursor: "issue/lin-88#v1",
+        remoteUpdatedAt: "2026-03-13T11:59:00.000Z",
+        actor: "sync@app",
+        createdAt: "2026-03-13T12:00:00.000Z",
+      },
+    ],
+  });
+
+  expect(findTicketRemoteLink({ ticket, provider: "linear" })).toEqual(
+    expect.objectContaining({
+      provider: "linear",
+      remoteId: "lin-88",
+      remoteKey: "HACK-88",
+      remoteUrl: "https://linear.app/hack/issue/HACK-88",
+    })
+  );
+  expect(provenance.fieldAuthorities).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        field: "title",
+        authority: "remote",
+      }),
+      expect.objectContaining({
+        field: "comment",
+        authority: "append_only",
+      }),
+    ])
+  );
+});
+
 async function createStore(opts: { readonly projectRoot: string }) {
   const configResult = await readControlPlaneConfig({
     projectDir: join(opts.projectRoot, ".hack"),

From 517031d46cf223cba2d839dca7295437fb8c0576 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 23:11:36 +0000
Subject: [PATCH 010/134] feat(tickets): make sync writes idempotent

---
 .../extensions/linear/commands.ts             |  56 ++++++
 src/control-plane/extensions/tickets/store.ts |  25 ++-
 tests/linear-commands.test.ts                 | 164 ++++++++++++++++++
 tests/tickets-store.test.ts                   |  50 ++++++
 4 files changed, 294 insertions(+), 1 deletion(-)

diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index 26bd0c3b6..313811047 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -3186,6 +3186,52 @@ function buildConflictDedupKey(input: {
   ].join("|");
 }
 
+function buildLinearCheckpointIdempotencyKey(input: {
+  readonly ticketId: string;
+  readonly profileId: string;
+  readonly direction: string;
+  readonly issue: LinearIssue;
+}): string {
+  const fingerprint = createHash("sha256")
+    .update(
+      JSON.stringify({
+        issueId: input.issue.id,
+        identifier: input.issue.identifier,
+        title: input.issue.title,
+        description: input.issue.description ?? null,
+        stateId: input.issue.state.id,
+        teamId: input.issue.teamId,
+        projectId: input.issue.projectId ?? null,
+        assigneeId: input.issue.assigneeId ?? null,
+        labels: input.issue.labels.map((label) => label.id).sort(),
+      })
+    )
+    .digest("hex")
+    .slice(0, 16);
+
+  return `linear:checkpoint:${input.ticketId}:${input.profileId}:${input.direction}:${fingerprint}`;
+}
+
+function buildLinearConflictIdempotencyKey(input: {
+  readonly ticketId: string;
+  readonly conflict: RecordedSyncConflict;
+}): string {
+  const fingerprint = createHash("sha256")
+    .update(
+      JSON.stringify({
+        field: input.conflict.field,
+        authority: input.conflict.authority ?? null,
+        summary: input.conflict.summary ?? null,
+        localValue: input.conflict.localValue ?? null,
+        remoteValue: input.conflict.remoteValue ?? null,
+      })
+    )
+    .digest("hex")
+    .slice(0, 16);
+
+  return `linear:conflict:${input.ticketId}:${fingerprint}`;
+}
+
 async function recordAuthoritativeConflicts(input: {
   readonly tickets: Pick<
     TicketSyncStore,
@@ -3228,6 +3274,10 @@ async function recordAuthoritativeConflicts(input: {
       field: conflict.field,
       authority: conflict.authority,
       summary: conflict.summary,
+      idempotencyKey: buildLinearConflictIdempotencyKey({
+        ticketId: input.ticketId,
+        conflict,
+      }),
       ...(conflict.localValue !== undefined
         ? { localValue: conflict.localValue }
         : {}),
@@ -3349,6 +3399,12 @@ async function recordLinearSyncCheckpoint(input: {
     direction: input.direction,
     remoteCursor: input.issue.identifier,
     localUpdatedAt: new Date().toISOString(),
+    idempotencyKey: buildLinearCheckpointIdempotencyKey({
+      ticketId: input.ticketId,
+      profileId: input.profileId,
+      direction: input.direction,
+      issue: input.issue,
+    }),
   });
   if (!checkpoint.ok) {
     return { ok: false, error: checkpoint.error };
diff --git a/src/control-plane/extensions/tickets/store.ts b/src/control-plane/extensions/tickets/store.ts
index ef2851212..e6afc3743 100644
--- a/src/control-plane/extensions/tickets/store.ts
+++ b/src/control-plane/extensions/tickets/store.ts
@@ -287,6 +287,7 @@ export function createTicketsStore(opts: {
     readonly remoteCursor?: string;
     readonly remoteUpdatedAt?: string;
     readonly localUpdatedAt?: string;
+    readonly idempotencyKey?: string;
     readonly actor?: string;
   }) => Promise<
     | { readonly ok: true; readonly checkpoint: TicketSyncCheckpoint }
@@ -300,6 +301,7 @@ export function createTicketsStore(opts: {
     readonly summary?: string;
     readonly localValue?: TicketMetadataValue;
     readonly remoteValue?: TicketMetadataValue;
+    readonly idempotencyKey?: string;
     readonly actor?: string;
   }) => Promise<
     | { readonly ok: true; readonly conflict: TicketSyncConflict }
@@ -635,7 +637,22 @@ export function createTicketsStore(opts: {
   }): Promise<
     { readonly ok: true } | { readonly ok: false; readonly error: string }
   > => {
-    const wrote = await git.appendEvents({ events: input.events });
+    const context = await loadStoreContext();
+    const seenIdempotencyKeys = new Set(
+      context.events.map((event) => event.idempotencyKey)
+    );
+    const pendingEvents = input.events.filter((event) => {
+      if (seenIdempotencyKeys.has(event.idempotencyKey)) {
+        return false;
+      }
+      seenIdempotencyKeys.add(event.idempotencyKey);
+      return true;
+    });
+    if (pendingEvents.length === 0) {
+      return { ok: true };
+    }
+
+    const wrote = await git.appendEvents({ events: pendingEvents });
     if (!wrote.ok) {
       return wrote;
     }
@@ -1045,6 +1062,9 @@ export function createTicketsStore(opts: {
           ...(remoteUpdatedAt ? { remoteUpdatedAt } : {}),
           ...(localUpdatedAt ? { localUpdatedAt } : {}),
         },
+        ...(input.idempotencyKey
+          ? { idempotencyKey: input.idempotencyKey }
+          : {}),
         actor: input.actor,
       });
 
@@ -1112,6 +1132,9 @@ export function createTicketsStore(opts: {
             ? { remoteValue: input.remoteValue }
             : {}),
         },
+        ...(input.idempotencyKey
+          ? { idempotencyKey: input.idempotencyKey }
+          : {}),
         actor: input.actor,
       });
 
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index d39152f28..60cd4fab1 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -1457,6 +1457,170 @@ test("syncTicketToLinearIssue reuses a linked Linear issue inferred from provena
   expect(updatedIssues).toHaveLength(1);
 });
 
+test("syncTicketToLinearIssue records a deterministic checkpoint idempotency key", async () => {
+  const checkpointInputs: Record<string, unknown>[] = [];
+
+  const runtime = {
+    profileId: "default",
+    apiUrl: "https://api.linear.app/graphql",
+    projectBinding: {
+      teamId: "team-1",
+      additionalProjects: [],
+    },
+    assigneeMappings: [],
+    tickets: {
+      getTicket: async () => ({
+        ticketId: "T-00003",
+        title: "Deterministic checkpoint",
+        body: "Keep checkpoint writes idempotent.",
+        status: "open" as const,
+        createdAt: "2026-03-05T10:00:00.000Z",
+        updatedAt: "2026-03-05T10:00:00.000Z",
+        dependsOn: [],
+        blocks: [],
+        owner: "hack",
+        source: "hack",
+        assignee: "alice@example.com",
+        tags: [],
+        externalSystem: "linear",
+        externalId: "issue-3",
+        externalKey: "ENG-333",
+        externalTeamId: "team-1",
+      }),
+      updateTicket: async () => ({ ok: true as const }),
+      listTickets: async () => [],
+      getTicketDetail: async () => ({
+        ticket: null,
+        events: [],
+        comments: [],
+        reviewNotes: [],
+        syncCheckpoints: [],
+        conflicts: [],
+      }),
+      linkCommentExternalId: async () => ({ ok: true as const }),
+      recordSyncCheckpoint: async (input: Record<string, unknown>) => {
+        checkpointInputs.push(input);
+        return {
+          ok: true as const,
+          checkpoint: {
+            checkpointId: "checkpoint-3",
+            ticketId: "T-00003",
+            provider: "linear",
+            direction: input.direction,
+            actor: "test",
+            createdAt: "2026-03-05T10:10:00.000Z",
+          },
+        };
+      },
+      recordSyncConflict: async () => ({ ok: true as const, conflict: null }),
+    },
+    linear: {
+      getIssueById: async () => ({
+        ok: true as const,
+        data: {
+          id: "issue-3",
+          identifier: "ENG-333",
+          title: "Deterministic checkpoint",
+          description: "Keep checkpoint writes idempotent.",
+          state: {
+            id: "state-1",
+            name: "Todo",
+            type: "unstarted" as const,
+          },
+          teamId: "team-1",
+          assigneeId: "user-1",
+          labels: [],
+        },
+      }),
+      updateIssue: async () => ({
+        ok: true as const,
+        data: {
+          id: "issue-3",
+          identifier: "ENG-333",
+          title: "Deterministic checkpoint",
+          description: "Keep checkpoint writes idempotent.",
+          state: {
+            id: "state-1",
+            name: "Todo",
+            type: "unstarted" as const,
+          },
+          teamId: "team-1",
+          assigneeId: "user-1",
+          labels: [],
+        },
+      }),
+      createIssue: async () => {
+        throw new Error("createIssue should not be called");
+      },
+      listTeamStates: async () => ({
+        ok: true as const,
+        data: [
+          {
+            id: "state-1",
+            name: "Todo",
+            type: "unstarted" as const,
+          },
+        ],
+      }),
+      listTeamLabels: async () => ({
+        ok: true as const,
+        data: [],
+      }),
+      listIssueComments: async () => ({
+        ok: true as const,
+        data: [],
+      }),
+      createComment: async () => {
+        throw new Error("createComment should not be called");
+      },
+      listTeamUsers: async () => ({
+        ok: true as const,
+        data: [
+          {
+            id: "user-1",
+            email: "alice@example.com",
+            displayName: "Alice",
+          },
+        ],
+      }),
+      getIssueByIdentifier: async () => ({ ok: true as const, data: null }),
+      getProject: async () => ({ ok: true as const, data: null }),
+    },
+  };
+
+  const first = await __testOnly.syncTicketToLinearIssue({
+    runtime,
+    ticketId: "T-00003",
+    syncToggles: {
+      labels: false,
+      statuses: true,
+      dependencies: false,
+      projects: true,
+    },
+  });
+  expect(first.ok).toBe(true);
+
+  const second = await __testOnly.syncTicketToLinearIssue({
+    runtime,
+    ticketId: "T-00003",
+    syncToggles: {
+      labels: false,
+      statuses: true,
+      dependencies: false,
+      projects: true,
+    },
+  });
+  expect(second.ok).toBe(true);
+
+  expect(checkpointInputs).toHaveLength(2);
+  expect(checkpointInputs[0]?.idempotencyKey).toBe(
+    checkpointInputs[1]?.idempotencyKey
+  );
+  expect(checkpointInputs[0]?.idempotencyKey).toContain(
+    "linear:checkpoint:T-00003"
+  );
+});
+
 test("runProjectLinearAutosync syncs issue and project deliveries, then applies them", async () => {
   const appliedDeliveryIds: string[] = [];
   const issueSyncCalls: Array<{ issueIdentifier?: string; issueId?: string }> =
diff --git a/tests/tickets-store.test.ts b/tests/tickets-store.test.ts
index 4ef4a6a63..becf0d088 100644
--- a/tests/tickets-store.test.ts
+++ b/tests/tickets-store.test.ts
@@ -450,6 +450,56 @@ test("tickets store writes normalized journal envelope metadata and ignores dupl
   });
 }, 20_000);
 
+test("tickets store ignores duplicate sync checkpoints with the same idempotency key", async () => {
+  const projectRoot = await createTempGitProject({
+    prefix: "hack-cli-tickets-checkpoint-idempotency-",
+  });
+  const store = await createStore({ projectRoot });
+
+  const created = await store.createTicket({
+    title: "Checkpoint idempotency",
+    owner: "hack",
+    source: "linear",
+    actor: "creator@hack",
+  });
+  expect(created.ok).toBe(true);
+  if (!created.ok) {
+    throw new Error(created.error);
+  }
+
+  const first = await store.recordSyncCheckpoint({
+    ticketId: created.ticket.ticketId,
+    provider: "linear",
+    profileId: "default",
+    direction: "hack_to_linear",
+    remoteCursor: "ENG-321",
+    idempotencyKey: "linear:checkpoint:T-00001:ENG-321",
+    actor: "sync@app",
+  });
+  expect(first.ok).toBe(true);
+
+  const second = await store.recordSyncCheckpoint({
+    ticketId: created.ticket.ticketId,
+    provider: "linear",
+    profileId: "default",
+    direction: "hack_to_linear",
+    remoteCursor: "ENG-321",
+    idempotencyKey: "linear:checkpoint:T-00001:ENG-321",
+    actor: "sync@app",
+  });
+  expect(second.ok).toBe(true);
+
+  const detail = await store.getTicketDetail({
+    ticketId: created.ticket.ticketId,
+  });
+  expect(detail.syncCheckpoints).toHaveLength(1);
+  expect(
+    detail.events.filter(
+      (event) => event.type === "ticket.sync_checkpoint_recorded"
+    )
+  ).toHaveLength(1);
+});
+
 test("tickets store persists a sqlite projection and rebuilds it when deleted", async () => {
   const projectRoot = await createTempGitProject({
     prefix: "hack-cli-tickets-projection-",

From d166be12e8c5994bdf13bd319160776cb23ceb39 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 23:32:28 +0000
Subject: [PATCH 011/134] feat(tickets): add document-backed ticket content

---
 .../extensions/tickets/commands.ts            | 168 ++++++++++++
 .../extensions/tickets/documents.ts           |  97 +++++++
 .../extensions/tickets/domain.ts              |  41 ++-
 .../extensions/tickets/sqlite-projection.ts   |  29 ++
 src/control-plane/extensions/tickets/store.ts | 230 ++++++++++++++--
 tests/tickets-extension.test.ts               | 252 ++++++++++++++++++
 tests/tickets-store.test.ts                   |  67 +++++
 7 files changed, 845 insertions(+), 39 deletions(-)
 create mode 100644 src/control-plane/extensions/tickets/documents.ts

diff --git a/src/control-plane/extensions/tickets/commands.ts b/src/control-plane/extensions/tickets/commands.ts
index 673e0154c..82192f283 100644
--- a/src/control-plane/extensions/tickets/commands.ts
+++ b/src/control-plane/extensions/tickets/commands.ts
@@ -11,6 +11,12 @@ import {
   type TicketsAgentDocUpdateResult,
   upsertTicketsAgentDocs,
 } from "./agent-docs.ts";
+import {
+  isTicketDocumentKind,
+  isTicketDocumentRole,
+  type TicketDocumentKind,
+  type TicketDocumentRole,
+} from "./documents.ts";
 import {
   checkTicketsRepoState,
   ensureTicketsGitignore,
@@ -686,6 +692,91 @@ export const TICKETS_COMMANDS: readonly ExtensionCommand[] = [
       return 0;
     },
   },
+  {
+    name: "document",
+    summary: "Append an immutable ticket document",
+    scope: "project",
+    handler: async ({ ctx, args }) => {
+      if (!ctx.project) {
+        ctx.logger.error({ message: "No project found. Run inside a repo." });
+        return 1;
+      }
+
+      const parsed = parseTicketsArgs({ args });
+      if (!parsed.ok) {
+        ctx.logger.error({ message: parsed.error });
+        return 1;
+      }
+
+      const ticketId = (parsed.value.rest[0] ?? "").trim();
+      if (!ticketId) {
+        ctx.logger.error({
+          message:
+            'Usage: hack x tickets document <ticket-id> --kind <description|spec|notes> [--role <description|spec|notes|handoff>] [--body "..."] [--body-file <path>] [--body-stdin] [--json]',
+        });
+        return 1;
+      }
+      if (!parsed.value.kind) {
+        ctx.logger.error({
+          message:
+            "Document kind is required. Use --kind <description|spec|notes>.",
+        });
+        return 1;
+      }
+
+      const body = await resolveTicketBody({
+        body: parsed.value.body,
+        bodyFile: parsed.value.bodyFile,
+        bodyStdin: parsed.value.bodyStdin,
+      });
+      if (!body) {
+        ctx.logger.error({
+          message:
+            "Document body is required. Use --body, --body-file, or --body-stdin.",
+        });
+        return 1;
+      }
+
+      await maybeEnsureTicketsSetup({ ctx, json: parsed.value.json });
+
+      const store = createTicketsStore({
+        projectRoot: ctx.project.projectRoot,
+        projectId: ctx.projectId,
+        projectName: ctx.projectName,
+        controlPlaneConfig: ctx.controlPlaneConfig,
+        logger: ctx.logger,
+      });
+
+      const appended = await store.appendDocument({
+        ticketId,
+        kind: parsed.value.kind,
+        ...(parsed.value.role ? { role: parsed.value.role } : {}),
+        content: body,
+        actor: parsed.value.actor,
+      });
+      if (!appended.ok) {
+        ctx.logger.error({ message: appended.error });
+        return 1;
+      }
+
+      if (parsed.value.json) {
+        process.stdout.write(
+          `${JSON.stringify({ document: appended.document }, null, 2)}\n`
+        );
+        return 0;
+      }
+
+      await display.panel({
+        title: "Ticket document",
+        tone: "success",
+        lines: [
+          `${ticketId} ${appended.document.role} document appended`,
+          appended.document.content,
+        ],
+      });
+      return 0;
+    },
+  },
   {
     name: "list",
     summary: "List tickets",
@@ -833,6 +924,7 @@ export const TICKETS_COMMANDS: readonly ExtensionCommand[] = [
           `${JSON.stringify(
             {
               ticket,
+              documents: detail.documents,
               comments: detail.comments,
               reviewNotes: detail.reviewNotes,
               syncCheckpoints: detail.syncCheckpoints,
@@ -879,6 +971,18 @@ export const TICKETS_COMMANDS: readonly ExtensionCommand[] = [
         });
       }
 
+      if (detail.documents.length > 0) {
+        await display.table({
+          columns: ["document_id", "kind", "role", "updated_at"],
+          rows: detail.documents.map((document) => [
+            document.documentId,
+            document.kind,
+            document.role,
+            document.updatedAt,
+          ]),
+        });
+      }
+
       if (detail.comments.length > 0) {
         await display.table({
           columns: ["comment_id", "source", "actor", "created_at", "body"],
@@ -1153,6 +1257,8 @@ type TicketsArgs = {
   readonly body?: string;
   readonly bodyFile?: string;
   readonly bodyStdin: boolean;
+  readonly kind?: TicketDocumentKind;
+  readonly role?: TicketDocumentRole;
   readonly dependsOn: readonly string[];
   readonly blocks: readonly string[];
   readonly clearDependsOn: boolean;
@@ -1210,6 +1316,8 @@ function parseTicketsArgs(opts: {
   let body: string | undefined;
   let bodyFile: string | undefined;
   let bodyStdin = false;
+  let kind: TicketDocumentKind | undefined;
+  let role: TicketDocumentRole | undefined;
   const dependsOn: string[] = [];
   const blocks: string[] = [];
   let clearDependsOn = false;
@@ -1303,6 +1411,64 @@ function parseTicketsArgs(opts: {
       continue;
     }
 
+    if (token.startsWith("--kind=")) {
+      const value = token.slice("--kind=".length);
+      if (!isTicketDocumentKind(value)) {
+        return {
+          ok: false,
+          error: "Invalid --kind value. Expected description|spec|notes.",
+        };
+      }
+      kind = value;
+      continue;
+    }
+
+    if (token === "--kind") {
+      const value = takeValue(token, opts.args[i + 1]);
+      if (!value) {
+        return { ok: false, error: "--kind requires a value." };
+      }
+      if (!isTicketDocumentKind(value)) {
+        return {
+          ok: false,
+          error: "Invalid --kind value. Expected description|spec|notes.",
+        };
+      }
+      kind = value;
+      i += 1;
+      continue;
+    }
+
+    if (token.startsWith("--role=")) {
+      const value = token.slice("--role=".length);
+      if (!isTicketDocumentRole(value)) {
+        return {
+          ok: false,
+          error:
+            "Invalid --role value. Expected description|spec|notes|handoff.",
+        };
+      }
+      role = value;
+      continue;
+    }
+
+    if (token === "--role") {
+      const value = takeValue(token, opts.args[i + 1]);
+      if (!value) {
+        return { ok: false, error: "--role requires a value." };
+      }
+      if (!isTicketDocumentRole(value)) {
+        return {
+          ok: false,
+          error:
+            "Invalid --role value. Expected description|spec|notes|handoff.",
+        };
+      }
+      role = value;
+      i += 1;
+      continue;
+    }
+
     if (token === "--clear-depends-on") {
       clearDependsOn = true;
       continue;
@@ -1540,6 +1706,8 @@ function parseTicketsArgs(opts: {
       ...(body ? { body } : {}),
       ...(bodyFile ? { bodyFile } : {}),
       bodyStdin,
+      ...(kind ? { kind } : {}),
+      ...(role ? { role } : {}),
       dependsOn,
       blocks,
       clearDependsOn,
diff --git a/src/control-plane/extensions/tickets/documents.ts b/src/control-plane/extensions/tickets/documents.ts
new file mode 100644
index 000000000..f43ee8300
--- /dev/null
+++ b/src/control-plane/extensions/tickets/documents.ts
@@ -0,0 +1,97 @@
+import { sha256Hex } from "./util.ts";
+
+export type TicketDocumentKind = "description" | "spec" | "notes";
+export type TicketDocumentRole = TicketDocumentKind | "handoff";
+
+export type TicketDocument = {
+  readonly documentId: string;
+  readonly ticketId: string;
+  readonly kind: TicketDocumentKind;
+  readonly role: TicketDocumentRole;
+  readonly content: string;
+  readonly contentSha256: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+export function isTicketDocumentKind(
+  value: string
+): value is TicketDocumentKind {
+  return ["description", "spec", "notes"].includes(value);
+}
+
+export function isTicketDocumentRole(
+  value: string
+): value is TicketDocumentRole {
+  return ["description", "spec", "notes", "handoff"].includes(value);
+}
+
+export function resolveTicketDocumentRole(input: {
+  readonly kind: TicketDocumentKind;
+  readonly role?: TicketDocumentRole;
+}): TicketDocumentRole {
+  return input.role ?? input.kind;
+}
+
+export function buildTicketDocument(input: {
+  readonly documentId: string;
+  readonly ticketId: string;
+  readonly kind: TicketDocumentKind;
+  readonly role?: TicketDocumentRole;
+  readonly content: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}): TicketDocument {
+  return {
+    documentId: input.documentId,
+    ticketId: input.ticketId,
+    kind: input.kind,
+    role: resolveTicketDocumentRole({
+      kind: input.kind,
+      role: input.role,
+    }),
+    content: input.content,
+    contentSha256: sha256Hex({ value: input.content }),
+    createdAt: input.createdAt,
+    updatedAt: input.updatedAt,
+  };
+}
+
+export function buildLegacyDescriptionDocument(input: {
+  readonly eventId: string;
+  readonly ticketId: string;
+  readonly content: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}): TicketDocument {
+  return buildTicketDocument({
+    documentId: `${input.ticketId}:description:${input.eventId}`,
+    ticketId: input.ticketId,
+    kind: "description",
+    content: input.content,
+    createdAt: input.createdAt,
+    updatedAt: input.updatedAt,
+  });
+}
+
+export function getActiveTicketDescription(input: {
+  readonly documents: readonly TicketDocument[];
+}): TicketDocument | undefined {
+  for (let index = input.documents.length - 1; index >= 0; index -= 1) {
+    const document = input.documents[index];
+    if (document?.role === "description") {
+      return document;
+    }
+  }
+  return undefined;
+}
+
+export function projectTicketBodyFromDocuments(input: {
+  readonly documents: readonly TicketDocument[];
+  readonly fallbackBody?: string;
+}): string | undefined {
+  return (
+    getActiveTicketDescription({ documents: input.documents })?.content ??
+    input.fallbackBody
+  );
+}
diff --git a/src/control-plane/extensions/tickets/domain.ts b/src/control-plane/extensions/tickets/domain.ts
index 953b9daee..b2af16d47 100644
--- a/src/control-plane/extensions/tickets/domain.ts
+++ b/src/control-plane/extensions/tickets/domain.ts
@@ -1,8 +1,8 @@
+import { buildLegacyDescriptionDocument } from "./documents.ts";
 import {
   buildTicketProvenance,
   projectRemoteLinkToCompatibilityFields,
 } from "./provenance.ts";
-import { sha256Hex } from "./util.ts";
 
 export type TicketStatus = "open" | "in_progress" | "blocked" | "done";
 
@@ -114,19 +114,11 @@ export type TicketFieldVersion = {
   readonly value?: TicketMetadataValue;
 };
 
-export type TicketDocumentKind = "description" | "spec" | "notes";
-export type TicketDocumentRole = TicketDocumentKind | "handoff";
-
-export type TicketDocument = {
-  readonly documentId: string;
-  readonly ticketId: string;
-  readonly kind: TicketDocumentKind;
-  readonly role: TicketDocumentRole;
-  readonly content: string;
-  readonly contentSha256: string;
-  readonly createdAt: string;
-  readonly updatedAt: string;
-};
+export type {
+  TicketDocument,
+  TicketDocumentKind,
+  TicketDocumentRole,
+} from "./documents.ts";
 
 export type TicketFieldState = {
   readonly field: string;
@@ -162,8 +154,12 @@ export function createNormalizedTicket(input: {
   readonly ticket: TicketSummaryCompatibility;
   readonly syncCheckpoints?: readonly TicketSyncCheckpointCompatibility[];
   readonly conflicts?: readonly TicketSyncConflictCompatibility[];
+  readonly documents?: readonly TicketDocument[];
 }): NormalizedTicket {
-  const documents = buildDocuments({ ticket: input.ticket });
+  const documents = buildDocuments({
+    ticket: input.ticket,
+    documents: input.documents,
+  });
   const checkpoints = input.syncCheckpoints ?? [];
   const conflicts = input.conflicts ?? [];
   const provenance = buildTicketProvenance({
@@ -238,23 +234,22 @@ export function projectNormalizedTicketSummary(input: {
 
 function buildDocuments(input: {
   readonly ticket: TicketSummaryCompatibility;
+  readonly documents?: readonly TicketDocument[];
 }): TicketDocument[] {
+  if (input.documents && input.documents.length > 0) {
+    return [...input.documents];
+  }
   if (!input.ticket.body) {
     return [];
   }
-
-  const contentSha256 = sha256Hex({ value: input.ticket.body });
   return [
-    {
-      documentId: `${input.ticket.ticketId}:description:${contentSha256.slice(0, 12)}`,
+    buildLegacyDescriptionDocument({
+      eventId: "compatibility-summary",
       ticketId: input.ticket.ticketId,
-      kind: "description",
-      role: "description",
       content: input.ticket.body,
-      contentSha256,
       createdAt: input.ticket.createdAt,
       updatedAt: input.ticket.updatedAt,
-    },
+    }),
   ];
 }
 
diff --git a/src/control-plane/extensions/tickets/sqlite-projection.ts b/src/control-plane/extensions/tickets/sqlite-projection.ts
index 141299da2..6e9ff6fa7 100644
--- a/src/control-plane/extensions/tickets/sqlite-projection.ts
+++ b/src/control-plane/extensions/tickets/sqlite-projection.ts
@@ -2,6 +2,7 @@ import { Database } from "bun:sqlite";
 import { mkdir, readdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
+import type { TicketDocument } from "./documents.ts";
 import type {
   TicketComment,
   TicketEvent,
@@ -105,6 +106,9 @@ export function createTicketsSqliteProjection(opts: {
       const insertComment = db.query(
         "INSERT INTO ticket_comments (comment_id, ticket_id, json_value) VALUES (?, ?, ?)"
       );
+      const insertDocument = db.query(
+        "INSERT INTO ticket_documents (document_id, ticket_id, json_value) VALUES (?, ?, ?)"
+      );
       const insertReviewNote = db.query(
         "INSERT INTO ticket_review_notes (note_id, ticket_id, json_value) VALUES (?, ?, ?)"
       );
@@ -123,6 +127,7 @@ export function createTicketsSqliteProjection(opts: {
           DELETE FROM tickets;
           DELETE FROM journal_events;
           DELETE FROM ticket_comments;
+          DELETE FROM ticket_documents;
           DELETE FROM ticket_review_notes;
           DELETE FROM ticket_sync_checkpoints;
           DELETE FROM ticket_sync_conflicts;
@@ -164,6 +169,17 @@ export function createTicketsSqliteProjection(opts: {
           },
         });
 
+        writeMapEntries({
+          map: input.snapshot.documentsByTicket,
+          write: (document: TicketDocument) => {
+            insertDocument.run(
+              document.documentId,
+              document.ticketId,
+              JSON.stringify(document)
+            );
+          },
+        });
+
         writeMapEntries({
           map: input.snapshot.reviewNotesByTicket,
           write: (reviewNote: TicketReviewNote) => {
@@ -244,6 +260,10 @@ export function createTicketsSqliteProjection(opts: {
         db,
         table: "ticket_comments",
       });
+      const documentsByTicket = readRowsByTicket<TicketDocument>({
+        db,
+        table: "ticket_documents",
+      });
       const reviewNotesByTicket = readRowsByTicket<TicketReviewNote>({
         db,
         table: "ticket_review_notes",
@@ -260,6 +280,7 @@ export function createTicketsSqliteProjection(opts: {
       return {
         tickets,
         eventsByTicket,
+        documentsByTicket,
         commentsByTicket,
         reviewNotesByTicket,
         syncCheckpointsByTicket,
@@ -305,6 +326,11 @@ function initializeProjectionSchema(input: { readonly db: Database }): void {
       ticket_id TEXT NOT NULL,
       json_value TEXT NOT NULL
     );
+    CREATE TABLE IF NOT EXISTS ticket_documents (
+      document_id TEXT PRIMARY KEY,
+      ticket_id TEXT NOT NULL,
+      json_value TEXT NOT NULL
+    );
     CREATE TABLE IF NOT EXISTS ticket_review_notes (
       note_id TEXT PRIMARY KEY,
       ticket_id TEXT NOT NULL,
@@ -324,6 +350,8 @@ function initializeProjectionSchema(input: { readonly db: Database }): void {
       ON journal_events (ticket_id, ts, order_key);
     CREATE INDEX IF NOT EXISTS ticket_comments_ticket_id_idx
       ON ticket_comments (ticket_id);
+    CREATE INDEX IF NOT EXISTS ticket_documents_ticket_id_idx
+      ON ticket_documents (ticket_id);
     CREATE INDEX IF NOT EXISTS ticket_review_notes_ticket_id_idx
       ON ticket_review_notes (ticket_id);
     CREATE INDEX IF NOT EXISTS ticket_sync_checkpoints_ticket_id_idx
@@ -367,6 +395,7 @@ function readRowsByTicket<T>(input: {
   readonly db: Database;
   readonly table:
     | "ticket_comments"
+    | "ticket_documents"
     | "ticket_review_notes"
     | "ticket_sync_checkpoints"
     | "ticket_sync_conflicts";
diff --git a/src/control-plane/extensions/tickets/store.ts b/src/control-plane/extensions/tickets/store.ts
index e6afc3743..5df5be9f3 100644
--- a/src/control-plane/extensions/tickets/store.ts
+++ b/src/control-plane/extensions/tickets/store.ts
@@ -5,6 +5,16 @@ import { resolve } from "node:path";
 
 import { isRecord } from "../../../lib/guards.ts";
 import type { ControlPlaneConfig } from "../../sdk/config.ts";
+import {
+  buildLegacyDescriptionDocument,
+  buildTicketDocument,
+  getActiveTicketDescription,
+  isTicketDocumentKind,
+  isTicketDocumentRole,
+  type TicketDocument,
+  type TicketDocumentKind,
+  type TicketDocumentRole,
+} from "./documents.ts";
 import {
   createNormalizedTicket,
   projectNormalizedTicketSummary,
@@ -134,6 +144,7 @@ export type TicketEvent = {
 export type TicketStoreSnapshot = {
   readonly tickets: readonly TicketSummary[];
   readonly eventsByTicket: ReadonlyMap<string, readonly TicketEvent[]>;
+  readonly documentsByTicket: ReadonlyMap<string, readonly TicketDocument[]>;
   readonly commentsByTicket: ReadonlyMap<string, readonly TicketComment[]>;
   readonly reviewNotesByTicket: ReadonlyMap<
     string,
@@ -165,6 +176,7 @@ type SyncResult =
 
 type MaterializedTicketState = {
   readonly tickets: Map<string, TicketSummary>;
+  readonly documentsByTicket: Map<string, TicketDocument[]>;
   readonly commentsByTicket: Map<string, TicketComment[]>;
   readonly reviewNotesByTicket: Map<string, TicketReviewNote[]>;
   readonly syncCheckpointsByTicket: Map<string, TicketSyncCheckpoint[]>;
@@ -245,6 +257,7 @@ export function createTicketsStore(opts: {
   readonly getTicketDetail: (input: { readonly ticketId: string }) => Promise<{
     readonly ticket: TicketSummary | null;
     readonly events: readonly TicketEvent[];
+    readonly documents: readonly TicketDocument[];
     readonly comments: readonly TicketComment[];
     readonly reviewNotes: readonly TicketReviewNote[];
     readonly syncCheckpoints: readonly TicketSyncCheckpoint[];
@@ -270,6 +283,16 @@ export function createTicketsStore(opts: {
     | { readonly ok: true; readonly reviewNote: TicketReviewNote }
     | { readonly ok: false; readonly error: string }
   >;
+  readonly appendDocument: (input: {
+    readonly ticketId: string;
+    readonly kind: TicketDocumentKind;
+    readonly role?: TicketDocumentRole;
+    readonly content: string;
+    readonly actor?: string;
+  }) => Promise<
+    | { readonly ok: true; readonly document: TicketDocument }
+    | { readonly ok: false; readonly error: string }
+  >;
   readonly linkCommentExternalId: (input: {
     readonly ticketId: string;
     readonly commentId: string;
@@ -448,6 +471,7 @@ export function createTicketsStore(opts: {
     readonly events: readonly TicketEvent[];
   }): MaterializedTicketState => {
     const tickets = new Map<string, TicketSummary>();
+    const documentsByTicket = new Map<string, TicketDocument[]>();
     const commentsByTicket = new Map<string, TicketComment[]>();
     const reviewNotesByTicket = new Map<string, TicketReviewNote[]>();
     const syncCheckpointsByTicket = new Map<string, TicketSyncCheckpoint[]>();
@@ -456,6 +480,7 @@ export function createTicketsStore(opts: {
     for (const event of input.events) {
       applyTicketEvent({
         tickets,
+        documentsByTicket,
         commentsByTicket,
         reviewNotesByTicket,
         syncCheckpointsByTicket,
@@ -466,6 +491,7 @@ export function createTicketsStore(opts: {
 
     return {
       tickets: applyDerivedBlocks(tickets),
+      documentsByTicket,
       commentsByTicket,
       reviewNotesByTicket,
       syncCheckpointsByTicket,
@@ -504,6 +530,7 @@ export function createTicketsStore(opts: {
     return {
       tickets: sortTickets({ tickets: input.materialized.tickets.values() }),
       eventsByTicket: groupEventsByTicket({ events: input.events }),
+      documentsByTicket: input.materialized.documentsByTicket,
       commentsByTicket: input.materialized.commentsByTicket,
       reviewNotesByTicket: input.materialized.reviewNotesByTicket,
       syncCheckpointsByTicket: input.materialized.syncCheckpointsByTicket,
@@ -764,12 +791,12 @@ export function createTicketsStore(opts: {
 
     updateTicket: async (input) => {
       const tickets = await materializeTickets();
-      const current = tickets.get(input.ticketId);
-      if (!current) {
+      if (!tickets.has(input.ticketId)) {
         return { ok: false, error: `Ticket not found: ${input.ticketId}` };
       }
 
       const payload: Record<string, unknown> = {};
+      const events: TicketEvent[] = [];
       if (input.title !== undefined) {
         const title = input.title.trim();
         if (!title) {
@@ -778,7 +805,22 @@ export function createTicketsStore(opts: {
         payload.title = title;
       }
       if (input.body !== undefined) {
-        payload.body = input.body;
+        const content = input.body.trimEnd();
+        if (!content) {
+          return { ok: false, error: "Body cannot be empty." };
+        }
+        events.push(
+          buildEvent({
+            ticketId: input.ticketId,
+            type: "ticket.document_recorded",
+            payload: {
+              documentId: randomUUID(),
+              kind: "description",
+              content,
+            },
+            actor: input.actor,
+          })
+        );
       }
       if (input.dependsOn !== undefined) {
         payload.dependsOn = normalizeTicketRefs(input.dependsOn);
@@ -843,18 +885,22 @@ export function createTicketsStore(opts: {
         });
       }
 
-      if (Object.keys(payload).length === 0) {
-        return { ok: false, error: "No updates provided." };
+      if (Object.keys(payload).length > 0) {
+        events.push(
+          buildEvent({
+            ticketId: input.ticketId,
+            type: "ticket.updated",
+            payload,
+            actor: input.actor,
+          })
+        );
       }
 
-      const event = buildEvent({
-        ticketId: input.ticketId,
-        type: "ticket.updated",
-        payload,
-        actor: input.actor,
-      });
+      if (events.length === 0) {
+        return { ok: false, error: "No updates provided." };
+      }
 
-      return await appendEventsAndRefresh({ events: [event] });
+      return await appendEventsAndRefresh({ events });
     },
 
     listTickets: async () => {
@@ -881,6 +927,7 @@ export function createTicketsStore(opts: {
           snapshot.tickets.find((ticket) => ticket.ticketId === ticketId) ??
           null,
         events: snapshot.eventsByTicket.get(ticketId) ?? [],
+        documents: snapshot.documentsByTicket.get(ticketId) ?? [],
         comments: snapshot.commentsByTicket.get(ticketId) ?? [],
         reviewNotes: snapshot.reviewNotesByTicket.get(ticketId) ?? [],
         syncCheckpoints: snapshot.syncCheckpointsByTicket.get(ticketId) ?? [],
@@ -988,6 +1035,49 @@ export function createTicketsStore(opts: {
       };
     },
 
+    appendDocument: async (input) => {
+      const tickets = await materializeTickets();
+      if (!tickets.has(input.ticketId)) {
+        return { ok: false, error: `Ticket not found: ${input.ticketId}` };
+      }
+
+      const content = input.content.trimEnd();
+      if (!content.trim()) {
+        return { ok: false, error: "Document content cannot be empty." };
+      }
+
+      const documentId = randomUUID();
+      const event = buildEvent({
+        ticketId: input.ticketId,
+        type: "ticket.document_recorded",
+        payload: {
+          documentId,
+          kind: input.kind,
+          ...(input.role ? { role: input.role } : {}),
+          content,
+        },
+        actor: input.actor,
+      });
+
+      const wrote = await appendEventsAndRefresh({ events: [event] });
+      if (!wrote.ok) {
+        return wrote;
+      }
+
+      return {
+        ok: true,
+        document: buildTicketDocument({
+          documentId,
+          ticketId: input.ticketId,
+          kind: input.kind,
+          ...(input.role ? { role: input.role } : {}),
+          content,
+          createdAt: event.tsIso,
+          updatedAt: event.tsIso,
+        }),
+      };
+    },
+
     linkCommentExternalId: async (input) => {
       const { snapshot } = await loadStoreContext();
       const comments = snapshot.commentsByTicket.get(input.ticketId) ?? [];
@@ -1207,6 +1297,7 @@ export function createTicketsStore(opts: {
 
 function applyTicketEvent(input: {
   readonly tickets: Map<string, TicketSummary>;
+  readonly documentsByTicket: Map<string, TicketDocument[]>;
   readonly commentsByTicket: Map<string, TicketComment[]>;
   readonly reviewNotesByTicket: Map<string, TicketReviewNote[]>;
   readonly syncCheckpointsByTicket: Map<string, TicketSyncCheckpoint[]>;
@@ -1217,6 +1308,7 @@ function applyTicketEvent(input: {
     case "ticket.created": {
       applyTicketCreatedEvent({
         tickets: input.tickets,
+        documentsByTicket: input.documentsByTicket,
         event: input.event,
       });
       break;
@@ -1231,6 +1323,15 @@ function applyTicketEvent(input: {
     case "ticket.updated": {
       applyTicketUpdatedEvent({
         tickets: input.tickets,
+        documentsByTicket: input.documentsByTicket,
+        event: input.event,
+      });
+      break;
+    }
+    case "ticket.document_recorded": {
+      applyTicketDocumentRecordedEvent({
+        tickets: input.tickets,
+        documentsByTicket: input.documentsByTicket,
         event: input.event,
       });
       break;
@@ -1289,6 +1390,7 @@ function applyTicketEvent(input: {
 
 function applyTicketCreatedEvent(input: {
   readonly tickets: Map<string, TicketSummary>;
+  readonly documentsByTicket: Map<string, TicketDocument[]>;
   readonly event: TicketEvent;
 }): void {
   const title =
@@ -1369,6 +1471,20 @@ function applyTicketCreatedEvent(input: {
       },
     })
   );
+
+  if (body) {
+    appendMapValue({
+      map: input.documentsByTicket,
+      key: input.event.ticketId,
+      value: buildLegacyDescriptionDocument({
+        eventId: input.event.eventId,
+        ticketId: input.event.ticketId,
+        content: body,
+        createdAt: input.event.tsIso,
+        updatedAt: input.event.tsIso,
+      }),
+    });
+  }
 }
 
 function applyTicketStatusChangedEvent(input: {
@@ -1399,6 +1515,7 @@ function applyTicketStatusChangedEvent(input: {
 
 function applyTicketUpdatedEvent(input: {
   readonly tickets: Map<string, TicketSummary>;
+  readonly documentsByTicket: Map<string, TicketDocument[]>;
   readonly event: TicketEvent;
 }): void {
   const current = input.tickets.get(input.event.ticketId);
@@ -1517,6 +1634,78 @@ function applyTicketUpdatedEvent(input: {
       },
     })
   );
+
+  if (body !== undefined) {
+    appendMapValue({
+      map: input.documentsByTicket,
+      key: input.event.ticketId,
+      value: buildLegacyDescriptionDocument({
+        eventId: input.event.eventId,
+        ticketId: input.event.ticketId,
+        content: body,
+        createdAt: input.event.tsIso,
+        updatedAt: input.event.tsIso,
+      }),
+    });
+  }
+}
+
+function applyTicketDocumentRecordedEvent(input: {
+  readonly tickets: Map<string, TicketSummary>;
+  readonly documentsByTicket: Map<string, TicketDocument[]>;
+  readonly event: TicketEvent;
+}): void {
+  const current = input.tickets.get(input.event.ticketId);
+  if (!current) {
+    return;
+  }
+
+  const kindValue = readOptionalStringPayload({
+    value: input.event.payload.kind,
+  });
+  const content = readOptionalTextPayload({
+    value: input.event.payload.content,
+  });
+  if (!(kindValue && content && isTicketDocumentKind(kindValue))) {
+    return;
+  }
+
+  const roleValue = readOptionalStringPayload({
+    value: input.event.payload.role,
+  });
+  const role =
+    roleValue && isTicketDocumentRole(roleValue) ? roleValue : undefined;
+
+  const document = buildTicketDocument({
+    documentId:
+      readOptionalStringPayload({ value: input.event.payload.documentId }) ??
+      input.event.eventId,
+    ticketId: input.event.ticketId,
+    kind: kindValue,
+    ...(role ? { role } : {}),
+    content,
+    createdAt: input.event.tsIso,
+    updatedAt: input.event.tsIso,
+  });
+
+  appendMapValue({
+    map: input.documentsByTicket,
+    key: input.event.ticketId,
+    value: document,
+  });
+
+  const documents = input.documentsByTicket.get(input.event.ticketId) ?? [];
+  const activeDescription = getActiveTicketDescription({ documents });
+  input.tickets.set(
+    input.event.ticketId,
+    normalizeTicketSummaryCompatibility({
+      ticket: {
+        ...current,
+        ...(activeDescription ? { body: activeDescription.content } : {}),
+        updatedAt: input.event.tsIso,
+      },
+    })
+  );
 }
 
 function applyTicketCommentAppendedEvent(input: {
@@ -1529,10 +1718,10 @@ function applyTicketCommentAppendedEvent(input: {
   }
 
   const body =
-    readOptionalStringPayload({
+    readOptionalTextPayload({
       value: input.event.payload.body,
     }) ??
-    readOptionalStringPayload({
+    readOptionalTextPayload({
       value: input.event.payload.markdown,
     });
   if (!body) {
@@ -1612,8 +1801,8 @@ function applyTicketReviewNoteAppendedEvent(input: {
   }
 
   const body =
-    readOptionalStringPayload({ value: input.event.payload.body }) ??
-    readOptionalStringPayload({ value: input.event.payload.markdown });
+    readOptionalTextPayload({ value: input.event.payload.body }) ??
+    readOptionalTextPayload({ value: input.event.payload.markdown });
   if (!body) {
     return;
   }
@@ -1952,6 +2141,15 @@ function readOptionalStringPayload(input: {
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
+function readOptionalTextPayload(input: {
+  readonly value: unknown;
+}): string | undefined {
+  if (typeof input.value !== "string") {
+    return undefined;
+  }
+  return input.value.trim().length > 0 ? input.value : undefined;
+}
+
 function normalizeOwnerOrSource(input: {
   readonly value: string | undefined;
   readonly fallback: string;
diff --git a/tests/tickets-extension.test.ts b/tests/tickets-extension.test.ts
index e85e863cf..4479920bf 100644
--- a/tests/tickets-extension.test.ts
+++ b/tests/tickets-extension.test.ts
@@ -312,6 +312,258 @@ testIntegration(
   }
 );
 
+testIntegration(
+  "tickets extension: document command appends spec docs and updates the active description",
+  { timeout: 60_000 },
+  async () => {
+    const root = await mkdirTempDir({ prefix: "hack-cli-tickets-docs-e2e-" });
+    const projectDir = join(root, "project");
+
+    await mkdir(projectDir, { recursive: true });
+    await copyDir({
+      from: resolve(import.meta.dir, "../examples/tickets"),
+      to: projectDir,
+    });
+
+    await run({ cwd: projectDir, cmd: ["git", "init"] });
+    await run({
+      cwd: projectDir,
+      cmd: ["git", "config", "user.email", "tests@hack"],
+    });
+    await run({
+      cwd: projectDir,
+      cmd: ["git", "config", "user.name", "hack-cli-tests"],
+    });
+    await run({ cwd: projectDir, cmd: ["git", "add", "-A"] });
+    await run({ cwd: projectDir, cmd: ["git", "commit", "-m", "init"] });
+
+    const created = await runHack({
+      cwd: projectDir,
+      args: [
+        "tickets",
+        "create",
+        "--title",
+        "Document lifecycle",
+        "--body",
+        "## Context\nInitial description",
+        "--json",
+      ],
+    });
+    const createdJson = JSON.parse(created.stdout) as {
+      ticket: { ticketId: string };
+    };
+    const ticketId = createdJson.ticket.ticketId;
+
+    const spec = await runHack({
+      cwd: projectDir,
+      args: [
+        "tickets",
+        "document",
+        ticketId,
+        "--kind",
+        "spec",
+        "--body",
+        "## Goals\n- Add spec support",
+        "--json",
+      ],
+    });
+    const specJson = JSON.parse(spec.stdout) as {
+      document: { kind: string; role: string };
+    };
+    expect(specJson.document.kind).toBe("spec");
+    expect(specJson.document.role).toBe("spec");
+
+    const description = await runHack({
+      cwd: projectDir,
+      args: [
+        "tickets",
+        "document",
+        ticketId,
+        "--kind",
+        "description",
+        "--body",
+        "## Context\nUpdated description",
+        "--json",
+      ],
+    });
+    const descriptionJson = JSON.parse(description.stdout) as {
+      document: { kind: string; content: string };
+    };
+    expect(descriptionJson.document.kind).toBe("description");
+    expect(descriptionJson.document.content).toBe(
+      "## Context\nUpdated description"
+    );
+
+    const shown = await runHack({
+      cwd: projectDir,
+      args: ["tickets", "show", ticketId, "--json"],
+    });
+    const showJson = JSON.parse(shown.stdout) as {
+      ticket: { body?: string };
+      documents: Array<{ kind: string; role: string; content: string }>;
+    };
+    expect(showJson.ticket.body).toBe("## Context\nUpdated description");
+    expect(showJson.documents).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: "description",
+          role: "description",
+          content: "## Context\nInitial description",
+        }),
+        expect.objectContaining({
+          kind: "spec",
+          role: "spec",
+          content: "## Goals\n- Add spec support",
+        }),
+        expect.objectContaining({
+          kind: "description",
+          role: "description",
+          content: "## Context\nUpdated description",
+        }),
+      ])
+    );
+
+    await rm(root, { recursive: true, force: true });
+  }
+);
+
+testIntegration(
+  "tickets extension: hidden ref sync transports only the journal and peers rebuild projection state locally",
+  { timeout: 60_000 },
+  async () => {
+    const root = await mkdirTempDir({
+      prefix: "hack-cli-tickets-portability-e2e-",
+    });
+    const authorDir = join(root, "author");
+    const peerDir = join(root, "peer");
+    const remoteDir = join(root, "remote.git");
+
+    await mkdir(authorDir, { recursive: true });
+    await copyDir({
+      from: resolve(import.meta.dir, "../examples/tickets"),
+      to: authorDir,
+    });
+
+    await run({ cwd: authorDir, cmd: ["git", "init"] });
+    await run({
+      cwd: authorDir,
+      cmd: ["git", "config", "user.email", "tests@hack"],
+    });
+    await run({
+      cwd: authorDir,
+      cmd: ["git", "config", "user.name", "hack-cli-tests"],
+    });
+    await run({ cwd: authorDir, cmd: ["git", "add", "-A"] });
+    await run({ cwd: authorDir, cmd: ["git", "commit", "-m", "init"] });
+
+    await run({ cwd: root, cmd: ["git", "init", "--bare", remoteDir] });
+    await run({
+      cwd: authorDir,
+      cmd: ["git", "remote", "add", "origin", remoteDir],
+    });
+    await run({
+      cwd: authorDir,
+      cmd: ["git", "push", "-u", "origin", "HEAD:main"],
+    });
+
+    const created = await runHack({
+      cwd: authorDir,
+      args: ["tickets", "create", "--title", "Portable journal", "--json"],
+    });
+    const createdJson = JSON.parse(created.stdout) as {
+      ticket: { ticketId: string };
+    };
+
+    const remoteTree = await run({
+      cwd: root,
+      cmd: [
+        "git",
+        `--git-dir=${remoteDir}`,
+        "ls-tree",
+        "-r",
+        "--name-only",
+        "refs/hack/tickets",
+      ],
+    });
+    const remotePaths = remoteTree.stdout
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+    expect(
+      remotePaths.some((path) =>
+        path.startsWith(".hack/tickets/events/events-")
+      )
+    ).toBe(true);
+    expect(remotePaths).not.toContain(".hack/tickets/projection.sqlite");
+
+    await mkdir(peerDir, { recursive: true });
+    await copyDir({
+      from: resolve(import.meta.dir, "../examples/tickets"),
+      to: peerDir,
+    });
+    await run({ cwd: peerDir, cmd: ["git", "init"] });
+    await run({
+      cwd: peerDir,
+      cmd: ["git", "config", "user.email", "tests@hack"],
+    });
+    await run({
+      cwd: peerDir,
+      cmd: ["git", "config", "user.name", "hack-cli-tests"],
+    });
+    await run({ cwd: peerDir, cmd: ["git", "add", "-A"] });
+    await run({ cwd: peerDir, cmd: ["git", "commit", "-m", "init"] });
+    await run({
+      cwd: peerDir,
+      cmd: ["git", "remote", "add", "origin", remoteDir],
+    });
+
+    const synced = await runHack({
+      cwd: peerDir,
+      args: ["tickets", "sync", "--json"],
+    });
+    expect(synced.exitCode).toBe(0);
+
+    const shown = await runHack({
+      cwd: peerDir,
+      args: ["tickets", "show", createdJson.ticket.ticketId, "--json"],
+    });
+    expect(shown.exitCode).toBe(0);
+
+    const eventsDir = join(
+      peerDir,
+      ".hack/tickets/git/worktree/.hack/tickets/events"
+    );
+    const eventFiles = (await readdir(eventsDir))
+      .filter((entry) => entry.endsWith(".jsonl"))
+      .sort();
+    expect(eventFiles.length).toBeGreaterThan(0);
+    const journalBeforeDeletion = await readFile(
+      join(eventsDir, eventFiles[0] ?? ""),
+      "utf8"
+    );
+
+    const projectionPath = join(peerDir, ".hack/tickets/projection.sqlite");
+    expect(await Bun.file(projectionPath).exists()).toBe(true);
+    await rm(projectionPath, { force: true });
+    expect(await Bun.file(projectionPath).exists()).toBe(false);
+
+    const rebuilt = await runHack({
+      cwd: peerDir,
+      args: ["tickets", "list", "--json"],
+    });
+    expect(rebuilt.exitCode).toBe(0);
+    expect(await Bun.file(projectionPath).exists()).toBe(true);
+
+    const journalAfterDeletion = await readFile(
+      join(eventsDir, eventFiles[0] ?? ""),
+      "utf8"
+    );
+    expect(journalAfterDeletion).toBe(journalBeforeDeletion);
+
+    await rm(root, { recursive: true, force: true });
+  }
+);
+
 interface RunResult {
   readonly stdout: string;
   readonly stderr: string;
diff --git a/tests/tickets-store.test.ts b/tests/tickets-store.test.ts
index becf0d088..86c4baf20 100644
--- a/tests/tickets-store.test.ts
+++ b/tests/tickets-store.test.ts
@@ -500,6 +500,73 @@ test("tickets store ignores duplicate sync checkpoints with the same idempotency
   ).toHaveLength(1);
 });
 
+test("tickets store records immutable documents and projects body from the active description", async () => {
+  const projectRoot = await createTempGitProject({
+    prefix: "hack-cli-tickets-documents-",
+  });
+  const store = await createStore({ projectRoot });
+
+  const created = await store.createTicket({
+    title: "Document-backed ticket",
+    body: "## Context\nInitial description",
+    owner: "hack",
+    source: "hack",
+    actor: "creator@hack",
+  });
+  expect(created.ok).toBe(true);
+  if (!created.ok) {
+    throw new Error(created.error);
+  }
+
+  const spec = await store.appendDocument({
+    ticketId: created.ticket.ticketId,
+    kind: "spec",
+    content: "\n## Goals\n- Ship immutable ticket documents",
+    actor: "author@hack",
+  });
+  expect(spec.ok).toBe(true);
+  if (!spec.ok) {
+    throw new Error(spec.error);
+  }
+
+  const description = await store.appendDocument({
+    ticketId: created.ticket.ticketId,
+    kind: "description",
+    content: "## Context\nUpdated description",
+    actor: "author@hack",
+  });
+  expect(description.ok).toBe(true);
+  if (!description.ok) {
+    throw new Error(description.error);
+  }
+
+  const detail = await store.getTicketDetail({
+    ticketId: created.ticket.ticketId,
+  });
+
+  expect(detail.ticket?.body).toBe("## Context\nUpdated description");
+  expect(detail.documents).toEqual([
+    expect.objectContaining({
+      kind: "description",
+      role: "description",
+      content: "## Context\nInitial description",
+    }),
+    expect.objectContaining({
+      kind: "spec",
+      role: "spec",
+      content: "\n## Goals\n- Ship immutable ticket documents",
+    }),
+    expect.objectContaining({
+      kind: "description",
+      role: "description",
+      content: "## Context\nUpdated description",
+    }),
+  ]);
+  expect(
+    detail.events.filter((event) => event.type === "ticket.document_recorded")
+  ).toHaveLength(2);
+}, 20_000);
+
 test("tickets store persists a sqlite projection and rebuilds it when deleted", async () => {
   const projectRoot = await createTempGitProject({
     prefix: "hack-cli-tickets-projection-",

From 362e2565c1b83f3ca6f090074426b4f8541b3ad2 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:00:55 +0000
Subject: [PATCH 012/134] docs: define prerequisite detection matrix

---
 docs/README.md                               |   1 +
 docs/guides/prerequisite-detection-matrix.md | 159 +++++
 src/cli/prerequisites.ts                     | 628 +++++++++++++++++++
 tests/prerequisites-matrix.test.ts           | 209 ++++++
 4 files changed, 997 insertions(+)
 create mode 100644 docs/guides/prerequisite-detection-matrix.md
 create mode 100644 src/cli/prerequisites.ts
 create mode 100644 tests/prerequisites-matrix.test.ts

diff --git a/docs/README.md b/docs/README.md
index e493be242..973c47a74 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -34,6 +34,7 @@ Quick diagnostics:
 - Remote setup (one command): `hack remote setup`
 - [Initialize a project](guides/init-project.md)
 - [Global settings](guides/global-settings.md)
+- [Prerequisite detection matrix](guides/prerequisite-detection-matrix.md)
 - [Tickets (git-backed)](guides/tickets.md)
 - [Expose the gateway over SSH](guides/remote-ssh.md)
 - [Expose the gateway with Cloudflare](guides/remote-cloudflare.md)
diff --git a/docs/guides/prerequisite-detection-matrix.md b/docs/guides/prerequisite-detection-matrix.md
new file mode 100644
index 000000000..10f72e2bd
--- /dev/null
+++ b/docs/guides/prerequisite-detection-matrix.md
@@ -0,0 +1,159 @@
+# Prerequisite Detection Matrix
+
+This guide defines the prerequisite contract for guided interception in the CLI.
+The implementation-facing source of truth lives in `src/cli/prerequisites.ts`.
+
+## Scope
+
+This matrix covers the prerequisite families called out in HACK-441:
+
+- Docker runtime
+- Global install state
+- tmux/zellij mux availability
+- GitHub auth/config
+- Linear auth/config
+
+The goal is not to make every command fail earlier. The goal is to decide, in a repeatable way, whether a missing prerequisite should:
+
+- block: stop and show the missing prerequisite inline
+- guide: intercept into a repair/setup path
+- warn: continue and surface degraded or diagnostic state
+
+## Check Catalog
+
+| Check ID | Domain | What it means | Primary guidance |
+| --- | --- | --- | --- |
+| `docker_cli` | Docker | `docker` is installed and on `PATH` | Install Docker Desktop or OrbStack |
+| `docker_daemon` | Docker | `docker info` succeeds | Start Docker or route into `hack global install` |
+| `global_bootstrap` | Global | `hack global install` has generated `~/.hack` artifacts | `hack global install` |
+| `global_services` | Global | Caddy/CoreDNS/Loki are reachable for routed hosts, Loki logs, or Caddy-managed CA export | `hack global up` or `hack global install` |
+| `mux_backend` | Mux | `sessions.mux` resolves to an installed tmux or zellij backend | Install tmux/zellij or change `sessions.mux` |
+| `tmux_binary` | Mux | tmux exists for tmux-backed session commands | Install tmux directly, then optionally run `hack setup tmux` |
+| `github_profile` | GitHub | A GitHub profile is resolvable from flags/config | `hack x github connect` or `hack x github use` |
+| `github_token` | GitHub | The selected GitHub profile resolves a usable token | `hack x github connect` or `hack x github oauth-connect` |
+| `github_gh_cli` | GitHub | `gh` exists for browser bootstrap | Install GitHub CLI |
+| `linear_profile` | Linear | A Linear profile is resolvable from flags/config | `hack linear connect` or `hack linear use` |
+| `linear_token` | Linear | The selected Linear profile resolves a usable token | `hack linear connect` or `hack linear oauth-connect` |
+| `linear_broker_auth` | Linear | A Hack broker management token exists for broker-owned flows | `hack auth login` |
+| `linear_oauth_client` | Linear | Local OAuth client credentials exist for direct OAuth fallback | Configure local Linear OAuth env/auth-ref values |
+
+## Command Matrix
+
+| Command(s) | Checks | Missing behavior | Notes |
+| --- | --- | --- | --- |
+| `hack global install` | `docker_cli`, `docker_daemon`, `mux_backend` | guide, guide, warn | Bootstrap should repair Docker issues inline, but only warn about missing mux tooling |
+| `hack global up`, `hack global status`, `hack global logs`, `hack global logs-reset` | `global_bootstrap`, `docker_cli`, `docker_daemon` | guide, guide, guide | These commands operate on the generated global stack |
+| `hack global down` | `docker_cli`, `docker_daemon` | guide, guide | Conditional: only when a managed global stack already exists; otherwise teardown should stay idempotent |
+| `hack global ca`, `hack global trust` | `global_bootstrap`, `docker_cli`, `docker_daemon`, `global_services` | guide, guide, guide, guide | CA export/trust depends on an installed and running Caddy-managed global stack |
+| `hack up`, `hack down`, `hack restart`, `hack ps`, `hack run`, `hack tui` | `docker_cli`, `docker_daemon` | guide, guide | Core Docker-backed runtime commands |
+| `hack up`, `hack restart` | `mux_backend` | guide | Only when lifecycle host processes or mux-backed pre-start hooks are configured |
+| `hack open` | `global_services` | guide | Routed `*.hack` access should repair global routing instead of failing opaquely |
+| `hack logs` | `docker_cli`, `docker_daemon`, `global_services` | guide, guide, warn | Default logs may fall back from Loki to compose logs |
+| `hack logs --loki`, `hack logs --query` | `global_services` | guide | Explicit Loki mode should not silently fall back |
+| `hack session`, `hack session list`, `hack session start`, `hack session attach`, `hack session exec`, `hack session stop`, `hack ssh` | `tmux_binary` | guide | The current session and session-aware SSH implementation is tmux-backed even when mux config exists elsewhere |
+| `hack session panes`, `hack session capture`, `hack session tail`, `hack setup tmux` | `tmux_binary` | guide | tmux-only surfaces |
+| `hack x github status`, `hack x github profiles` | `github_profile`, `github_token` | warn, warn | Diagnostics should expose missing state instead of intercepting it |
+| `hack x github use` | `github_profile` | guide | Profile selection should redirect into setup when there is no resolvable target |
+| `hack x github oauth-connect` | `github_gh_cli` | guide | Browser bootstrap is `gh`-driven |
+| `hack x github pr-upsert` | `github_profile`, `github_token` | guide, guide | Mutating GitHub API command |
+| `hack linear status`, `hack linear profiles` | `linear_profile`, `linear_token` | warn, warn | Diagnostics should keep unresolved state visible |
+| `hack linear use` | `linear_profile` | guide | Profile selection should redirect into setup when there is no resolvable target |
+| `hack linear connect` | `linear_broker_auth`, `linear_oauth_client` | guide, guide | Conditional: broker auth only when broker OAuth is selected and local OAuth fallback is unavailable; direct OAuth config only when fallback is the chosen path |
+| `hack linear oauth-connect` | `linear_broker_auth`, `linear_oauth_client` | guide, guide | Same split as `hack linear connect`, but on the explicit OAuth path |
+| `hack linear connections`, `hack linear seed-local-access`, `hack linear deliveries`, `hack linear apply-delivery`, `hack linear subscriptions`, `hack linear set-subscription`, `hack linear remove-subscription` | `linear_broker_auth` | guide | These commands are broker-backed and should route into Hack auth first |
+| `hack linear projects`, `hack linear sync-issue`, `hack linear sync-project` | `linear_profile`, `linear_token` | guide, guide | Linear API actions should repair auth/config before invoking the API |
+| `hack linear project-bind`, `hack linear project-link` | `linear_profile`, `linear_token` | guide, guide | Conditional: only when the command must resolve project metadata remotely instead of using a fully specified local binding |
+| `hack linear run-autosync` | `linear_profile`, `linear_token`, `linear_broker_auth` | guide, guide, guide | Autosync needs both Linear API access and broker-backed subscription/delivery access |
+
+## Decision Rules
+
+### Use `guide`
+
+Use guided interception when the command is operational and the missing prerequisite is something Hack can clearly repair or route the user toward:
+
+- Docker is missing or not running for Docker-backed workflows
+- `hack global install` has never been run
+- Routed global services are missing for `hack open` or explicit Loki commands
+- tmux is missing for the current session and SSH implementation, or mux is missing for lifecycle-backed host-process flows
+- GitHub or Linear action commands are missing resolvable profile/token state
+- broker-owned Linear flows are missing Hack account auth
+
+### Use `warn`
+
+Use a warning when the command is itself diagnostic or the CLI can still continue in a degraded but useful mode:
+
+- `hack global install` with missing tmux/zellij
+- `hack logs` when Loki is unavailable but compose fallback still works
+- `hack x github status` and `hack x github profiles`
+- `hack linear status` and `hack linear profiles`
+
+### Use `block`
+
+The current matrix leaves `block` for cases where guided repair is not appropriate, but the ticket scope does not require a first blocking case. The important contract is that operational commands guide, diagnostics warn, and only irreparable/unowned failures should block later.
+
+## Commands That Should Invoke Checks
+
+The explicit command set currently covered by the source-of-truth matrix is:
+
+```text
+global install
+global up
+global status
+global logs
+global logs-reset
+global down
+global ca
+global trust
+up
+down
+restart
+ps
+run
+tui
+open
+logs
+logs --loki
+logs --query
+session
+session list
+session start
+session attach
+session exec
+session stop
+ssh
+session panes
+session capture
+session tail
+setup tmux
+x github status
+x github profiles
+x github use
+x github oauth-connect
+x github pr-upsert
+linear status
+linear profiles
+linear use
+linear connect
+linear oauth-connect
+linear connections
+linear seed-local-access
+linear projects
+linear project-bind
+linear project-link
+linear sync-issue
+linear sync-project
+linear run-autosync
+linear deliveries
+linear apply-delivery
+linear subscriptions
+linear set-subscription
+linear remove-subscription
+```
+
+## Notes for Follow-on Implementation
+
+- Preserve the current distinction between diagnostics and actions. Status commands should not disappear behind setup wizards.
+- Keep conditional checks conditional. `mux_backend` only matters for lifecycle-backed `hack up`/`hack restart` when lifecycle host processes are configured.
+- Keep cleanup and local-only config commands out of shared interception. `x github disconnect`, `linear disconnect`, `linear assignee-mappings`, and `linear project-unlink` should use command-local validation instead of the prerequisite matrix.
+- Docker detection should distinguish CLI missing from daemon unavailable because the repair path is different.
+- GitHub and Linear setup flows already contain parts of this guidance. Interception should centralize the decision, not duplicate every downstream error string.
diff --git a/src/cli/prerequisites.ts b/src/cli/prerequisites.ts
new file mode 100644
index 000000000..331e39d22
--- /dev/null
+++ b/src/cli/prerequisites.ts
@@ -0,0 +1,628 @@
+export type PrerequisitePolicy = "block" | "guide" | "warn";
+
+export type PrerequisiteCheckId =
+  | "docker_cli"
+  | "docker_daemon"
+  | "global_bootstrap"
+  | "global_services"
+  | "mux_backend"
+  | "tmux_binary"
+  | "github_profile"
+  | "github_token"
+  | "github_gh_cli"
+  | "linear_profile"
+  | "linear_token"
+  | "linear_broker_auth"
+  | "linear_oauth_client";
+
+export type PrerequisiteDomain =
+  | "docker"
+  | "global"
+  | "mux"
+  | "github"
+  | "linear";
+
+/**
+ * Stable metadata for a missing-prerequisite check.
+ */
+export type PrerequisiteCheckDefinition = {
+  readonly id: PrerequisiteCheckId;
+  readonly domain: PrerequisiteDomain;
+  readonly summary: string;
+  readonly detection: string;
+  readonly primaryGuidance: string;
+};
+
+/**
+ * A concrete prerequisite rule for a user-facing command.
+ */
+export type CommandPrerequisiteRule = {
+  readonly checkId: PrerequisiteCheckId;
+  readonly onMissing: PrerequisitePolicy;
+  readonly reason: string;
+  readonly when?: string;
+};
+
+/**
+ * A user-facing command or conditional command variant that should invoke checks.
+ */
+export type CommandPrerequisiteContract = {
+  readonly name: string;
+  readonly commands: readonly string[];
+  readonly rules: readonly CommandPrerequisiteRule[];
+};
+
+export const PREREQUISITE_CHECKS = [
+  {
+    id: "docker_cli",
+    domain: "docker",
+    summary: "Docker CLI is installed and on PATH",
+    detection:
+      "Resolve `docker` from PATH before any Docker-backed command path.",
+    primaryGuidance:
+      "Install Docker Desktop or OrbStack before retrying the command.",
+  },
+  {
+    id: "docker_daemon",
+    domain: "docker",
+    summary: "Docker engine is reachable",
+    detection:
+      "Run `docker info`; distinguish an installed CLI from a stopped or unreachable daemon.",
+    primaryGuidance:
+      "Offer to start the detected backend when possible, otherwise point to `hack global install` or the platform Docker app/service.",
+  },
+  {
+    id: "global_bootstrap",
+    domain: "global",
+    summary:
+      "`hack global install` has generated the managed ~/.hack stack files",
+    detection:
+      "Require generated compose/config/schema artifacts under `~/.hack` before commands that operate on the global stack.",
+    primaryGuidance: "Launch `hack global install`.",
+  },
+  {
+    id: "global_services",
+    domain: "global",
+    summary:
+      "Global routing, logging, and Caddy-managed services are reachable",
+    detection:
+      "Check Caddy/CoreDNS/Loki reachability when a command relies on `*.hack`, internal DNS, Loki-backed logs, or Caddy-managed CA export.",
+    primaryGuidance:
+      "Launch `hack global up` when bootstrap exists, otherwise fall back to `hack global install`.",
+  },
+  {
+    id: "mux_backend",
+    domain: "mux",
+    summary:
+      "The configured `sessions.mux` backend resolves to an installed tmux or zellij binary",
+    detection:
+      "Read `sessions.mux`, then verify the selected backend in PATH; in `auto`, accept either tmux or zellij.",
+    primaryGuidance:
+      "Install tmux or zellij, or change `sessions.mux` to a valid value.",
+  },
+  {
+    id: "tmux_binary",
+    domain: "mux",
+    summary: "tmux is available for tmux-only session features",
+    detection:
+      "Resolve `tmux` from PATH before tmux-specific commands like pane inspection or capture.",
+    primaryGuidance:
+      "Install tmux directly. After tmux is available, `hack setup tmux` can configure the picker keybinding.",
+  },
+  {
+    id: "github_profile",
+    domain: "github",
+    summary:
+      "A GitHub profile is explicitly selected or resolvable from config",
+    detection:
+      "Resolve profile selection using command flag, project override, global default, then implicit default.",
+    primaryGuidance:
+      "Launch `hack x github connect --profile <name>` or choose a profile with `hack x github use --profile <name>`.",
+  },
+  {
+    id: "github_token",
+    domain: "github",
+    summary: "The selected GitHub profile can resolve a usable token",
+    detection:
+      "Resolve token from keychain, refresh flow, or env fallback before invoking GitHub API operations.",
+    primaryGuidance:
+      "Launch `hack x github connect --profile <name>` or rerun `hack x github oauth-connect --profile <name>`.",
+  },
+  {
+    id: "github_gh_cli",
+    domain: "github",
+    summary: "`gh` is installed for GitHub browser bootstrap",
+    detection:
+      "Resolve `gh` from PATH before `oauth-connect`; optionally preflight `gh auth status` once the CLI is present.",
+    primaryGuidance:
+      "Install GitHub CLI and rerun `hack x github oauth-connect`.",
+  },
+  {
+    id: "linear_profile",
+    domain: "linear",
+    summary:
+      "A Linear profile is explicitly selected or resolvable from config",
+    detection:
+      "Resolve profile selection using command flag, project override, global default, then implicit default.",
+    primaryGuidance:
+      "Launch `hack linear connect --profile <name>` or choose a profile with `hack linear use --profile <name>`.",
+  },
+  {
+    id: "linear_token",
+    domain: "linear",
+    summary: "The selected Linear profile can resolve a usable access token",
+    detection:
+      "Resolve token from keychain, broker refresh, or env fallback before Linear API operations.",
+    primaryGuidance:
+      "Launch `hack linear connect --profile <name>` or rerun `hack linear oauth-connect --profile <name>`.",
+  },
+  {
+    id: "linear_broker_auth",
+    domain: "linear",
+    summary:
+      "A Hack broker management token is available for broker-owned Linear flows",
+    detection:
+      "Require the local Hack auth session before broker-owned OAuth bootstrap or token refresh.",
+    primaryGuidance: "Launch `hack auth login`.",
+  },
+  {
+    id: "linear_oauth_client",
+    domain: "linear",
+    summary:
+      "Local Linear OAuth client credentials are configured for direct OAuth fallback",
+    detection:
+      "Require local Linear OAuth client id and secret when using the direct OAuth path instead of the broker.",
+    primaryGuidance:
+      "Configure the local Linear OAuth env/auth-ref values, then rerun `hack linear oauth-connect`.",
+  },
+] as const satisfies readonly PrerequisiteCheckDefinition[];
+
+export const COMMAND_PREREQUISITE_CONTRACTS = [
+  {
+    name: "Global bootstrap",
+    commands: ["global install"],
+    rules: [
+      {
+        checkId: "docker_cli",
+        onMissing: "guide",
+        reason:
+          "Global bootstrap cannot create or start the managed stack without Docker.",
+      },
+      {
+        checkId: "docker_daemon",
+        onMissing: "guide",
+        reason:
+          "This command should intercept into backend start guidance instead of failing on `docker info`.",
+      },
+      {
+        checkId: "mux_backend",
+        onMissing: "warn",
+        reason:
+          "Global bootstrap should complete even if session management will be degraded afterward.",
+      },
+    ],
+  },
+  {
+    name: "Global stack lifecycle",
+    commands: [
+      "global up",
+      "global status",
+      "global logs",
+      "global logs-reset",
+    ],
+    rules: [
+      {
+        checkId: "global_bootstrap",
+        onMissing: "guide",
+        reason:
+          "These commands operate on the generated global stack and should redirect to install when the stack was never bootstrapped.",
+      },
+      {
+        checkId: "docker_cli",
+        onMissing: "guide",
+        reason: "The global stack is Docker-managed.",
+      },
+      {
+        checkId: "docker_daemon",
+        onMissing: "guide",
+        reason:
+          "These commands should guide users into starting Docker rather than surfacing raw engine errors.",
+      },
+    ],
+  },
+  {
+    name: "Global stack teardown",
+    commands: ["global down"],
+    rules: [
+      {
+        checkId: "docker_cli",
+        onMissing: "guide",
+        reason:
+          "Tearing down an existing global stack still uses Docker-managed resources.",
+        when: "Only when the managed global stack has already been bootstrapped; otherwise the command should remain idempotent.",
+      },
+      {
+        checkId: "docker_daemon",
+        onMissing: "guide",
+        reason:
+          "Stopping an existing global stack should guide users into starting Docker rather than surfacing raw engine errors.",
+        when: "Only when the managed global stack has already been bootstrapped; otherwise the command should remain idempotent.",
+      },
+    ],
+  },
+  {
+    name: "Global CA export and trust",
+    commands: ["global ca", "global trust"],
+    rules: [
+      {
+        checkId: "global_bootstrap",
+        onMissing: "guide",
+        reason:
+          "CA export and trust flows depend on the managed global stack having been installed at least once.",
+      },
+      {
+        checkId: "docker_cli",
+        onMissing: "guide",
+        reason:
+          "These commands extract the Caddy-managed certificate authority from Docker-managed global services.",
+      },
+      {
+        checkId: "docker_daemon",
+        onMissing: "guide",
+        reason:
+          "CA export and trust should repair Docker availability before attempting to inspect or copy certificates.",
+      },
+      {
+        checkId: "global_services",
+        onMissing: "guide",
+        reason:
+          "The Caddy-managed global services need to be running before Hack can export or trust the generated CA.",
+      },
+    ],
+  },
+  {
+    name: "Project runtime lifecycle",
+    commands: ["up", "down", "restart", "ps", "run", "tui"],
+    rules: [
+      {
+        checkId: "docker_cli",
+        onMissing: "guide",
+        reason:
+          "These commands are fundamentally Docker-backed project operations.",
+      },
+      {
+        checkId: "docker_daemon",
+        onMissing: "guide",
+        reason:
+          "The preferred first-run behavior is guided Docker startup rather than a hard failure.",
+      },
+    ],
+  },
+  {
+    name: "Project lifecycle host processes",
+    commands: ["up", "restart"],
+    rules: [
+      {
+        checkId: "mux_backend",
+        onMissing: "guide",
+        reason:
+          "Lifecycle host processes use the configured mux backend and should fail fast with an actionable setup path.",
+        when: "Only when the project config defines lifecycle host processes or pre-start hooks that require a mux session.",
+      },
+    ],
+  },
+  {
+    name: "Project DNS and routed open",
+    commands: ["open"],
+    rules: [
+      {
+        checkId: "global_services",
+        onMissing: "guide",
+        reason:
+          "Opening `https://<project>.hack` without Caddy/CoreDNS reachability is usually a setup gap, not a user error.",
+      },
+    ],
+  },
+  {
+    name: "Project logs with fallback",
+    commands: ["logs"],
+    rules: [
+      {
+        checkId: "docker_cli",
+        onMissing: "guide",
+        reason:
+          "The compose log backend remains the local fallback and still needs Docker available.",
+      },
+      {
+        checkId: "docker_daemon",
+        onMissing: "guide",
+        reason:
+          "Without a reachable daemon there is no compose fallback path for logs.",
+      },
+      {
+        checkId: "global_services",
+        onMissing: "warn",
+        reason:
+          "Default logs can degrade to compose output, so missing Loki/Caddy should warn instead of blocking.",
+        when: "Only for the default logs path when the command is allowed to fall back from Loki to compose logs.",
+      },
+    ],
+  },
+  {
+    name: "Project logs without fallback",
+    commands: ["logs --loki", "logs --query"],
+    rules: [
+      {
+        checkId: "global_services",
+        onMissing: "guide",
+        reason:
+          "An explicit Loki request should not silently fall back; it should route into global logging setup.",
+      },
+    ],
+  },
+  {
+    name: "Session commands",
+    commands: [
+      "session",
+      "session list",
+      "session start",
+      "session attach",
+      "session exec",
+      "session stop",
+      "ssh",
+    ],
+    rules: [
+      {
+        checkId: "tmux_binary",
+        onMissing: "guide",
+        reason:
+          "The current session and SSH flows shell out to tmux directly, so they should repair tmux availability before continuing.",
+      },
+    ],
+  },
+  {
+    name: "tmux-only session commands",
+    commands: [
+      "session panes",
+      "session capture",
+      "session tail",
+      "setup tmux",
+    ],
+    rules: [
+      {
+        checkId: "tmux_binary",
+        onMissing: "guide",
+        reason:
+          "These commands are tmux-specific and should launch tmux setup guidance instead of failing later.",
+      },
+    ],
+  },
+  {
+    name: "GitHub diagnostics",
+    commands: ["x github status", "x github profiles"],
+    rules: [
+      {
+        checkId: "github_profile",
+        onMissing: "warn",
+        reason:
+          "Status-style commands exist to expose missing GitHub configuration, so they should report the gap instead of intercepting it.",
+      },
+      {
+        checkId: "github_token",
+        onMissing: "warn",
+        reason:
+          "Token resolution failures should remain visible in diagnostics output rather than being hidden behind setup interception.",
+      },
+    ],
+  },
+  {
+    name: "GitHub profile selection",
+    commands: ["x github use"],
+    rules: [
+      {
+        checkId: "github_profile",
+        onMissing: "guide",
+        reason:
+          "Changing or removing a profile without a resolvable target should redirect into profile setup.",
+      },
+    ],
+  },
+  {
+    name: "GitHub OAuth bootstrap",
+    commands: ["x github oauth-connect"],
+    rules: [
+      {
+        checkId: "github_gh_cli",
+        onMissing: "guide",
+        reason:
+          "GitHub browser bootstrap is built around the `gh` CLI and should intercept before spawning it.",
+      },
+    ],
+  },
+  {
+    name: "GitHub API actions",
+    commands: ["x github pr-upsert"],
+    rules: [
+      {
+        checkId: "github_profile",
+        onMissing: "guide",
+        reason:
+          "PR automation needs a selected GitHub identity before it can talk to the API.",
+      },
+      {
+        checkId: "github_token",
+        onMissing: "guide",
+        reason:
+          "This is a mutating GitHub API command and should route directly into token setup when auth is missing.",
+      },
+    ],
+  },
+  {
+    name: "Linear diagnostics",
+    commands: ["linear status", "linear profiles"],
+    rules: [
+      {
+        checkId: "linear_profile",
+        onMissing: "warn",
+        reason:
+          "Status-style commands should show unresolved Linear profile state instead of intercepting it.",
+      },
+      {
+        checkId: "linear_token",
+        onMissing: "warn",
+        reason:
+          "Users run these commands specifically to inspect missing token state, so guidance belongs in the output rather than a redirect.",
+      },
+    ],
+  },
+  {
+    name: "Linear profile selection",
+    commands: ["linear use"],
+    rules: [
+      {
+        checkId: "linear_profile",
+        onMissing: "guide",
+        reason:
+          "Changing or removing a profile without a resolvable target should redirect into profile setup.",
+      },
+    ],
+  },
+  {
+    name: "Linear connect",
+    commands: ["linear connect"],
+    rules: [
+      {
+        checkId: "linear_broker_auth",
+        onMissing: "guide",
+        reason:
+          "When connect falls into a broker-owned OAuth flow, it should send the user to Hack account login first.",
+        when: "Only when no direct token input is supplied, the command resolves to the broker-owned OAuth path, and local OAuth fallback is not configured.",
+      },
+      {
+        checkId: "linear_oauth_client",
+        onMissing: "guide",
+        reason:
+          "Local direct OAuth should not start until the client id and secret are configured.",
+        when: "Only when no direct token input is supplied and the command resolves to the local OAuth fallback path after broker auth is unavailable or skipped.",
+      },
+    ],
+  },
+  {
+    name: "Linear OAuth bootstrap",
+    commands: ["linear oauth-connect"],
+    rules: [
+      {
+        checkId: "linear_broker_auth",
+        onMissing: "guide",
+        reason:
+          "Broker-owned Linear connection flows should launch Hack account login instead of surfacing auth-broker errors.",
+        when: "Only when the broker-owned OAuth path is selected and local OAuth fallback is not configured.",
+      },
+      {
+        checkId: "linear_oauth_client",
+        onMissing: "guide",
+        reason:
+          "Direct OAuth fallback should intercept before opening the browser if local credentials are missing.",
+        when: "Only when the local OAuth fallback path is selected after broker auth is unavailable or skipped.",
+      },
+    ],
+  },
+  {
+    name: "Linear broker-backed setup and delivery commands",
+    commands: [
+      "linear connections",
+      "linear seed-local-access",
+      "linear deliveries",
+      "linear apply-delivery",
+      "linear subscriptions",
+      "linear set-subscription",
+      "linear remove-subscription",
+    ],
+    rules: [
+      {
+        checkId: "linear_broker_auth",
+        onMissing: "guide",
+        reason:
+          "These commands are broker-backed and should route into Hack account auth before they attempt broker operations.",
+      },
+    ],
+  },
+  {
+    name: "Linear API actions",
+    commands: ["linear projects", "linear sync-issue", "linear sync-project"],
+    rules: [
+      {
+        checkId: "linear_profile",
+        onMissing: "guide",
+        reason:
+          "These commands depend on a resolved Linear profile or project binding before they can talk to Linear.",
+      },
+      {
+        checkId: "linear_token",
+        onMissing: "guide",
+        reason:
+          "These are action commands and should route directly into connection repair when access tokens are missing.",
+      },
+    ],
+  },
+  {
+    name: "Linear project binding with remote resolution",
+    commands: ["linear project-bind", "linear project-link"],
+    rules: [
+      {
+        checkId: "linear_profile",
+        onMissing: "guide",
+        reason:
+          "Project binding needs a resolved Linear profile whenever it must look up project metadata remotely.",
+        when: "Only when the command must resolve project metadata from Linear instead of using a fully specified local binding.",
+      },
+      {
+        checkId: "linear_token",
+        onMissing: "guide",
+        reason:
+          "Remote project lookup should route directly into token repair when Linear API access is missing.",
+        when: "Only when the command must resolve project metadata from Linear instead of using a fully specified local binding.",
+      },
+    ],
+  },
+  {
+    name: "Linear autosync runtime",
+    commands: ["linear run-autosync"],
+    rules: [
+      {
+        checkId: "linear_profile",
+        onMissing: "guide",
+        reason:
+          "Autosync processing needs a resolved Linear profile once it begins working against a configured route.",
+        when: "Only when a target project route is being processed.",
+      },
+      {
+        checkId: "linear_token",
+        onMissing: "guide",
+        reason:
+          "Autosync should repair missing Linear API access before it starts the sync runtime.",
+        when: "Only when the runtime needs to talk to the Linear API for the selected route.",
+      },
+      {
+        checkId: "linear_broker_auth",
+        onMissing: "guide",
+        reason:
+          "Autosync also depends on broker-backed subscription and delivery flows, so broker auth should repair up front.",
+      },
+    ],
+  },
+] as const satisfies readonly CommandPrerequisiteContract[];
+
+export const COMMANDS_THAT_INVOKE_PREREQUISITE_CHECKS = [
+  ...new Set(
+    COMMAND_PREREQUISITE_CONTRACTS.flatMap((contract) => contract.commands)
+  ),
+] as const;
+
+export function getCommandPrerequisiteContracts(input: {
+  readonly command: string;
+}): readonly CommandPrerequisiteContract[] {
+  return COMMAND_PREREQUISITE_CONTRACTS.filter((contract) =>
+    contract.commands.includes(input.command)
+  );
+}
diff --git a/tests/prerequisites-matrix.test.ts b/tests/prerequisites-matrix.test.ts
new file mode 100644
index 000000000..40322cbd1
--- /dev/null
+++ b/tests/prerequisites-matrix.test.ts
@@ -0,0 +1,209 @@
+import { expect, test } from "bun:test";
+
+import {
+  COMMAND_PREREQUISITE_CONTRACTS,
+  COMMANDS_THAT_INVOKE_PREREQUISITE_CHECKS,
+  getCommandPrerequisiteContracts,
+  PREREQUISITE_CHECKS,
+} from "../src/cli/prerequisites.ts";
+
+test("every prerequisite check is referenced by at least one command contract", () => {
+  const referencedChecks = new Set(
+    COMMAND_PREREQUISITE_CONTRACTS.flatMap((contract) =>
+      contract.rules.map((rule) => rule.checkId)
+    )
+  );
+
+  for (const check of PREREQUISITE_CHECKS) {
+    expect(referencedChecks.has(check.id)).toBe(true);
+  }
+});
+
+test("command coverage includes the major first-run and integration paths", () => {
+  expect(COMMANDS_THAT_INVOKE_PREREQUISITE_CHECKS).toEqual([
+    "global install",
+    "global up",
+    "global status",
+    "global logs",
+    "global logs-reset",
+    "global down",
+    "global ca",
+    "global trust",
+    "up",
+    "down",
+    "restart",
+    "ps",
+    "run",
+    "tui",
+    "open",
+    "logs",
+    "logs --loki",
+    "logs --query",
+    "session",
+    "session list",
+    "session start",
+    "session attach",
+    "session exec",
+    "session stop",
+    "ssh",
+    "session panes",
+    "session capture",
+    "session tail",
+    "setup tmux",
+    "x github status",
+    "x github profiles",
+    "x github use",
+    "x github oauth-connect",
+    "x github pr-upsert",
+    "linear status",
+    "linear profiles",
+    "linear use",
+    "linear connect",
+    "linear oauth-connect",
+    "linear connections",
+    "linear seed-local-access",
+    "linear deliveries",
+    "linear apply-delivery",
+    "linear subscriptions",
+    "linear set-subscription",
+    "linear remove-subscription",
+    "linear projects",
+    "linear sync-issue",
+    "linear sync-project",
+    "linear project-bind",
+    "linear project-link",
+    "linear run-autosync",
+  ]);
+});
+
+test("global install guides Docker problems but only warns on mux availability", () => {
+  const [contract] = getCommandPrerequisiteContracts({
+    command: "global install",
+  });
+  expect(contract).toBeDefined();
+
+  const rulesByCheck = new Map(
+    contract?.rules.map((rule) => [rule.checkId, rule.onMissing])
+  );
+
+  expect(rulesByCheck.get("docker_cli")).toBe("guide");
+  expect(rulesByCheck.get("docker_daemon")).toBe("guide");
+  expect(rulesByCheck.get("mux_backend")).toBe("warn");
+});
+
+test("status-style auth commands warn instead of intercepting missing auth", () => {
+  const [githubStatus] = getCommandPrerequisiteContracts({
+    command: "x github status",
+  });
+  const [linearStatus] = getCommandPrerequisiteContracts({
+    command: "linear status",
+  });
+
+  expect(githubStatus?.rules.every((rule) => rule.onMissing === "warn")).toBe(
+    true
+  );
+  expect(linearStatus?.rules.every((rule) => rule.onMissing === "warn")).toBe(
+    true
+  );
+});
+
+test("action commands escalate to guidance for missing integration auth", () => {
+  const [githubAction] = getCommandPrerequisiteContracts({
+    command: "x github pr-upsert",
+  });
+  const [linearAction] = getCommandPrerequisiteContracts({
+    command: "linear sync-issue",
+  });
+
+  expect(githubAction?.rules.map((rule) => rule.onMissing)).toEqual([
+    "guide",
+    "guide",
+  ]);
+  expect(linearAction?.rules.map((rule) => rule.onMissing)).toEqual([
+    "guide",
+    "guide",
+  ]);
+});
+
+test("session commands require tmux instead of only resolving a mux backend", () => {
+  const [sessionStart] = getCommandPrerequisiteContracts({
+    command: "session start",
+  });
+
+  expect(sessionStart?.rules.map((rule) => rule.checkId)).toEqual([
+    "tmux_binary",
+  ]);
+});
+
+test("cleanup and local-config commands stay out of shared prerequisite interception", () => {
+  expect(
+    getCommandPrerequisiteContracts({ command: "x github disconnect" })
+  ).toEqual([]);
+  expect(
+    getCommandPrerequisiteContracts({ command: "linear disconnect" })
+  ).toEqual([]);
+  expect(
+    getCommandPrerequisiteContracts({ command: "linear assignee-mappings" })
+  ).toEqual([]);
+  expect(
+    getCommandPrerequisiteContracts({ command: "linear project-unlink" })
+  ).toEqual([]);
+});
+
+test("broker-backed linear commands guide through Hack auth", () => {
+  const [connections] = getCommandPrerequisiteContracts({
+    command: "linear connections",
+  });
+  const [deliveries] = getCommandPrerequisiteContracts({
+    command: "linear deliveries",
+  });
+
+  expect(connections?.rules.map((rule) => rule.checkId)).toEqual([
+    "linear_broker_auth",
+  ]);
+  expect(deliveries?.rules.map((rule) => rule.checkId)).toEqual([
+    "linear_broker_auth",
+  ]);
+  expect(connections?.rules.map((rule) => rule.onMissing)).toEqual(["guide"]);
+  expect(deliveries?.rules.map((rule) => rule.onMissing)).toEqual(["guide"]);
+});
+
+test("conditional linear project binding rules only apply to remote lookup paths", () => {
+  const [projectBind] = getCommandPrerequisiteContracts({
+    command: "linear project-bind",
+  });
+  const [projectLink] = getCommandPrerequisiteContracts({
+    command: "linear project-link",
+  });
+
+  expect(projectBind?.rules.map((rule) => rule.checkId)).toEqual([
+    "linear_profile",
+    "linear_token",
+  ]);
+  expect(projectLink?.rules.map((rule) => rule.checkId)).toEqual([
+    "linear_profile",
+    "linear_token",
+  ]);
+  expect(projectBind?.rules.every((rule) => rule.when)).toBe(true);
+  expect(projectLink?.rules.every((rule) => rule.when)).toBe(true);
+});
+
+test("conditional overlays remain addressable through multi-contract lookup", () => {
+  const upContracts = getCommandPrerequisiteContracts({ command: "up" });
+  const restartContracts = getCommandPrerequisiteContracts({
+    command: "restart",
+  });
+
+  expect(upContracts.length).toBe(2);
+  expect(restartContracts.length).toBe(2);
+  expect(
+    upContracts.flatMap((contract) =>
+      contract.rules.map((rule) => rule.checkId)
+    )
+  ).toEqual(["docker_cli", "docker_daemon", "mux_backend"]);
+  expect(
+    restartContracts.flatMap((contract) =>
+      contract.rules.map((rule) => rule.checkId)
+    )
+  ).toEqual(["docker_cli", "docker_daemon", "mux_backend"]);
+});

From eaab6df623878f2bb9b5e577a67cc4f349c9f5e4 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:00:59 +0000
Subject: [PATCH 013/134] feat(env): define portable managed env artifact
 schema

---
 docs/env.md                                   |  85 +++++
 ...able-project-env-artifact-schema-design.md | 334 ++++++++++++++++++
 ...rtable-project-env-artifact-schema-plan.md | 241 +++++++++++++
 scripts/build-release.ts                      |   5 +
 src/commands/global.ts                        |  13 +-
 src/constants.ts                              |   2 +
 src/templates.ts                              |  64 ++++
 tests/global-command.test.ts                  |  10 +
 tests/project-config-schema.test.ts           |  53 ++-
 9 files changed, 803 insertions(+), 4 deletions(-)
 create mode 100644 docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md
 create mode 100644 docs/plans/2026-03-13-portable-project-env-artifact-schema-plan.md

diff --git a/docs/env.md b/docs/env.md
index 3314d7971..6dc012dd8 100644
--- a/docs/env.md
+++ b/docs/env.md
@@ -34,6 +34,7 @@ hack supports a project-scoped env contract (shareable, no values) plus safe sec
 ```
 
 Fields:
+
 - `key`: uppercase snake-case env var name (e.g. `AWS_PROFILE`).
 - `required`: if true, `hack up/run/restart` fails when missing (for targeted services).
 - `source`:
@@ -42,6 +43,83 @@ Fields:
 - `services`: `null` (or omitted) means all services; otherwise a list of Compose service names.
 - `description`: optional, for humans/UI.
 
+## Portable managed artifact
+
+Portable env management uses three layers:
+
+- `.hack/hack.env.json`: committed declaration contract for keys, required flags, service scope, and descriptions
+- `PortableProjectEnvArtifactV1`: canonical managed-value artifact for portability, import/export, and future remote publish/apply flows
+- local compatibility storage: `.hack/.env` for plaintext values plus the configured secret backend for secret values
+
+The managed artifact is intentionally separate from `.hack/hack.env.json`. The contract remains safe to commit. The managed artifact carries actual values plus intent metadata and should be encrypted as a whole when stored outside the local machine.
+
+Suggested import/export filename:
+
+- `.hack/hack.env.managed.json`
+- schema URL: `https://schemas.hack/hack.env.managed.schema.json`
+
+Artifact shape:
+
+```json
+{
+  "$schema": "https://schemas.hack/hack.env.managed.schema.json",
+  "version": 1,
+  "environment": "default",
+  "metadata": {
+    "description": "Shared dev environment for Hack App",
+    "updatedAt": "2026-03-13T18:00:00Z",
+    "updatedBy": "cli",
+    "source": "hack-cli"
+  },
+  "entries": [
+    {
+      "key": "AWS_REGION",
+      "value": {
+        "kind": "plaintext",
+        "text": "us-east-1"
+      },
+      "required": true,
+      "services": ["api"],
+      "description": "AWS region used by the API"
+    },
+    {
+      "key": "DATABASE_URL",
+      "value": {
+        "kind": "secret",
+        "text": "postgres://..."
+      },
+      "required": true,
+      "services": ["api", "worker"],
+      "description": "Primary application database"
+    }
+  ]
+}
+```
+
+Managed artifact rules:
+
+- `entries[].value.kind` distinguishes logical plaintext from logical secrets
+- `entries[].value.text` is the canonical string value before outer-envelope encryption
+- `services` belongs in the managed artifact because portability must preserve service intent outside the originating machine
+- `metadata` captures human and CLI/Desktop provenance, not machine-local backend details
+- the artifact must not store local absolute paths, keychain service names, backend provider configuration, or runtime resolution history such as `resolvedFrom`
+
+Local compatibility rules:
+
+- `.hack/.env` contains only plaintext values
+- the configured secret backend contains only secret values keyed by env var name
+- neither compatibility target stores descriptions, service scope, timestamps, or actor metadata
+- compatibility targets are derived outputs and may be regenerated from the managed artifact at any time
+
+CLI behavior when a managed artifact is active:
+
+1. Reads validate artifact keys against `.hack/hack.env.json` when present.
+2. Reads report artifact intent, local materialization state, and drift between them.
+3. `hack env set` mutates the canonical artifact first, then materializes the entry to `.hack/.env` or the configured secret backend based on `value.kind`.
+4. If an entry changes kind, Hack removes stale local state from the old compatibility target before writing the new one.
+
+See [docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md](plans/2026-03-13-portable-project-env-artifact-schema-design.md) for the full design rationale and implementation boundary.
+
 ## CLI
 
 - `hack env list [--json] [--show-secrets]`
@@ -59,6 +137,7 @@ Fields:
   - sets global backend strategy for multi-node/env secret storage
 
 Notes:
+
 - `hack env set` also supports interactive prompting when `KEY` or `VALUE` is omitted.
 - Keychain mode uses service name `hack-<projectName>` (project name from `.hack/hack.config.json`).
 - Encrypted-file mode uses `HACK_SECRETS_FILE_KEY` (if set) before keychain key lookup (`hack-secrets-backend/encrypted-file-key`).
@@ -89,6 +168,7 @@ Global config supports backend selection for secret portability:
 ```
 
 Fields:
+
 - `backend`: `keychain` | `encrypted_file` | `cloud`.
 - `allowEnvAuthRefs`: allow `env:VAR_NAME` auth/secret references for node/controller workflows.
 - `encryptedFile.path`: target path for encrypted local store mode.
@@ -106,23 +186,28 @@ When you run `hack up`, `hack restart`, or `hack run`, hack:
 4. Invokes `docker compose` with an environment that includes resolved values (including secret backend values).
 
 Security posture:
+
 - Secret values are never written into `.hack/` YAML files.
 - Plain env values live in `.hack/.env` (expected to be gitignored in most repos).
 
 ## Remote node secret behavior
 
 Current behavior (today):
+
 - Node auth tokens and extension auth refs are stored through the configured secret backend.
 - `env:VAR_NAME` auth refs are allowed only when `controlPlane.secrets.allowEnvAuthRefs=true`.
 - Remote dispatch/workspace bootstrap does **not** automatically copy all host env values to remote nodes.
 
 Recommended setup:
+
 - Keep controller secrets in `keychain` or `encrypted_file` backend (not shell env).
 - Configure each remote node to use the same secret backend strategy where possible.
 - Use project env contract (`.hack/hack.env.json`) to make required keys explicit before runs.
 
 Planned direction:
+
 - Add an explicit host-to-node secret sync command with least-privilege scoping, encrypted payload delivery, and audit events per run.
+- Keep the committed contract (`.hack/hack.env.json`) separate from the future portable managed-values artifact. See `docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md`.
 
 ## Daemon/gateway API (UI integration)
 
diff --git a/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md b/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md
new file mode 100644
index 000000000..488f98861
--- /dev/null
+++ b/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md
@@ -0,0 +1,334 @@
+# Portable Project Env Artifact Schema Design
+
+## Context
+
+The current env model has two clear layers:
+
+- `.hack/hack.env.json` is a committed contract with key names, required flags, service scope, and descriptions.
+- `.hack/.env` plus the configured secret backend hold local runtime values.
+
+That split works for local development, but it is not a portable managed-value model. It does not give Hack a stable artifact that can be exported, encrypted, published remotely, re-applied on another machine, or used as the canonical source for future CLI and desktop env workflows.
+
+This design introduces a separate portable managed env artifact instead of expanding `.hack/hack.env.json` in place.
+
+## Decision
+
+Keep `.hack/hack.env.json` as the declaration contract and introduce a second artifact for managed values:
+
+- Contract file: `.hack/hack.env.json`
+- Portable artifact format: `PortableProjectEnvArtifactV1`
+- Suggested import/export filename: `.hack/hack.env.managed.json`
+- Default durable storage: encrypted bundle transport or remote storage, not a committed plaintext repo file
+
+This avoids schema churn in the existing contract parser and keeps the portable artifact focused on values, scope, and intent.
+
+## Approaches Considered
+
+### 1. Separate portable artifact
+
+Recommended.
+
+Pros:
+
+- preserves compatibility with current `hack init`, parser, docs, and tests
+- keeps the committed contract safe to share and review
+- gives portability its own stable schema and lifecycle
+- makes `.hack/.env` and the secret backend clearly derived compatibility targets
+
+Cons:
+
+- introduces one more schema to document and maintain
+- requires explicit reconciliation rules between contract and artifact
+
+### 2. Expand `.hack/hack.env.json` into the managed artifact
+
+Pros:
+
+- fewer files to explain
+- one JSON document to parse
+
+Cons:
+
+- mixes safe shareable contract data with managed values
+- creates migration pressure for existing repos and templates
+- makes future remote encryption and local compatibility logic harder to reason about
+
+### 3. Keep only local compatibility files and derive portability ad hoc
+
+Pros:
+
+- no new schema immediately
+
+Cons:
+
+- `.hack/.env` cannot represent secrets safely or service intent
+- the secret backend cannot represent descriptions or service scope
+- export/apply/publish behavior would stay heuristic and brittle
+
+## Layer Model
+
+The env system should be treated as three distinct layers.
+
+### 1. Declaration contract
+
+`.hack/hack.env.json`
+
+Purpose:
+
+- defines which env keys exist
+- captures default required flags, service scope, and descriptions
+- remains safe to commit
+
+### 2. Portable managed artifact
+
+`PortableProjectEnvArtifactV1`
+
+Purpose:
+
+- canonical managed-value snapshot for publish, fetch, apply, import, and export
+- contains logical plaintext and secret values plus the metadata needed to materialize them anywhere
+- should be encrypted as a whole when stored outside the local machine
+
+### 3. Local compatibility materialization
+
+- `.hack/.env`
+- configured secret backend (`keychain`, `encrypted_file`, `cloud`)
+
+Purpose:
+
+- runtime compatibility for Compose, local shells, and existing commands
+- derived output only
+
+## Artifact Schema
+
+```json
+{
+  "$schema": "https://schemas.hack/hack.env.managed.schema.json",
+  "version": 1,
+  "environment": "default",
+  "metadata": {
+    "description": "Shared dev environment for Hack App",
+    "updatedAt": "2026-03-13T18:00:00Z",
+    "updatedBy": "cli",
+    "source": "hack-cli"
+  },
+  "entries": [
+    {
+      "key": "AWS_REGION",
+      "value": {
+        "kind": "plaintext",
+        "text": "us-east-1"
+      },
+      "required": true,
+      "services": ["api"],
+      "description": "AWS region used by the API"
+    },
+    {
+      "key": "DATABASE_URL",
+      "value": {
+        "kind": "secret",
+        "text": "postgres://..."
+      },
+      "required": true,
+      "services": ["api", "worker"],
+      "description": "Primary application database"
+    }
+  ]
+}
+```
+
+## Field Semantics
+
+### Top-level fields
+
+- `$schema`: schema URL for tooling and validation
+- `version`: artifact schema version; starts at `1`
+- `environment`: named managed environment, defaulting to `"default"`
+- `metadata.description`: human summary for the artifact as a whole
+- `metadata.updatedAt`: RFC 3339 timestamp for the last artifact mutation
+- `metadata.updatedBy`: actor class such as `cli`, `desktop`, or `api`
+- `metadata.source`: producing surface such as `hack-cli` or `hack-desktop`
+- `entries`: stable, key-sorted list of managed env entries
+
+### Entry fields
+
+- `key`: uppercase snake-case env var name
+- `value.kind`:
+  - `plaintext`: write to `.hack/.env` during compatibility materialization
+  - `secret`: write to the configured secret backend during compatibility materialization
+- `value.text`: canonical string value
+- `required`: whether the value is required when targeted services use it
+- `services`: `null` or omitted means all services; otherwise a sorted list of Compose service names
+- `description`: human intent note shown in CLI and UI
+
+## Why Secrets Are Still Plaintext Inside The Artifact
+
+The artifact is the normalized logical payload. Encryption belongs to the outer transport or storage envelope, not to individual entry fields.
+
+That means:
+
+- the artifact stays simple and deterministic
+- plaintext and secret entries are distinguished by intent, not by nested encryption machinery
+- the entire artifact can be encrypted, versioned, and audited as one unit for remote portability
+
+This design keeps the schema stable even if the remote encryption envelope changes later.
+
+## Portable Artifact Rules
+
+The portable artifact must include:
+
+- canonical key names
+- canonical values
+- whether each value is `plaintext` or `secret`
+- required flag
+- service scope
+- human-readable description
+- environment name
+- artifact-level update metadata
+
+The portable artifact must not include:
+
+- local absolute paths
+- machine hostnames
+- keychain service names
+- encrypted file paths
+- cloud backend provider config
+- `resolvedFrom` state such as `dotenv`, `process`, or `keychain`
+- prompt history, interactive defaults, or shell fallback behavior
+- per-machine compose override output
+
+## Local Compatibility Rules
+
+`.hack/.env` should contain only:
+
+- plaintext values
+- no secret entries
+- no descriptions
+- no service scope metadata
+- no timestamps or actor metadata
+
+The configured secret backend should contain only:
+
+- secret values keyed by env var name
+- no plaintext entries
+- no descriptions
+- no service scope metadata
+
+Local compatibility files are not canonical. The CLI may regenerate them from the managed artifact at any time.
+
+## Reconciliation With `.hack/hack.env.json`
+
+The contract and artifact intentionally overlap on a few fields. The rules should be:
+
+- contract defines the expected shape of the project env surface
+- artifact carries the managed snapshot used for portability
+- when both exist, key names must be validated against the contract
+- if `required`, `services`, or `description` disagree, the artifact wins for apply/export behavior and the CLI should surface drift
+- unknown artifact keys should warn by default and require explicit confirmation before apply
+
+This keeps the artifact self-contained while still treating the committed contract as the project declaration surface.
+
+## CLI Read Behavior
+
+When portable env management is enabled for a project, CLI reads should use this order:
+
+1. load the portable artifact or fetched remote bundle payload
+2. validate entry keys against `.hack/hack.env.json` when present
+3. materialize compatibility state in memory:
+   - plaintext entries to `.env`-style map
+   - secret entries to secret-store map
+4. compare local compatibility files against the canonical artifact
+5. report drift, missing values, and unknown keys explicitly
+
+If no managed artifact is configured, current local-only behavior remains unchanged.
+
+## CLI Write Behavior
+
+`hack env set` and `hack env set --secret` should behave as follows when a managed artifact is active:
+
+1. mutate the canonical artifact entry
+2. update top-level metadata timestamps/source
+3. regenerate the corresponding local compatibility target:
+   - plaintext to `.hack/.env`
+   - secret to the configured secret backend
+4. keep the other compatibility target untouched unless the entry kind changed
+
+If an entry changes kind:
+
+- `plaintext -> secret`: remove it from `.hack/.env`, then write it to the secret backend
+- `secret -> plaintext`: remove it from the secret backend, then write it to `.hack/.env`
+
+`hack env list` should show:
+
+- contract intent
+- artifact intent and value kind
+- local compatibility resolution status
+- drift when local files do not match the canonical artifact
+
+## Service Scope Rules
+
+Service scope belongs in the artifact because apply and export need stable intent even outside the originating machine.
+
+Rules:
+
+- omit or set `services` to `null` for all services
+- store service names sorted and de-duplicated
+- never infer service scope from `.hack/.env`
+- when targeting a service subset, only required entries whose scope intersects that subset should block execution
+
+## Migration And Compatibility
+
+No existing repo should be forced to adopt the portable artifact immediately.
+
+Initial compatibility rules:
+
+- existing projects with only `.hack/hack.env.json` plus local values continue to work unchanged
+- the portable artifact is opt-in
+- import/export and remote publish/apply should use the new artifact
+- local-only projects can be upgraded by normalizing current values into the artifact on first publish or explicit `env managed init`
+
+## Validation And Error Handling
+
+The schema should fail closed on structural errors and fail loud on semantic drift.
+
+Rules:
+
+- reject unknown schema versions
+- reject entries without a valid uppercase env key
+- reject duplicate keys inside one artifact
+- reject invalid `value.kind` values
+- reject non-array `services` values other than `null`/omitted
+- sort and de-duplicate service names at serialization boundaries
+- warn, rather than silently discard, when artifact keys are not declared in `.hack/hack.env.json`
+- require explicit confirmation before applying artifact entries that are unknown to the contract
+
+This keeps corruption visible and makes CLI behavior predictable for publish, fetch, and apply flows.
+
+## Recommended Implementation Boundary
+
+Implement the artifact as a typed model and serializer first, before wiring remote storage.
+
+Suggested first implementation units:
+
+- parser and serializer for `PortableProjectEnvArtifactV1`
+- normalization from contract + `.hack/.env` + secret store into artifact shape
+- materialization from artifact back into local compatibility files
+- drift reporting between artifact and local compatibility state
+
+## Testing Expectations
+
+The first implementation should be verifiable with deterministic unit tests around the artifact model before any remote transport work lands.
+
+Minimum test coverage:
+
+- parse valid plaintext and secret entries
+- reject invalid versions and duplicate keys
+- preserve `required`, `services`, and `description` through parse/serialize round trips
+- keep entry ordering stable by key and service ordering stable within each entry
+- normalize current local contract + value state into the artifact without leaking secret entries into `.hack/.env`
+- materialize artifact entries back into local compatibility storage, including kind changes and stale-key cleanup
+
+## Notes
+
+- The referenced Linear spec URL was not directly accessible from this environment, so this design is inferred from the issue text, current repo docs, and the existing remote env portability plan.
+- This design intentionally keeps the remote encryption envelope out of the inner artifact schema to minimize version churn.
diff --git a/docs/plans/2026-03-13-portable-project-env-artifact-schema-plan.md b/docs/plans/2026-03-13-portable-project-env-artifact-schema-plan.md
new file mode 100644
index 000000000..2a2c27092
--- /dev/null
+++ b/docs/plans/2026-03-13-portable-project-env-artifact-schema-plan.md
@@ -0,0 +1,241 @@
+# Portable Project Env Artifact Schema Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a stable portable managed env artifact model that can normalize plaintext and secret values, materialize local compatibility files, and support future remote publish/apply flows without changing the existing contract file format.
+
+**Architecture:** Keep `.hack/hack.env.json` as the committed declaration contract. Introduce a typed managed artifact model for canonical values plus metadata, then add read/write helpers that translate between the artifact and existing local compatibility targets (`.hack/.env` and the configured secret backend).
+
+**Tech Stack:** Bun, TypeScript, existing CLI env commands, Bun test, docs in `docs/env.md` and `docs/plans/`
+
+---
+
+### Task 1: Add managed artifact types and parsing
+
+**Files:**
+
+- Create: `src/lib/managed-env-artifact.ts`
+- Test: `tests/managed-env-artifact.test.ts`
+- Modify: `src/constants.ts`
+
+**Step 1: Write the failing test**
+
+Add parser/serializer tests that cover:
+
+- valid artifact parse for plaintext entries
+- valid artifact parse for secret entries
+- service scope parsing with `null` and specific service lists
+- stable serialization ordering
+- invalid version rejection
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/managed-env-artifact.test.ts` Expected: FAIL because the module and types do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Create:
+
+- artifact version constant
+- `PortableProjectEnvArtifact`
+- `PortableProjectEnvEntry`
+- `readManagedEnvArtifact`
+- `parseManagedEnvArtifact`
+- `serializeManagedEnvArtifact`
+
+Keep the schema narrow:
+
+- top-level metadata
+- entries with `key`, `value.kind`, `value.text`, `required`, `services`, `description`
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/managed-env-artifact.test.ts` Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/lib/managed-env-artifact.ts src/constants.ts tests/managed-env-artifact.test.ts
+git commit -m "feat: add managed env artifact schema"
+```
+
+### Task 2: Normalize current local env state into the artifact
+
+**Files:**
+
+- Modify: `src/lib/hack-env.ts`
+- Test: `tests/managed-env-artifact.test.ts`
+- Test: `tests/env-backend-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests that normalize:
+
+- contract + `.hack/.env` into plaintext entries
+- contract + secret store into secret entries
+- mixed plaintext and secret entries
+- contract descriptions and service scope copied into the artifact
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/managed-env-artifact.test.ts tests/env-backend-command.test.ts` Expected: FAIL because normalization helpers do not exist.
+
+**Step 3: Write minimal implementation**
+
+Add helpers that:
+
+- resolve current local values using existing env logic
+- build a canonical artifact entry list
+- preserve contract metadata in the artifact
+- keep entries sorted by key and services sorted alphabetically
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/managed-env-artifact.test.ts tests/env-backend-command.test.ts` Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/lib/hack-env.ts tests/managed-env-artifact.test.ts tests/env-backend-command.test.ts
+git commit -m "feat: normalize local env state into managed artifacts"
+```
+
+### Task 3: Materialize artifact values back into local compatibility files
+
+**Files:**
+
+- Modify: `src/lib/hack-env.ts`
+- Modify: `src/lib/secret-store.ts`
+- Test: `tests/env-backend-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests that:
+
+- write plaintext artifact entries into `.hack/.env`
+- write secret artifact entries into the configured secret backend
+- delete old local state when an entry changes kind
+- leave unrelated keys untouched
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/env-backend-command.test.ts` Expected: FAIL because artifact materialization does not exist.
+
+**Step 3: Write minimal implementation**
+
+Add a helper that takes a managed artifact and:
+
+- writes plaintext entries to `.hack/.env`
+- writes secret entries to the configured secret store
+- removes stale keys from the wrong local target when kind changes
+
+Do not add remote storage in this task.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/env-backend-command.test.ts` Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/lib/hack-env.ts src/lib/secret-store.ts tests/env-backend-command.test.ts
+git commit -m "feat: materialize managed env artifacts locally"
+```
+
+### Task 4: Add CLI visibility for managed artifact state
+
+**Files:**
+
+- Modify: `src/commands/env.ts`
+- Test: `tests/env-backend-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+
+- artifact-aware `hack env list --json`
+- drift reporting between artifact and local compatibility state
+- explicit reporting of `plaintext` vs `secret` kind
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/env-backend-command.test.ts` Expected: FAIL because the CLI output does not expose managed artifact state yet.
+
+**Step 3: Write minimal implementation**
+
+Extend `hack env list` output to show:
+
+- managed artifact presence
+- value kind
+- contract metadata
+- local drift state
+
+Keep existing output compatible where possible.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/env-backend-command.test.ts` Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/commands/env.ts tests/env-backend-command.test.ts
+git commit -m "feat: surface managed env artifact state in env list"
+```
+
+### Task 5: Document artifact rules and upgrade path
+
+**Files:**
+
+- Modify: `docs/env.md`
+- Modify: `docs/guides/init-project.md`
+- Modify: `src/templates.ts`
+
+**Step 1: Write the failing test**
+
+No code test is required for this task. Use doc review plus template output review.
+
+**Step 2: Run verification to confirm the current docs are incomplete**
+
+Run: `grep -n \"managed artifact\\|portable artifact\" docs/env.md docs/guides/init-project.md src/templates.ts` Expected: incomplete or missing references to the new artifact model.
+
+**Step 3: Write minimal implementation**
+
+Document:
+
+- contract vs artifact vs local compatibility split
+- opt-in upgrade path
+- any template notes needed for future initialization behavior
+
+Do not start scaffolding the artifact by default unless the implementation requires it.
+
+**Step 4: Run verification to confirm docs are updated**
+
+Run: `grep -n \"managed artifact\\|portable artifact\" docs/env.md docs/guides/init-project.md src/templates.ts` Expected: matches in the updated docs.
+
+**Step 5: Commit**
+
+```bash
+git add docs/env.md docs/guides/init-project.md src/templates.ts
+git commit -m "docs: describe managed env artifact model"
+```
+
+## Recommended Execution Order
+
+1. Add the standalone artifact module first.
+2. Normalize current local state into the artifact.
+3. Add local materialization helpers.
+4. Surface the new state in CLI output.
+5. Update docs only after the code contract is settled.
+
+## Risks To Watch
+
+- accidental breaking changes to existing `.hack/hack.env.json` parsing
+- leaking secret values into `.hack/.env` during kind changes
+- making `hack env list --json` incompatible for existing consumers
+- treating local compatibility files as canonical instead of derived
+
+## Links
+
+- `docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md`
+- `docs/plans/2026-03-06-remote-encrypted-project-env-portability-plan.md`
diff --git a/scripts/build-release.ts b/scripts/build-release.ts
index 5f18e9e6d..ad7384791 100644
--- a/scripts/build-release.ts
+++ b/scripts/build-release.ts
@@ -7,6 +7,7 @@ import {
   renderProjectBranchesSchemaJson,
   renderProjectConfigSchemaJson,
   renderProjectEnvSchemaJson,
+  renderProjectManagedEnvSchemaJson,
 } from "../src/templates.ts";
 
 interface BuildArgs {
@@ -109,6 +110,10 @@ async function main({ args }: { readonly args: BuildArgs }): Promise<number> {
     resolve(schemasDir, "hack.env.schema.json"),
     renderProjectEnvSchemaJson()
   );
+  await Bun.write(
+    resolve(schemasDir, "hack.env.managed.schema.json"),
+    renderProjectManagedEnvSchemaJson()
+  );
   await Bun.write(
     resolve(schemasDir, "hack.branches.schema.json"),
     renderProjectBranchesSchemaJson()
diff --git a/src/commands/global.ts b/src/commands/global.ts
index 08ed8fc9e..57bcf7e20 100644
--- a/src/commands/global.ts
+++ b/src/commands/global.ts
@@ -4,9 +4,6 @@ import { confirm, isCancel, note, spinner } from "@clack/prompts";
 import type { CliContext, CommandArgs } from "../cli/command.ts";
 import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
 
-/** Regex to split strings on whitespace. */
-const WHITESPACE_PATTERN = /\s+/;
-
 import {
   optFollow,
   optJson,
@@ -40,6 +37,7 @@ import {
   GLOBAL_LOGGING_COMPOSE_FILENAME,
   GLOBAL_LOGGING_DIR_NAME,
   GLOBAL_LOKI_CONFIG_FILENAME,
+  GLOBAL_MANAGED_ENV_SCHEMA_FILENAME,
   GLOBAL_SCHEMAS_DIR_NAME,
 } from "../constants.ts";
 import { resolveGatewayConfig } from "../control-plane/extensions/gateway/config.ts";
@@ -82,6 +80,7 @@ import {
   renderProjectBranchesSchemaJson,
   renderProjectConfigSchemaJson,
   renderProjectEnvSchemaJson,
+  renderProjectManagedEnvSchemaJson,
 } from "../templates.ts";
 import { display } from "../ui/display.ts";
 import { dockerComposeLogsPretty } from "../ui/docker-logs.ts";
@@ -89,6 +88,9 @@ import { ensureBundledGumInstalled } from "../ui/gum.ts";
 import { logger } from "../ui/logger.ts";
 import { resolvePreferredHostDnsTarget } from "./doctor-utils.ts";
 
+/** Regex to split strings on whitespace. */
+const WHITESPACE_PATTERN = /\s+/;
+
 const globalLogsOptions = [optFollow, optNoFollow, optTail, optPretty] as const;
 const globalLogsPositionals = [{ name: "service", required: false }] as const;
 
@@ -283,6 +285,7 @@ function getGlobalPaths() {
     grafanaDashboard: resolve(loggingDir, GLOBAL_GRAFANA_DASHBOARD_FILENAME),
     configSchema: resolve(schemasDir, GLOBAL_CONFIG_SCHEMA_FILENAME),
     envSchema: resolve(schemasDir, GLOBAL_ENV_SCHEMA_FILENAME),
+    managedEnvSchema: resolve(schemasDir, GLOBAL_MANAGED_ENV_SCHEMA_FILENAME),
     branchesSchema: resolve(schemasDir, GLOBAL_BRANCHES_SCHEMA_FILENAME),
   };
 }
@@ -607,6 +610,10 @@ async function globalInstall(): Promise<number> {
     paths.envSchema,
     renderProjectEnvSchemaJson()
   );
+  await writeWithPromptIfDifferent(
+    paths.managedEnvSchema,
+    renderProjectManagedEnvSchemaJson()
+  );
   await writeWithPromptIfDifferent(
     paths.branchesSchema,
     renderProjectBranchesSchemaJson()
diff --git a/src/constants.ts b/src/constants.ts
index 1bffc7df3..cfe53f435 100644
--- a/src/constants.ts
+++ b/src/constants.ts
@@ -88,5 +88,7 @@ export const PROJECT_BRANCHES_FILENAME = "hack.branches.json" as const;
 
 export const GLOBAL_CONFIG_SCHEMA_FILENAME = "hack.config.schema.json" as const;
 export const GLOBAL_ENV_SCHEMA_FILENAME = "hack.env.schema.json" as const;
+export const GLOBAL_MANAGED_ENV_SCHEMA_FILENAME =
+  "hack.env.managed.schema.json" as const;
 export const GLOBAL_BRANCHES_SCHEMA_FILENAME =
   "hack.branches.schema.json" as const;
diff --git a/src/templates.ts b/src/templates.ts
index fcca682dc..b46b8365d 100644
--- a/src/templates.ts
+++ b/src/templates.ts
@@ -669,6 +669,70 @@ export function renderProjectEnvSchemaJson(): string {
   return `${JSON.stringify(schema, null, 2)}\n`;
 }
 
+export function renderProjectManagedEnvSchemaJson(): string {
+  const schema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "hack.env.managed.json",
+    type: "object",
+    additionalProperties: false,
+    required: ["version", "environment", "metadata", "entries"],
+    properties: {
+      $schema: { type: "string" },
+      version: { type: "integer", const: 1 },
+      environment: { type: "string", minLength: 1 },
+      metadata: {
+        type: "object",
+        additionalProperties: false,
+        required: ["updatedAt", "updatedBy", "source"],
+        properties: {
+          description: { type: "string" },
+          updatedAt: { type: "string", format: "date-time" },
+          updatedBy: { type: "string", minLength: 1 },
+          source: { type: "string", minLength: 1 },
+        },
+      },
+      entries: {
+        type: "array",
+        items: {
+          type: "object",
+          additionalProperties: false,
+          required: ["key", "value", "required"],
+          properties: {
+            key: {
+              type: "string",
+              pattern: "^[A-Z_][A-Z0-9_]*$",
+              minLength: 1,
+            },
+            value: {
+              type: "object",
+              additionalProperties: false,
+              required: ["kind", "text"],
+              properties: {
+                kind: { type: "string", enum: ["plaintext", "secret"] },
+                text: { type: "string" },
+              },
+            },
+            required: { type: "boolean" },
+            services: {
+              anyOf: [
+                { type: "null" },
+                {
+                  type: "array",
+                  items: { type: "string", minLength: 1 },
+                  uniqueItems: true,
+                },
+              ],
+            },
+            description: { type: "string" },
+          },
+        },
+      },
+    },
+  } as const;
+
+  return `${JSON.stringify(schema, null, 2)}\n`;
+}
+
 export function renderProjectBranchesSchemaJson(): string {
   const schema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
diff --git a/tests/global-command.test.ts b/tests/global-command.test.ts
index 47e250905..2d727fb2a 100644
--- a/tests/global-command.test.ts
+++ b/tests/global-command.test.ts
@@ -13,6 +13,8 @@ import {
   GLOBAL_HACK_DIR_NAME,
   GLOBAL_LOGGING_COMPOSE_FILENAME,
   GLOBAL_LOGGING_DIR_NAME,
+  GLOBAL_MANAGED_ENV_SCHEMA_FILENAME,
+  GLOBAL_SCHEMAS_DIR_NAME,
 } from "../src/constants.ts";
 
 let tempDir: string | null = null;
@@ -273,9 +275,17 @@ test("global install writes compose files and starts stacks", async () => {
   );
   const hasCaddy = await Bun.file(caddyCompose).exists();
   const hasLogging = await Bun.file(loggingCompose).exists();
+  const managedEnvSchema = join(
+    tempDir!,
+    GLOBAL_HACK_DIR_NAME,
+    GLOBAL_SCHEMAS_DIR_NAME,
+    GLOBAL_MANAGED_ENV_SCHEMA_FILENAME
+  );
+  const hasManagedEnvSchema = await Bun.file(managedEnvSchema).exists();
 
   expect(hasCaddy).toBe(true);
   expect(hasLogging).toBe(true);
+  expect(hasManagedEnvSchema).toBe(true);
   expect(
     runCalls.some((call) => call.includes(caddyCompose) && call.includes("up"))
   ).toBe(true);
diff --git a/tests/project-config-schema.test.ts b/tests/project-config-schema.test.ts
index 95faf3e11..69cebb781 100644
--- a/tests/project-config-schema.test.ts
+++ b/tests/project-config-schema.test.ts
@@ -1,5 +1,8 @@
 import { expect, test } from "bun:test";
-import { renderProjectConfigSchemaJson } from "../src/templates.ts";
+import {
+  renderProjectConfigSchemaJson,
+  renderProjectManagedEnvSchemaJson,
+} from "../src/templates.ts";
 
 test("project config schema includes startup validation", () => {
   const schema = JSON.parse(renderProjectConfigSchemaJson()) as Record<
@@ -49,3 +52,51 @@ test("project config schema includes strict lifecycle hooks and processes", () =
   expect(processItems.additionalProperties).toBe(false);
   expect(processItems.required).toEqual(["name", "command"]);
 });
+
+test("managed env schema models entry kind, metadata, and service scope", () => {
+  const schema = JSON.parse(renderProjectManagedEnvSchemaJson()) as Record<
+    string,
+    unknown
+  >;
+  const properties = schema.properties as Record<string, unknown>;
+
+  expect(schema.additionalProperties).toBe(false);
+  expect(schema.required).toEqual([
+    "version",
+    "environment",
+    "metadata",
+    "entries",
+  ]);
+
+  const metadata = properties.metadata as Record<string, unknown>;
+  expect(metadata.additionalProperties).toBe(false);
+  const metadataProperties = metadata.properties as Record<string, unknown>;
+  expect(metadataProperties.updatedAt).toEqual({
+    type: "string",
+    format: "date-time",
+  });
+
+  const entries = properties.entries as Record<string, unknown>;
+  const entry = entries.items as Record<string, unknown>;
+  expect(entry.additionalProperties).toBe(false);
+  expect(entry.required).toEqual(["key", "value", "required"]);
+
+  const entryProperties = entry.properties as Record<string, unknown>;
+  const value = entryProperties.value as Record<string, unknown>;
+  expect(value.additionalProperties).toBe(false);
+  const valueProperties = value.properties as Record<string, unknown>;
+  expect(valueProperties.kind).toEqual({
+    type: "string",
+    enum: ["plaintext", "secret"],
+  });
+
+  const services = entryProperties.services as Record<string, unknown>;
+  expect(services.anyOf).toEqual([
+    { type: "null" },
+    {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      uniqueItems: true,
+    },
+  ]);
+});

From daa5ed3dedbcfc0e6a26d35ebbfbc8152e2020c9 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:07:52 +0000
Subject: [PATCH 014/134] docs: clarify core offer and docs ia

---
 README.md                             | 960 +++-----------------------
 apps/macos/README.md                  |   4 +-
 docs/README.md                        |  75 +-
 docs/cli.md                           | 125 +++-
 docs/extensions.md                    |   8 +-
 docs/gateway-api.md                   |   3 +-
 docs/gateway.md                       |   3 +-
 docs/guides/remote-cloudflare.md      |   3 +-
 docs/guides/remote-node-container.md  |   4 +-
 docs/guides/remote-node-laptop-e2e.md |   4 +-
 docs/guides/remote-node-quickstart.md |   4 +-
 docs/guides/remote-node-railway.md    |   4 +-
 docs/guides/remote-ssh.md             |   3 +-
 docs/guides/remote-supervisor.md      |   4 +-
 docs/guides/remote-tailscale.md       |   4 +-
 docs/integrations.md                  | 126 ++++
 docs/supervisor.md                    |   4 +-
 src/cli/command.ts                    |   3 +
 src/cli/help.ts                       |  25 +-
 src/cli/spec.ts                       |   8 +-
 src/commands/auth.ts                  |  14 +-
 src/commands/dispatch.ts              |  10 +-
 src/commands/env.ts                   |   4 +-
 src/commands/gateway.ts               |  10 +-
 src/commands/linear.ts                |   4 +-
 src/commands/node.ts                  |   4 +-
 src/commands/remote.ts                |  12 +-
 src/commands/session.ts               |   4 +-
 src/commands/ssh.ts                   |   4 +-
 src/commands/tickets.ts               |   4 +-
 tests/cli-help.test.ts                |  52 ++
 31 files changed, 532 insertions(+), 964 deletions(-)
 create mode 100644 docs/integrations.md
 create mode 100644 tests/cli-help.test.ts

diff --git a/README.md b/README.md
index 31d64cc93..3c134f4f4 100644
--- a/README.md
+++ b/README.md
@@ -1,942 +1,204 @@
-<a id="readme-top"></a>
+# Hack
 
-<!-- PROJECT LOGO -->
-<br />
-<div align="center">
-<pre style="font-family:monospace;padding:0;margin:0;white-space:pre;font-size:12px;background:none!important;">
- █████   █████   █████████     █████████  █████   ████
-░░███   ░░███   ███░░░░░███   ███░░░░░███░░███   ███░ 
- ░███    ░███  ░███    ░███  ███     ░░░  ░███  ███   
- ░███████████  ░███████████ ░███          ░███████    
- ░███░░░░░███  ░███░░░░░███ ░███          ░███░░███   
- ░███    ░███  ░███    ░███ ░░███     ███ ░███ ░░███  
- █████   █████ █████   █████ ░░█████████  █████ ░░████
-░░░░░   ░░░░░ ░░░░░   ░░░░░   ░░░░░░░░░  ░░░░░   ░░░░ 
-</p>
-<br/>
-</div>
-  <p align="center">
-    Opinionated local-dev orchestration for running <b>multiple projects</b> at the same time without port conflicts.
-    <br />
-  </p>
+Hack is local development without the port-collision tax.
 
----
-**Network isolation per repo / branch**: every instance runs on its own Docker network (so Postgres/Redis/etc can stay on default ports *inside* the project).
+It gives each repo or branch its own network, a stable HTTPS URL, and a single place to manage
+the workflows that usually end up scattered across shell scripts, terminal tabs, and sidecar tools.
 
-**Stable HTTPS hostnames**: `https://<project>.hack` (and subdomains like `https://api.<project>.hack`) routed by a global Caddy proxy.
+## Three core promises
 
-**Good logs UX**: instant `docker compose logs` tailing, plus Loki/Grafana for querying + history.
+1. Run multiple repos or branches at the same time without port conflicts.
+2. Open every project on a stable HTTPS URL like `https://myapp.hack`.
+3. Keep project workflows such as env, sessions, tickets, and integrations close to the repo.
 
-**Opt-in per repo**: no invasive changes to your codebase; config lives in `.hack/`.
-
----
-
-### Why this exists
-
-Most of my projects run the same stack. That’s fine until you want to:
-
-- run two projects at the same time
-- run two branches of the same repo
-- run multiple worktrees in parallel
-
-At that point everything fights over `localhost` and default ports.
-
-The daily choice:
-
-- **Option A:** stop A → start B → ship fix → stop B → restart A  
-  you just spent 5–10 minutes paying the orchestration tax and nuking your focus.
-- **Option B:** don’t run it. code blind. push. let CI tell you what you broke.
-
-Neither scales. Both slow you down in dumb, repeatable ways.
-
-
-## Installation
+## Five-minute start
 
 ### Prerequisites
-- **macOS**: supported.
-- **Docker + Compose**: [Orbstack](https://docs.orbstack.dev/quick-start) | [Docker Desktop](https://www.docker.com/get-started/) 
+
+- macOS
+- Docker + Compose via [OrbStack](https://docs.orbstack.dev/quick-start) or
+  [Docker Desktop](https://www.docker.com/get-started/)
 
 ### Install
 
-**Option A: Shell script (CLI only)**
+CLI:
 
 ```bash
 curl -fsSL https://github.com/hack-dance/hack/releases/latest/download/hack-install.sh | bash
 ```
 
-**Option B: macOS DMG (CLI + Desktop App)**
+macOS app:
 
-Download the latest DMG from [GitHub Releases](https://github.com/hack-dance/hack/releases/latest).
+- Download the latest DMG from
+  [GitHub Releases](https://github.com/hack-dance/hack/releases/latest)
+- `Hack Desktop for macOS` is currently **Beta**
 
-The DMG includes:
-- **Hack Desktop** - macOS menu bar app for managing projects
-- **Install Hack CLI** - double-click to install the CLI to `~/.hack/bin`
+### Start a project
 
-### Setup
 ```bash
 hack global install
-```
-
-### Quick start 
-Manual (CLI):
 
-```bash
 cd /path/to/your-repo
 hack init
 hack up --detach
 hack open
 ```
 
-Agent-assisted (Cursor/Claude/Codex with shell access):
-
-```bash
-hack setup cursor   # or hack setup claude / hack setup codex
-hack setup agents   # optional: adds AGENTS.md + CLAUDE.md snippets
-hack setup sync --all-scopes   # optional: refresh project + user integrations
-hack agent init --client cursor   # or --client claude / --client codex
-hack agent patterns              # optional: dependency/ops checklist
-```
-
-If you omit `--client`, `hack agent init` will prompt you to choose (TTY only).
-If your agent does not auto-open, paste the output into the chat. Example:
-
-```
-I ran `hack agent init` and pasted the output below. Please follow it to set up hack for this repo,
-then run:
-- `hack init` (use --auto if dev scripts are detected)
-- `hack up --detach`
-- `hack open --json`
-If anything fails, use `hack logs --pretty` and summarize next steps.
-
-<PASTE HACK AGENT INIT OUTPUT HERE>
-```
-
-If the agent cannot run shell commands, use MCP instead: `hack setup mcp` and `hack mcp serve`.
-
-### Remote node runtime image (multi-node)
-
-Use the prebuilt node-runtime container to bootstrap remote nodes quickly (Linux/macOS hosts with Docker):
-
-```bash
-bun run build:node-runtime-image --tag hack-node-runtime:dev
-```
-
-Full operator guide: [`docs/guides/remote-node-container.md`](docs/guides/remote-node-container.md)
-
-### Tickets (optional, git-backed issue tracking)
+What those commands do:
 
-`hack` includes a lightweight, git-backed ticket system for tracking work without leaving your repo. Tickets are stored in a hidden git ref (`refs/hack/tickets`) so they sync with your code but don't clutter your branch list.
+- `hack global install` boots the machine-level DNS, TLS, and logging services
+- `hack init` creates the `.hack/` project config
+- `hack up --detach` starts your stack on an isolated network
+- `hack open` opens the project URL in your browser
 
-**Quick setup:**
+Useful next commands:
 
 ```bash
-# Enable tickets for this repo
-hack x tickets setup
-
-# Create a ticket
-hack x tickets create --title "Add dark mode support"
-
-# List tickets
-hack x tickets list
-
-# Interactive TUI for managing tickets
-hack x tickets tui
-
-# Update status
-hack x tickets status T-00001 in_progress
-
-# Sync to remote
-hack x tickets sync
-```
-
-**Why use it:**
-- No external service required - tickets live in git
-- Agent-friendly - Claude/Cursor/Codex can create and manage tickets
-- Syncs with `git push/pull` via hidden refs
-- Works offline
-
-Tickets are ideal for solo devs, small teams, or agent-driven workflows where you want lightweight task tracking without context-switching to Jira/Linear/GitHub Issues.
-
-Full docs: [`docs/guides/tickets.md`](docs/guides/tickets.md)
-
-### macOS app (experimental)
-Source lives in `apps/macos`. See `apps/macos/README.md` for XcodeGen and build/run steps.
-Quick commands (repo root):
-
-```bash
-bun run macos:project-gen
-bun run macos:open
-bun run macos:dev
-bun run macos:build
-bun run macos:test
-```
-
-### Configuration (.hack/hack.config.json)
-- `name`: project slug (also used for Docker Compose project name)
-- `dev_host`: base hostname (`<dev_host>.hack`)
-
-*Optional `[logs]` settings*
-- `follow_backend`: `compose|loki` (default: `compose`)
-- `snapshot_backend`: `compose|loki` (default: `loki`)
-- `clear_on_down`: when running `hack down`, request Loki delete for this project (best-effort)
-- `retention_period`: e.g. `"24h"`; on `hack down`, prune older logs (best-effort)
-
-*Optional `[internal]` settings (container DNS/TLS)*
-- `dns`: use CoreDNS to resolve `*.hack` inside containers (default: `true`)
-- `tls`: mount Caddy Local CA + set common SSL env vars (default: `true`)
-- `extra_hosts`: static Compose `extra_hosts` entries (hostname → IP/target), merged into the internal override
-
-If you need **dynamic** `extra_hosts` (e.g. Pulumi outputs / local tunnels that change), use:
-
-```bash
-hack internal extra-hosts set <hostname> <target>
-hack internal extra-hosts unset <hostname>
-hack internal extra-hosts list
-```
-
-This writes `.hack/.internal/extra-hosts.json` and is merged into `extra_hosts` when you run `hack up` / `hack restart`.
-
-*Optional `[oauth]` settings (OAuth-safe alias host)*
-- `enabled`: when true, `hack init` generates Caddy labels so routed services answer on both:
-- primary: `https://<dev_host>`
-- OAuth alias: `https://<dev_host>.<tld>` (e.g. `https://sickemail.hack.gy`)
-- `tld`: optional (default: `"gy"`). Only `*.hack.gy` is bootstrapped automatically by `hack global install`; other TLDs require manual DNS setup.
-
-The file includes a JSON Schema reference for editor validation:
-
-```json
-{
-  "$schema": "https://schemas.hack/hack.config.schema.json"
-}
-```
-
-Schemas are served locally by the global Caddy proxy at `https://schemas.hack`.
-
-Quick edits:
-
-```bash
-hack config get dev_host
-hack config set dev_host "myapp.hack"
-hack config set logs.snapshot_backend "compose"
-```
-
-## Commands (high level)
-
-Run `hack help` (or `hack help <command>`) for full usage.
-
-Common:
-- `hack global install|up|down`
-- `hack init|up|down|logs|open|tui`
-- `hack status`
-- `hack remote setup`
-- `hack gateway enable`
-
-Full command table + flags: `docs/cli.md`.
-
-Run `hack help <command>` for detailed help.
-
-Project commands that call Docker Compose accept `--profile` (up/down/restart/ps/logs/run).
-
-## JSON output
-
-Use `--json` for machine-readable output:
-
-- `hack projects --json`
-- `hack ps --json`
-- `hack logs --json` (NDJSON stream; use `--no-follow` for snapshots)
-- `hack open --json` (returns `{ "url": "..." }`)
-
-When the daemon is running, `hack projects --json` and `hack ps --json` use it for faster results.
-
-`hack logs --json` emits event envelopes (`start`, `log`, `end`) so MCP/TUI consumers can stream safely.
-
-## Daemon (optional)
-
-`hackd` is a local daemon that caches Docker state for fast status/ps queries.
-
-```bash
-hack daemon start
-hack daemon status
-hack daemon metrics
-hack daemon stop
-hack daemon logs
+hack logs --pretty
+hack run <service> <command...>
+hack status
+hack down
 ```
 
-### launchd integration (macOS)
+## What is core today
 
-On macOS, you can install `hackd` as a launchd service for automatic management:
+These workflows are the main product:
 
-```bash
-# Install (auto-start on login by default)
-hack daemon install
+- Project setup and runtime: `hack init`, `hack up`, `hack down`, `hack restart`, `hack ps`
+- Stable local access: `hack open`, `hack logs`, `hack run`, `hack status`
+- Parallel project work: branch instances, isolated networks, and per-project hostnames
+- Repo-local workflow support: `hack env`, `hack session`, `hack tickets`
 
-# Install without auto-start (manual start/stop via launchd)
-hack daemon install --no-run-at-load
+Supporting capabilities:
 
-# Uninstall the launchd service
-hack daemon uninstall
-```
+- GitHub and Linear integrations
+- Agent setup for Cursor, Claude Code, and Codex
+- CLI and SDK reference surfaces for extensions and automation
 
-Options:
-- `--run-at-load` / `--no-run-at-load`: Start automatically on login
-- `--gui-only` / `--no-gui-only`: Only run in GUI sessions (default: GUI only)
+Beta surfaces:
 
-The service uses label `dance.hack.hackd` and writes to `~/Library/LaunchAgents/`.
+- Remote control plane and gateway flows
+- Multi-node execution and dispatch
+- Hack Desktop for macOS
 
-Use it when:
-- You run `hack projects --json` / `hack ps --json` frequently (scripts, agent workflows, TUI).
-- You want faster status snapshots without shelling out to Docker each time.
+## Integrations overview
 
-Skip it when:
-- You prefer zero background processes.
-- You rarely use JSON status/ps outputs.
+Hack has a few supporting surfaces that matter after your project is already running.
 
-If it is not running (or version-mismatched), the CLI falls back to direct Docker calls.
+### GitHub
 
-## Control plane + extensions (optional)
+Use GitHub integration when you want Hack to authenticate repo workflows or create and update pull
+requests for you.
 
-`hack` includes a small control-plane kernel so features like jobs, tickets, and remote access can
-ship as extensions without bloating the core CLI.
+- Main surface: `hack x github ...`
+- Common use: connect a profile, then use PR or repo automation from Hack workflows
+- Reference: [docs/extensions.md](docs/extensions.md)
 
-- Extension commands run via `hack x <namespace> <command>`.
-- Global control-plane config lives at `~/.hack/hack.config.json` (`hack config set --global ...`).
-- Per-project overrides live in `.hack/hack.config.json` and win over global values.
-- `controlPlane.gateway.enabled` is project-scoped and implicitly enables the gateway extension.
+### Linear
 
-See `SPECS/control-plane/consolidated.md` and `docs/extensions.md` for the extension SDK surface.
+Use Linear when you want selected Linear issues or projects to sync into your repo-local workflow
+instead of treating Linear as a separate universe.
 
-### Gateway (remote access)
+- Main surface: `hack linear ...`
+- Common use: connect a profile, bind a project, sync issues or project state
+- Reference: [docs/integrations.md](docs/integrations.md)
 
-The gateway exposes `hackd` over HTTP/WS with token auth. It binds to `127.0.0.1` by default and
-should be exposed via a Zero Trust/VPN or SSH tunnel when needed. `hack remote setup` is the
-one-command flow that enables the gateway, creates a token, and can configure + start exposure
-(Cloudflare/Tailscale/SSH) via prompts. It prints a QR by default (use `--no-qr` to skip).
+### Tickets
 
-```bash
-hack remote setup
-# or:
-hack gateway setup
-# or manually:
-hack gateway enable
-hack daemon stop && hack daemon start
-hack x gateway token-create
-```
+Use tickets when you want lightweight work tracking in git without leaving the repo.
 
-Gateway tokens default to read-only. For non-GET requests, set
-`controlPlane.gateway.allowWrites = true` globally and create a write-scoped token:
+- Main surface: `hack tickets ...`
+- Common use: create follow-up work, track status, sync hidden ticket refs
+- Reference: [docs/guides/tickets.md](docs/guides/tickets.md)
 
-```bash
-hack config set --global 'controlPlane.gateway.allowWrites' true
-```
+### Sessions
 
-```bash
-hack x gateway token-create --scope write
-```
+Use sessions when you want a durable terminal workspace for yourself or an agent.
 
-Current gateway API (HTTP/WS):
-- status/metrics/projects/ps (`/v1/*`)
-- supervisor jobs: list/create/show/cancel + log/event stream (`/control-plane/*`)
-- supervisor shells: create/show + PTY stream (write token + allowWrites)
-- CLI shell client: `hack x supervisor shell` (gateway + write token required)
+- Main surface: `hack session ...`
+- Common use: keep a project shell alive, reattach later, or run long-lived agent work
+- Reference: [docs/sessions.md](docs/sessions.md)
 
-Interactive shells are available over the gateway WebSocket; the CLI can attach with
-`hack x supervisor shell` (write token + allowWrites required). Use SSH/Zero Trust for a full
-terminal UI, or run commands via supervisor jobs.
+### Env
 
-See `docs/gateway-api.md` for full API usage, structured workflow patterns, and a runnable demo.
+Use env management when you want the repo to declare what configuration it needs without committing
+the secret values themselves.
 
-Remote access options (recommended order):
-1) SSH tunnel to the gateway port for quick, ad-hoc access.
-2) Zero Trust/VPN (Tailscale, Cloudflare, etc.) for persistent access.
-3) Optional Caddy route (`https://gateway.hack`) for local convenience.
+- Main surface: `hack env ...`
+- Common use: define required vars in `.hack/hack.env.json`, keep values in `.hack/.env` or a
+  secret backend
+- Reference: [docs/env.md](docs/env.md)
 
-Note: Cloudflare Tunnel is ideal for the gateway HTTP/WS surface. It is not a direct SSH
-replacement on iOS; use Tailscale/VPN for SSH access from mobile clients.
-If you already use Cloudflare WARP, configure a private network route to your laptop and
-use that IP/hostname for SSH in your mobile client.
+## Docs map
 
-Remote helper:
-- `hack remote` shows status and offers to run setup when needed.
-- `hack remote status` prints gateway + exposure status.
-- `hack remote qr` prints a QR payload for SSH or gateway usage (confirm before sharing).
-- `hack remote monitor` opens a mini TUI (status + gateway audit log tail).
+Start here when you want the product story before the low-level reference:
 
-Cloudflare tunnel helper:
+- Core workflows: [docs/README.md](docs/README.md)
+- CLI quick map and full reference: [docs/cli.md](docs/cli.md)
+- Integrations overview: [docs/integrations.md](docs/integrations.md)
 
-```bash
-hack x cloudflare tunnel-setup --hostname gateway.example.com
-hack x cloudflare tunnel-start
-```
+Beta surfaces are intentionally separate:
 
-Tailscale helper:
+- Remote control plane and gateway: [docs/gateway.md](docs/gateway.md)
+- Multi-node quickstart: [docs/guides/remote-node-quickstart.md](docs/guides/remote-node-quickstart.md)
+- Hack Desktop for macOS: [apps/macos/README.md](apps/macos/README.md)
 
-```bash
-hack x tailscale setup
-hack x tailscale status
-```
-
-DNS note: `cloudflared tunnel route dns <tunnel> <hostname>` creates the required CNAME to
-`<tunnel-id>.cfargotunnel.com` in your Cloudflare zone (proxied).
+Reference surfaces:
 
-### Supervisor (jobs + shells)
+- Extensions and SDK: [docs/extensions.md](docs/extensions.md)
+- Gateway API: [docs/gateway-api.md](docs/gateway-api.md)
+- Architecture: [docs/architecture.md](docs/architecture.md)
 
-The supervisor is the job/shell runner that powers agent workflows and remote execution. It can run
-commands, stream logs, and host PTY-backed shells. Use it locally with `hack x supervisor` or
-remotely over the gateway.
+## `hack help` guide
 
-Docs: `docs/supervisor.md`.
+Root help is organized in the same order as the product:
 
-## Docs
+- `Global commands`: machine setup and shared services
+- `Core workflows`: the day-to-day local-dev path
+- `Collaboration & integrations`: env, sessions, tickets, Linear, and SSH access
+- `Beta workflows`: remote control plane, multi-node, and dispatch
+- `Extension commands`: lower-level extension namespace access
 
-Start here:
-- `docs/README.md` (index)
-- `docs/architecture.md`
-- `docs/gateway.md`
-- `docs/extensions.md`
+Run `hack help` or `hack help <command>` for the CLI version of that map.
 
-## Agent setup (CLI-first)
+## Agent setup
 
-Use `hack setup` to install local integrations. Default is project scope; add `--global` for user scope.
+If you want Hack to teach coding agents how to work in a repo:
 
 ```bash
 hack setup cursor
 hack setup claude
 hack setup codex
-hack setup agents
 hack setup sync --all-scopes
+hack agent init --client codex
 ```
 
-What each setup command does:
-- `hack setup cursor`: installs Cursor rules in `.cursor/rules/hack.mdc`
-- `hack setup claude`: installs Claude Code hooks in `.claude/settings.local.json` (or user scope)
-- `hack setup codex`: installs the Codex skill in `.codex/skills/hack-cli/SKILL.md`
-- `hack setup agents`: adds/updates hack usage snippets in `AGENTS.md` and `CLAUDE.md`
-- `hack setup mcp`: writes MCP configs for no-shell clients
-- `hack setup sync --all-scopes`: refreshes docs, skills, and MCP config at project + user scope
-
-Automatic guardrail:
-- Project-level `hack` commands (interactive sessions) auto-check docs/skills/MCP drift and attempt auto-sync.
-- To warn-only: `HACK_SETUP_SYNC_MODE=warn`
-- To disable: `HACK_SETUP_SYNC_MODE=off`
-
-Primer helpers:
-- `hack agent prime`: short CLI-first primer used by Claude Code hooks
-- `hack agent init`: repo-specific setup prompt agents can follow to scaffold/verify hack config
-- `hack agent init --client cursor|claude|codex`: open the prompt directly in an agent client
-- `hack agent patterns`: dependency/ops checklist for agents
-
-Recommended flow:
-- Use `hack setup cursor|claude|codex` for your agent client
-- Use `hack setup agents` to document hack usage inside the repo
-- Use `hack setup sync --all-scopes` after `hack update` to refresh generated integrations
-- Use `hack setup mcp` only when the agent has no shell access
-
-## MCP (no-shell clients)
-
-Use MCP only when the CLI is not available (e.g. no shell access).
-
-Run the MCP server locally over stdio:
-
-```bash
-hack mcp serve
-```
-
-Most MCP clients spawn this on demand. Running it directly will wait for a client connection.
-
-Install MCP configs (Cursor, Claude CLI, Codex):
+If your agent does not have shell access, use MCP instead:
 
 ```bash
-# Project-scoped (default via setup)
 hack setup mcp
-
-# User-scoped (default; writes to your home config directories)
-hack mcp install --all
-
-# Project-scoped (writes .cursor/.claude/.codex in the repo)
-hack mcp install --all --scope project
-```
-
-Project scope writes `.cursor/mcp.json`, `.claude/settings.json`, and `.codex/config.toml`.
-For `--scope project`, `hack mcp install` also updates `AGENTS.md` and `CLAUDE.md` by default.
-
-Print config snippets without writing:
-
-```bash
-hack mcp print --codex
-```
-
-`hack init` can prompt to install local agent integrations after scaffolding a repo.
-For agent-driven scaffolding without prompts, use `hack init --auto` and run `hack setup` manually.
-
-## Branch builds (worktree-friendly)
-
-Use `--branch <name>` on project commands to run isolated instances with unique hostnames and compose
-project names:
-
-```bash
-hack up --branch feature-x --detach
-hack logs --branch feature-x
-hack open --branch feature-x
-```
-
-Using `--branch` will create/update `.hack/hack.branches.json` with a `last_used_at` timestamp. Branch
-instances show up in `hack projects --details`.
-
-Optional: track branch aliases in `.hack/hack.branches.json` for quick lookup:
-
-```bash
-hack branch add feature-x --note "worktree for PR 123"
-hack branch list
-hack branch open feature-x
-```
-
-
-## Service-to-service connections (HTTP vs DB/Redis)
-
-If your app runs in Docker (the default in `hack`), don’t connect to `127.0.0.1` / `localhost` for Postgres/Redis.
-Inside a container, `localhost` is that container, not the other compose services.
-
-If you previously ran everything on your host and used `localhost:PORT`, update those references when you
-move into containers:
-
-- **HTTP services**: use the same `https://*.hack` hostname you open from the host (whatever you configured in Caddy labels, e.g. `https://api.myapp.hack`).
-- **Non-HTTP services** (DB/Redis/etc.): use the Compose service hostname (e.g. `db`, `redis`).
-
-For HTTP services, use the same `https://*.hack` URLs you use on the host. `hack up` injects internal DNS,
-TLS trust, and `extra_hosts` mappings so `*.hack` resolves reliably inside containers. If you see `ENOTFOUND`
-inside containers, run `hack restart` to refresh the host mappings.
-
-For non-HTTP services, use the Compose service hostname on the default network:
-
-- `Postgres: db:5432`
-- `Redis: redis:6379`
-
-Note: Caddy’s CA is mounted into containers when `internal.tls: true` so HTTPS calls to `*.hack` work for most runtimes.
-If you’re using Java/Kotlin, you’ll need to import the CA into the JVM truststore manually.
-
-Example:
-
-```yaml
-environment:
-  DATABASE_URL: postgres://postgres:postgres@db:5432/mydb
-  REDIS_URL: redis://redis:6379
-```
-
-If you need host access for debugging, prefer `docker compose exec` so you don’t reintroduce port conflicts:
-
-```bash
-docker compose -f .hack/docker-compose.yml exec db psql -U postgres -d mydb
-docker compose -f .hack/docker-compose.yml exec redis redis-cli
-```
-
-## Logs (why both Compose and Loki)
-
-By default, `hack logs` uses `docker compose logs` because it’s the lowest latency tail.
-The daemon does not proxy logs yet; `hack logs` still talks directly to Docker Compose or Loki.
-
-Loki is still valuable for:
-
-- querying across time (history)
-- filtering by labels (project/service/container)
-- Grafana Explore / dashboards
-
-### CLI
-
-```bash
-# Tail (fast)
-hack logs --pretty
-
-# Snapshot
-hack logs --no-follow --pretty
-
-# Snapshot JSON
-hack logs --no-follow --json
-
-# Query/history (force Loki)
-hack logs --loki --pretty
-
-# Range (Loki only)
-hack logs --loki --since 2h --pretty
-hack logs --loki --since 4h --until 1h --pretty
-
-# Filter Loki by service
-hack logs --loki --services api,worker --pretty
-
-# Raw LogQL
-hack logs --loki --query '{project="my-project"} |= "error"' --pretty
-```
-
-### Grafana
-
-- Open: `hack open logs` or visit `https://logs.hack`
-- Explore queries:
-
-```logql
-{project="my-project"}
-{project="my-project", service="api"}
-```
-
-Alloy labels logs with:
-
-- project: `Docker Compose project name`
-- service: `Docker Compose service name`
-- container: `Docker container name`
-
-
-## Projects registry (bird’s-eye view)
-
-`hack` maintains a best-effort registry under `~/.hack/projects.json` so you can target a project from anywhere:
-
-```bash
-hack projects
-hack logs --project my-project --pretty
-hack up --project my-project
-```
-
-## .hack and valid tld requirements
-
-OAuth providers (notably Google) require `localhost` or a host that ends with a real public suffix.
-
-We keep `.hack` as the primary local dev domain, and optionally expose an alias domain for OAuth flows.
-If the OAuth alias is enabled, `hack global install` configures `*.hack.gy` to resolve to the Caddy
-container IP via dnsmasq + the OS resolver (bypasses port forwarding issues with Tailscale/VPNs).
-
-Routing rules:
-
-- `https://*.hack` is the default local-dev hostname space.
-- `https://*.hack.gy` is an OAuth-safe alias host space (public-suffix-style domain).
-- Only services with Caddy labels and attached to `hack-dev` are exposed via these hostnames.
-- These domains are local routes by default; use tunnels/remote ingress separately for internet-reachable webhooks.
-
-If you use Next.js (or another dev server that cares about dev origins), configure its dev allowlist to include the proxy domains.
-Next.js supports `allowedDevOrigins` (wildcards supported) in `next.config.js`:
-
-```js
-module.exports = {
-  allowedDevOrigins: ["*.hack", "*.hack.gy"],
-}
-```
-
-Optionally you can pass in your own custom `dev_host` to the config.
-
-
-## SSL
-
-`hack` uses Caddy’s internal PKI to issue certs for `*.hack` (and any OAuth alias host). This covers
-HTTPS for services routed through Caddy, but it does not create cert/key files for services running
-outside of Caddy.
-
-- macOS: run `hack global trust` to trust the Caddy Local CA in the System keychain.
-- Other OS: run `hack global ca` to export the CA cert path, then add it to your OS/browser trust store.
-- If you need the PEM directly: `hack global ca --print`.
-- If you are running a local service outside of Caddy, use `hack global cert <host...>` (mkcert required) to generate a cert/key under `~/.hack/certs` and wire it into your service. This is only needed for non-Caddy services that still want trusted TLS.
-- macOS: `hack global install` can optionally install mkcert (needed for `hack global cert`).
-
-Install mkcert if you don't already have it (macOS example):
-
-```bash
-brew install mkcert
-mkcert -install
-```
-
-Example (non-Caddy service):
-
-```bash
-hack global cert --install api.myapp.hack
-```
-
-Use `--out <dir>` if you want certs written somewhere else.
-
-## Internal DNS (containers)
-
-`hack global install` runs CoreDNS on the `hack-dev` network. CoreDNS answers `*.hack` and `*.hack.*` with
-Caddy’s current IP so containers can use the same `https://*.hack` URLs as the host.
-
-This is the core isolation model: each repo keeps its own compose network, while routed HTTP services get stable hostnames
-through shared Caddy ingress. That means you can call local services by hostname from host or container without relying on
-host-published `localhost:<port>` patterns.
-
-Some runtimes don’t honor custom DNS for `*.hack` reliably, so `hack up` also injects `extra_hosts` mappings
-to the Caddy IP. If the Caddy IP changes, `hack status`, `hack doctor`, and the TUI show a warning; fix it
-with `hack restart` to refresh the mapping.
-
-If you also need `extra_hosts` for non-`*.hack` hostnames (common when you run host-local tunnels/proxies
-and want containers to reach them by their real domain), use `hack internal extra-hosts set` to write a
-repo-local `.hack/.internal/extra-hosts.json` that gets merged into the generated Compose override.
-
-When `internal.tls` is enabled, `hack up` mounts the Caddy Local CA into each container and sets common
-SSL env vars so HTTPS to `*.hack` is trusted inside containers.
-
-If you update `hack`, rerun `hack global install` once to refresh the CoreDNS config.
-
-
-
-
-## Why not just use X?
-
-### Docker / Compose alone
-
-They run containers. They don’t give you stable hostnames, HTTPS, or a way to run many isolated copies of the same stack without custom glue. 
-
-You can build that layer yourself. I did. That’s this.
-
-### Kubernetes
-
-Kubernetes solves cluster orchestration. This problem is local parallelism.  
-It adds complexity without fixing ports, routing, or developer feedback loops.
-
-### Different ports
-
-This is the default answer and it doesn’t scale.  
-Ports leak into config, break OAuth and cookies, and turn into debt.  
-Hostnames scale. Ports don’t.
-
-There isn’t an off-the-shelf tool that gives you full local network isolation, real HTTPS, and near zero per-repo setup.
-
-If you want that, you have to build it yourself.
-
-
-## How it works
-
-`hack` is a thin layer on top of Docker Compose plus a tiny global proxy.
-
-- each project/branch runs in its own Docker network
-- services use their normal ports inside that network
-- a shared proxy routes `https://*.hack` and handles HTTPS
-- logs are captured centrally
-
-Your code doesn’t change. Your mental overhead does.
-
-### Global (once per machine)
-
-`hack global install` provisions `~/.hack/` and starts:
-
-- **Caddy** (`lucaslorentz/caddy-docker-proxy`) on ports `80/443`
-  - watches Docker labels and auto-routes `https://*.hack`
-- **Logging stack**: Grafana + Loki + Alloy
-  - reachable via `https://logs.hack`
-
-### Per-project (per repo)
-
-`hack init` creates `.hack/` in the repo root:
-
-- `.hack/docker-compose.yml`: your project services
-- `.hack/hack.config.json`: project config (name, dev host, log preferences)
-
-Each project’s compose network stays isolated; only services you want “public” get attached to the shared ingress network so Caddy can reach them.
-
-
-## Common patterns (deps + ops)
-
-Agents: run `hack agent patterns` for a compact checklist based on this section.
-
-### 1) Containerized dependency installs (recommended)
-
-If you run `bun install` on the host and then start Linux containers, you can hit platform
-mismatches (native modules, postinstall scripts, OS-specific binaries). The clean pattern is to
-install dependencies **inside** Docker and share them via a volume.
-
-Add a one-shot deps service and make your app services depend on it:
-
-```yaml
-deps:
-  image: imbios/bun-node:latest
-  working_dir: /app
-  volumes:
-    - ..:/app
-    - node_modules:/app/node_modules
-  command: bun install
-  networks:
-    - default
-
-www:
-  image: imbios/bun-node:latest
-  working_dir: /app/apps/www
-  volumes:
-    - ..:/app
-    - node_modules:/app/node_modules
-  depends_on:
-    deps:
-      condition: service_completed_successfully
-```
-
-This keeps dependency resolution in the same OS as your containers and avoids host/guest drift.
-
-### 2) Networked ops commands (DB schema tooling, migrations)
-
-Because `hack` avoids publishing DB ports to your host, run schema/ops commands inside the
-compose network.
-
-Option A (recommended): add an ops-only service:
-
-```yaml
-db-ops:
-  image: imbios/bun-node:latest
-  working_dir: /app/packages/db # where your db schema + package.json live
-  volumes:
-    - ..:/app
-    - node_modules:/app/node_modules
-  environment:
-    DATABASE_URL: postgres://postgres:postgres@db:5432/mydb
-  depends_on:
-    - db
-    - deps
-  networks:
-    - default
-  profiles: ["ops"]
-  # Examples:
-  # - Prisma:  bunx prisma migrate deploy
-  # - Drizzle: bunx drizzle-kit push
-  command: bun run db:push
-```
-
-Run it on demand:
-
-```bash
-docker compose -f .hack/docker-compose.yml --profile ops run --rm db-ops
-```
-
-Option B: run via `hack run` (thin wrapper over `docker compose run --rm`):
-
-```bash
-hack run --workdir /app/packages/db email-sync -- bunx prisma generate
-hack run --workdir /app/packages/db email-sync -- bunx prisma migrate dev
-hack run --workdir /app/packages/db email-sync -- bunx drizzle-kit push
-hack run --workdir /app bun run turbo db:migrate
-```
-
-If your ops service is behind a compose profile, enable it:
-
-```bash
-hack run --profile ops --workdir /app/packages/db db-ops -- bun run db:push
+hack mcp serve
 ```
 
-See examples:
-- `examples/next-app/README.md`
-
-
-## Troubleshooting
-
-- `*.hack` doesn’t resolve: run `hack doctor`, then `hack global install` (macOS: ensure dnsmasq is running).
-
-- Stale global setup / CoreDNS issues: run `hack doctor --fix` (refreshes network + CoreDNS + CA).
-
-- TLS warnings: run `hack global trust` (macOS).
-
-- Logs missing in Grafana: ensure Alloy is running (`hack global status`) and try `{app="docker"}` in Explore.
-
-- `ENOTFOUND` for `*.hack` inside containers: run `hack restart` to refresh `extra_hosts` mappings (check
-  `hack status` or the TUI for Caddy IP mismatch warnings).
-
-- `EAI_AGAIN` for external domains inside containers (e.g. `api.clerk.com`): CoreDNS isn’t forwarding.
-  Run `hack global install` and restart CoreDNS:
-  `docker compose -f ~/.hack/caddy/docker-compose.yml restart coredns`.
-
-- `hack global up` warns about `hack-dev` network labels or missing subnet: remove the network and reinstall:
-  `docker network rm hack-dev` then `hack global install`.
-
-- OAuth redirect errors: use the OAuth alias host (`*.hack.gy`) or `localhost` (providers may reject non-public suffixes like `.hack`).
-
-
-
 ## Development
 
-### From source
-
-```bash
-bun install
-bun run install:dev
-hack --help
-```
-This installs a small `hack` shim into `~/.hack/bin/hack` that runs your working tree directly (no rebuild needed).
-
-If `hack` isn’t found, add this to your shell config:
-
-```bash
-export PATH="$HOME/.hack/bin:$PATH"
-```
-
-### Compiled binary (release-like)
+If you are working on Hack itself:
 
 ```bash
 bun install
-bun run install:bin
-hack --help
-```
-This builds `dist/hack` via `bun build --compile` and installs it to `~/.hack/bin/hack`.
-
-### Check which install is active
-
-```bash
-bun run install:status
-```
-Reports whether `hack` is a dev shim or a compiled binary (and where it points).
-
-
-### Run in place
-
-```bash
-bun dev --help
-```
-
-### Tests
-
-```bash
-bun run test
-```
-
-Runs workspace tests via Turbo (`@hack/cli`, `@hack/auth-broker`, `@hack/db`).
-
-### Workspace command model
-
-Root commands are orchestration wrappers. For package-local work, run commands directly:
-
-```bash
-bun run --cwd packages/cli build
-bun run --cwd packages/cli macos:ghostty:bundle
-bun run --cwd services/auth-broker test
-bun run --cwd packages/db db:migrate
-```
-
-### Conventional commits
-
-```bash
-bun run commit
-```
-
-Commitlint runs on `git commit` via husky, and semantic-release uses Conventional Commits to
-compute versions.
-
-### Build a standalone binary
-
-```bash
 bun run build
-./dist/hack --help
-```
-
-### Build a release bundle
-
-```bash
-bun run build:release
+bun test
+bun x ultracite check
 ```
-Produces `dist/release/hack-<version>-release/`, a tarball, and `hack-install.sh`.
-
-### Release (tag + GitHub workflow)
-
-```bash
-bun run release:prepare
-git push --follow-tags
-```
-
-Updates `CHANGELOG.md` plus root/workspace `package.json` versions, creates the release commit and tag, and triggers the GitHub Release workflow on push.
-
-See `PACKAGING.md` for details.
 
+Useful repo-level commands:
 
-See also:
-- [Examples](examples/next-app/README.md)
-- [Docs](docs/README.md)
-- [Architecture](docs/architecture.md)
+- `bun run build`
+- `bun run test`
+- `bun run check`
+- `bun run macos:build`
 
+## Beta note
 
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
+Remote control plane, multi-node execution, and the macOS app are all still **Beta**. They are
+useful, but they are not the core path a new user needs to learn first.
diff --git a/apps/macos/README.md b/apps/macos/README.md
index d6dd111c5..a9b3ec9eb 100644
--- a/apps/macos/README.md
+++ b/apps/macos/README.md
@@ -1,7 +1,9 @@
-# Hack Desktop (macOS)
+# Hack Desktop for macOS (Beta)
 
 Native macOS app for managing local hack projects and daemon status.
 
+> Beta: the macOS app is useful, but it is still outside Hack's core getting-started path.
+
 ## Requirements
 
 - macOS 14+
diff --git a/docs/README.md b/docs/README.md
index e493be242..b99b525e0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,45 +1,52 @@
 # Docs
 
-This directory contains the public documentation for hack. Specs remain in `SPECS/` (working notes).
+This directory is organized around the product story instead of the implementation tree.
 
-## Core docs
+If you are new to Hack, start with the core path first, then move into integrations, then only
+visit the beta and reference surfaces you actually need.
 
+## Core workflows
+
+- [Initialize a project](guides/init-project.md)
 - [CLI reference](cli.md)
+- [Env & secrets](env.md)
+- [Sessions](sessions.md)
+- [Lifecycle](lifecycle.md)
+- [Global settings](guides/global-settings.md)
 - [Architecture](architecture.md)
-- [Sessions](sessions.md) - mux session management (tmux or zellij) + API
-- [Env & secrets](env.md) - env contract + `.hack/.env` + OS keychain secrets
-- [Lifecycle](lifecycle.md) - project startup hooks + managed host processes
-- [Gateway overview](gateway.md)
-- [Gateway API](gateway-api.md)
-- [Supervisor](supervisor.md)
-- [Extensions](extensions.md)
-- [Control-plane SDK](sdk.md)
 
-Monorepo note:
-- Root scripts orchestrate workspace tasks through Turbo.
-- Package-local commands remain available via `bun run --cwd <workspace> <script>`.
+## Integrations & collaboration
 
-Quick diagnostics:
-- `hack usage` (resource usage across running projects)
-- `hack usage --watch` (live resource trends)
-- `hack node routes status` (controller-side remote route bridge state)
-- `hack node routes repair` (re-apply persisted remote route bridge routes)
+- [Integrations overview](integrations.md)
+- [Tickets (git-backed)](guides/tickets.md)
+- [Linear integration architecture](guides/linear-integration-architecture.md)
 
-## Guides
+## Beta workflows
 
-- Start here (first remote node in ~10 minutes):
-  - [Remote node quickstart](guides/remote-node-quickstart.md)
-  - [Run laptop-to-laptop node pairing e2e](guides/remote-node-laptop-e2e.md)
-  - [Bootstrap a remote node on Railway](guides/remote-node-railway.md)
-- Remote setup (one command): `hack remote setup`
-- [Initialize a project](guides/init-project.md)
-- [Global settings](guides/global-settings.md)
-- [Tickets (git-backed)](guides/tickets.md)
-- [Expose the gateway over SSH](guides/remote-ssh.md)
-- [Expose the gateway with Cloudflare](guides/remote-cloudflare.md)
-- [Expose the gateway with Tailscale](guides/remote-tailscale.md)
-- [Run remote supervisor jobs](guides/remote-supervisor.md)
-- [Run a remote node via container image](guides/remote-node-container.md)
-- [Bootstrap a remote node on Railway](guides/remote-node-railway.md)
-- [Bootstrap auth-broker with Neon + Railway](guides/auth-broker-neon-bootstrap.md)
+- [Gateway (Beta)](gateway.md)
+- [Remote node quickstart (Beta)](guides/remote-node-quickstart.md)
+- [Remote node runtime container (Beta)](guides/remote-node-container.md)
+- [Remote node on Railway (Beta)](guides/remote-node-railway.md)
+- [Laptop-to-laptop remote node validation (Beta)](guides/remote-node-laptop-e2e.md)
+- [Expose the gateway over SSH (Beta)](guides/remote-ssh.md)
+- [Expose the gateway with Cloudflare (Beta)](guides/remote-cloudflare.md)
+- [Expose the gateway with Tailscale (Beta)](guides/remote-tailscale.md)
+- [Run remote supervisor jobs (Beta)](guides/remote-supervisor.md)
+- [Hack Desktop for macOS (Beta)](../apps/macos/README.md)
+
+## Extensions & reference
+
+- [Extensions & SDK reference](extensions.md)
+- [Gateway API (Beta)](gateway-api.md)
+- [Supervisor (Beta)](supervisor.md)
+- [Gateway auth-broker bootstrap](guides/auth-broker-neon-bootstrap.md)
 - [Create a new extension](guides/create-extension.md)
+- [Control-plane SDK](sdk.md)
+
+## Quick diagnostics
+
+- `hack help`
+- `hack status`
+- `hack usage`
+- `hack usage --watch`
+- `hack doctor`
diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..2919d0fe9 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -3,6 +3,14 @@
 This reference mirrors the CLI spec in `src/cli/spec.ts`.
 Run `hack help` or `hack help <command>` for interactive help.
 
+If you are new to Hack, scan the CLI in this order:
+
+1. `Global commands` for machine setup
+2. `Core workflows` for day-to-day local development
+3. `Collaboration & integrations` for env, sessions, tickets, Linear, and SSH access
+4. `Beta workflows` for remote control plane and multi-node execution
+5. `Extension commands` when you need the lower-level namespace surface
+
 ## Conventions
 
 - Commands that accept both `--path` and `--project` treat them as mutually exclusive.
@@ -18,31 +26,32 @@ Run `hack help` or `hack help <command>` for interactive help.
 | `hack projects` | Show all projects (registry + running docker compose) | Global |
 | `hack status` | Show project status (shortcut for `hack projects --details`) | Global |
 | `hack usage` | Show resource usage across running projects | Global |
-| `hack init` | Initialize a repo (generate .hack/ with compose + config) | Project |
-| `hack up` | Start project services (docker compose up) | Project |
-| `hack down` | Stop project services (docker compose down) | Project |
-| `hack restart` | Restart project services (down then up) | Project |
-| `hack ps` | Show project status (docker compose ps) | Project |
-| `hack logs` | Tail logs (compose by default; Loki for queries/history via --loki/--query) | Project |
-| `hack run` | Run a one-off command in a service container (docker compose run --rm) | Project |
-| `hack open` | Open a URL for the project (default: https://<project>.hack) | Project |
-| `hack tui` | Open the project TUI (services + logs) | Project |
-| `hack branch` | Manage branch aliases for a project | Project |
-| `hack linear` | Linear account connection and ticket sync | Project |
-| `hack config` | Read/write hack.config.json values | Project |
-| `hack env` | Manage project environment variables and secrets | Project |
-| `hack session` | Manage terminal sessions for hack projects | Project |
-| `hack ssh` | Show SSH connection info for remote access | Project |
-| `hack tickets` | Git-backed ticket management | Project |
+| `hack init` | Initialize a repo (generate .hack/ with compose + config) | Core workflows |
+| `hack up` | Start project services (docker compose up) | Core workflows |
+| `hack down` | Stop project services (docker compose down) | Core workflows |
+| `hack restart` | Restart project services (down then up) | Core workflows |
+| `hack ps` | Show project status (docker compose ps) | Core workflows |
+| `hack logs` | Tail logs (compose by default; Loki for queries/history via --loki/--query) | Core workflows |
+| `hack run` | Run a one-off command in a service container (docker compose run --rm) | Core workflows |
+| `hack open` | Open a URL for the project (default: https://<project>.hack) | Core workflows |
+| `hack tui` | Open the project TUI (services + logs) | Core workflows |
+| `hack branch` | Manage branch aliases for a project | Core workflows |
+| `hack config` | Read/write hack.config.json values | Core workflows |
+| `hack auth` | Manage Hack account sign-in | Collaboration & integrations |
+| `hack linear` | Connect Linear and sync selected work into the repo | Collaboration & integrations |
+| `hack env` | Share project env contracts and store local secrets | Collaboration & integrations |
+| `hack session` | Keep persistent work sessions for projects and agents | Collaboration & integrations |
+| `hack ssh` | Show SSH details for reaching this machine and its sessions | Collaboration & integrations |
+| `hack tickets` | Track repo-local work in git-backed tickets | Collaboration & integrations |
 | `hack internal` | Manage hack-managed internal overrides | Internal |
-| `hack gateway` | Manage gateway enablement | Extensions |
-| `hack node` | Manage remote execution nodes | Extensions |
-| `hack dispatch` | Dispatch branch-scoped jobs to remote nodes | Extensions |
-| `hack remote` | Remote workflow helpers | Extensions |
-| `hack x` | Run extension commands | Extensions |
-| `hack setup` | Install integrations for coding agents | Agents |
-| `hack agent` | Agent utilities | Agents |
-| `hack mcp` | Manage MCP server integrations for coding agents | Agents |
+| `hack gateway` | Beta: manage the remote control plane entrypoint | Beta workflows |
+| `hack node` | Beta: manage remote execution nodes | Beta workflows |
+| `hack dispatch` | Beta: run branch-scoped jobs on remote nodes | Beta workflows |
+| `hack remote` | Beta: guided remote access and gateway helpers | Beta workflows |
+| `hack x` | Run extension commands | Extension commands |
+| `hack setup` | Install integrations for coding agents | Agent integrations |
+| `hack agent` | Agent utilities | Agent integrations |
+| `hack mcp` | Manage MCP server integrations for coding agents | Agent integrations |
 | `hack doctor` | Validate local setup (docker, networks, DNS, global infra, project config) | Diagnostics |
 | `hack crash-capture` | Capture runtime crash diagnostics into `.tmp/` for triage | Diagnostics |
 | `hack daemon` | Manage the local hack daemon (hackd) | Diagnostics |
@@ -174,7 +183,7 @@ Options:
 | `--no-host` | boolean | false | Skip host process metrics |
 | `--json` | boolean | false | Output JSON (machine-readable); not supported with `--watch` |
 
-## Project commands
+## Core workflows
 
 ### hack init
 
@@ -472,6 +481,66 @@ Options:
 | `--project <name>` | string | - | Target a registered project by name |
 | `--global` | boolean | false | Write global `~/.hack/hack.config.json` |
 
+## Collaboration & integrations
+
+### hack auth
+
+Usage: `hack auth <subcommand>`
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `login` | Open a browser and sign in to Hack auth |
+| `logout` | Clear the locally stored Hack auth session |
+| `status` | Show whether Hack auth is configured locally |
+| `whoami` | Resolve the current Hack auth identity via the broker |
+
+#### hack auth login
+
+Usage: `hack auth login [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON |
+| `--no-open` | boolean | false | Print the browser URL instead of opening it automatically |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+| `--redirect <url>` | string | - | Return to this URL after browser sign-in finishes |
+
+#### hack auth logout
+
+Usage: `hack auth logout [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON |
+
+#### hack auth status
+
+Usage: `hack auth status [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+#### hack auth whoami
+
+Usage: `hack auth whoami [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
 ### hack env
 
 Usage: `hack env <subcommand>`
@@ -698,7 +767,7 @@ Usage: `hack internal extra-hosts unset <hostname> [options]`
 
 Usage: `hack internal extra-hosts list [options]`
 
-## Extension commands
+## Beta workflows
 
 ### hack gateway
 
@@ -1036,6 +1105,8 @@ Options:
 | `--ssh-port <port>` | number | - | SSH port for QR payload (omitted defaults to 22) |
 | `--yes` | boolean | false | Skip confirmation before printing sensitive QR payloads |
 
+## Extension commands
+
 ### hack x
 
 Usage: `hack x <namespace> <command> [args...]`
@@ -1051,7 +1122,7 @@ Notes:
 - `hack x list` lists available extensions.
 - `hack x <namespace> help` lists commands for a namespace.
 
-## Agent commands
+## Agent integrations
 
 ### hack setup
 
diff --git a/docs/extensions.md b/docs/extensions.md
index b4c8b0a81..fe2d10339 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -1,7 +1,9 @@
-# Extensions & SDK (v0.1)
+# Extensions & SDK Reference
 
-This doc defines the extension surface area for `hack` and how extension commands are authored,
-configured, and dispatched.
+This is the lower-level reference for extension commands, SDK surfaces, and extension dispatch.
+
+If you want the plain-language product overview first, read [integrations.md](integrations.md)
+before this page.
 
 ## Quick start (one command)
 
diff --git a/docs/gateway-api.md b/docs/gateway-api.md
index bbe4cd563..adca21122 100644
--- a/docs/gateway-api.md
+++ b/docs/gateway-api.md
@@ -1,9 +1,10 @@
-# Gateway API (hackd HTTP/WS)
+# Gateway API (Beta)
 
 The gateway exposes a small, authenticated HTTP/WS surface for remote orchestration. It is
 designed for structured workflows (jobs + log streaming + shells) and keeps write access
 opt-in with explicit guardrails.
 
+> Beta: this API belongs to the remote control plane, which is still beta.
 > ⚠️ Experimental: remote exposure steps are still being validated end-to-end.
 
 ## Security model (read this first)
diff --git a/docs/gateway.md b/docs/gateway.md
index 9a367e2a0..5a03311e5 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -1,9 +1,10 @@
-# Gateway (remote control plane)
+# Gateway (Beta remote control plane)
 
 The gateway exposes a small HTTP/WS surface on top of `hackd` so you can orchestrate jobs, stream
 logs, and open shells remotely. It is disabled by default and binds to `127.0.0.1` unless you
 explicitly expose it through SSH, Cloudflare, or Tailscale.
 
+> Beta: the remote control plane is not part of the core getting-started path yet.
 > ⚠️ Experimental: the remote exposure guides below are still being validated end-to-end.
 
 ## Concepts
diff --git a/docs/guides/remote-cloudflare.md b/docs/guides/remote-cloudflare.md
index 2f75279e0..a265c1d29 100644
--- a/docs/guides/remote-cloudflare.md
+++ b/docs/guides/remote-cloudflare.md
@@ -1,5 +1,6 @@
-# Expose the gateway with Cloudflare
+# Expose the gateway with Cloudflare (Beta)
 
+> Beta: Cloudflare gateway exposure is part of the remote control plane beta.
 > ⚠️ Experimental: this guide has not been validated end-to-end yet. Use with caution and report issues.
 
 Cloudflare Tunnel is ideal for HTTP/WS gateway access from a phone or browser when you are off-network.
diff --git a/docs/guides/remote-node-container.md b/docs/guides/remote-node-container.md
index 88d5df282..27648bd58 100644
--- a/docs/guides/remote-node-container.md
+++ b/docs/guides/remote-node-container.md
@@ -1,7 +1,9 @@
-# Remote Node Runtime Container
+# Remote Node Runtime Container (Beta)
 
 Use the published node-runtime container to spin up a remote node with minimal host setup.
 
+> Beta: multi-node execution is still being validated and is not part of the core local-dev path.
+
 Recommended public image:
 - `hackdance/hack:latest`
 
diff --git a/docs/guides/remote-node-laptop-e2e.md b/docs/guides/remote-node-laptop-e2e.md
index 0ff9c3864..dafd4afff 100644
--- a/docs/guides/remote-node-laptop-e2e.md
+++ b/docs/guides/remote-node-laptop-e2e.md
@@ -1,9 +1,11 @@
-# Run laptop-to-laptop node pairing e2e
+# Run laptop-to-laptop node pairing e2e (Beta)
 
 This guide is the full validation run for two Macs:
 1. Controller Mac (host mode)
 2. Remote MacBook node
 
+> Beta: laptop-to-laptop multi-node flows are still being validated and are not part of the core local-dev path.
+
 It validates pairing, remote routing, workspace mapping, mutagen sync, and dispatch execution.
 
 If you only need initial setup, use [Remote node quickstart](remote-node-quickstart.md) first.
diff --git a/docs/guides/remote-node-quickstart.md b/docs/guides/remote-node-quickstart.md
index d4af4bc71..ad6653814 100644
--- a/docs/guides/remote-node-quickstart.md
+++ b/docs/guides/remote-node-quickstart.md
@@ -1,7 +1,9 @@
-# Remote Node Quickstart
+# Remote Node Quickstart (Beta)
 
 Use this guide to connect one remote machine as a `hack` execution node and run a project on it.
 
+> Beta: multi-node execution is still being validated and is not part of the core local-dev path.
+
 ## What you need
 
 1. A host machine (controller) with `hack` installed.
diff --git a/docs/guides/remote-node-railway.md b/docs/guides/remote-node-railway.md
index 1fd58775f..2dafc7046 100644
--- a/docs/guides/remote-node-railway.md
+++ b/docs/guides/remote-node-railway.md
@@ -1,7 +1,9 @@
-# Railway Node Bootstrap Guide
+# Railway Node Bootstrap Guide (Beta)
 
 Use this guide to register a Railway-hosted runtime as a `hack` remote node.
 
+> Beta: provider-backed remote nodes are still being validated and are not part of the core local-dev path.
+
 If this is your first remote node, start with [Remote node quickstart](remote-node-quickstart.md) for core concepts.
 
 ## Quick Start
diff --git a/docs/guides/remote-ssh.md b/docs/guides/remote-ssh.md
index ed86f599d..75fc10b7a 100644
--- a/docs/guides/remote-ssh.md
+++ b/docs/guides/remote-ssh.md
@@ -1,5 +1,6 @@
-# Expose the gateway over SSH
+# Expose the gateway over SSH (Beta)
 
+> Beta: SSH gateway exposure is part of the remote control plane beta.
 > ⚠️ Experimental: this guide has not been validated end-to-end yet. Use with caution and report issues.
 
 Use SSH port-forwarding when you want quick, ad-hoc access without extra tooling.
diff --git a/docs/guides/remote-supervisor.md b/docs/guides/remote-supervisor.md
index b529cdebb..a6d43233f 100644
--- a/docs/guides/remote-supervisor.md
+++ b/docs/guides/remote-supervisor.md
@@ -1,7 +1,9 @@
-# Run remote supervisor jobs
+# Run remote supervisor jobs (Beta)
 
 Use the gateway API to run commands and stream logs remotely.
 
+> Beta: remote supervisor workflows are part of the remote control plane beta.
+
 ## Prereqs
 
 - Gateway enabled (`hack gateway setup`)
diff --git a/docs/guides/remote-tailscale.md b/docs/guides/remote-tailscale.md
index 3a9525765..3dcbbfc01 100644
--- a/docs/guides/remote-tailscale.md
+++ b/docs/guides/remote-tailscale.md
@@ -1,7 +1,9 @@
-# Expose the gateway with Tailscale
+# Expose the gateway with Tailscale (Beta)
 
 Use this guide when you want private tailnet-only access to `hack` gateway endpoints.
 
+> Beta: Tailscale gateway exposure is part of the remote control plane beta.
+
 Tailscale is recommended for:
 1. SSH from mobile/desktop clients.
 2. Private remote-node endpoints without public ingress.
diff --git a/docs/integrations.md b/docs/integrations.md
new file mode 100644
index 000000000..6edaede17
--- /dev/null
+++ b/docs/integrations.md
@@ -0,0 +1,126 @@
+# Integrations Overview
+
+Hack keeps the core local-dev path small, then layers supporting workflows around it.
+
+The easiest way to think about these integrations is:
+
+- GitHub and Linear connect Hack to systems that already exist outside your repo
+- Tickets, sessions, and env keep your daily workflow close to the repo itself
+- None of these are required to get started with `hack init`, `hack up`, and `hack open`
+
+## GitHub
+
+GitHub integration is for repo auth and pull-request workflows.
+
+Use it when you want Hack to:
+
+- authenticate private repo or automation flows
+- create or update a PR as part of a run or release workflow
+- keep more than one GitHub profile available on the same machine
+
+Main surface:
+
+- `hack x github connect`
+- `hack x github status`
+- `hack x github pr-upsert`
+
+Reference:
+
+- [Extensions & SDK reference](extensions.md)
+
+## Linear
+
+Linear integration is for syncing selected planning work into the repo, not for replacing your
+whole Linear setup.
+
+Use it when you want Hack to:
+
+- connect a local Linear profile
+- bind a Hack project to a Linear project
+- sync a specific issue or project into repo-local workflow state
+
+Main surface:
+
+- `hack linear status`
+- `hack linear connect`
+- `hack linear sync-issue`
+- `hack linear sync-project`
+
+Reference:
+
+- [Linear integration architecture](guides/linear-integration-architecture.md)
+- [Extensions & SDK reference](extensions.md)
+
+## Tickets
+
+Tickets are a lightweight, git-backed work log that lives with the repo instead of in a separate
+hosted tracker.
+
+Use them when you want to:
+
+- capture follow-up work during implementation
+- keep agent-created tasks next to the code
+- sync issue state through git refs instead of another service
+
+Main surface:
+
+- `hack tickets create`
+- `hack tickets list`
+- `hack tickets show`
+- `hack tickets status`
+- `hack tickets sync`
+
+Reference:
+
+- [Tickets guide](guides/tickets.md)
+
+## Sessions
+
+Sessions are durable terminal workspaces for humans and agents.
+
+Use them when you want to:
+
+- keep a project shell alive between reconnects
+- give an agent its own long-lived workspace
+- reattach to an existing terminal workflow instead of starting from scratch
+
+Main surface:
+
+- `hack session`
+- `hack session start`
+- `hack session attach`
+- `hack session exec`
+
+Reference:
+
+- [Sessions](sessions.md)
+
+## Env
+
+Env support gives the repo a clear contract for configuration without committing the actual secret
+values.
+
+Use it when you want to:
+
+- declare what variables a project needs
+- keep plain values in `.hack/.env`
+- keep sensitive values in a secret backend
+
+Main surface:
+
+- `hack env list`
+- `hack env set`
+- `hack env unset`
+- `hack env backend status`
+
+Reference:
+
+- [Env & secrets](env.md)
+
+## Choosing the right surface
+
+- Start with the core path if you just need a project running locally
+- Add env when a repo needs repeatable configuration
+- Add sessions when you want durable terminal workflows
+- Add tickets when follow-up work should stay in git
+- Add GitHub or Linear only when you need those external systems connected
diff --git a/docs/supervisor.md b/docs/supervisor.md
index 559ba4db0..768cbcfad 100644
--- a/docs/supervisor.md
+++ b/docs/supervisor.md
@@ -1,9 +1,11 @@
-# Supervisor (jobs + shells)
+# Supervisor (Beta)
 
 The supervisor is the execution engine behind remote workflows. It can run commands as jobs,
 stream logs/events, and host PTY-backed shells. The CLI exposes it locally via `hack x supervisor`
 and remotely through the gateway API.
 
+> Beta: supervisor is part of Hack's remote workflow surface, not the core getting-started path.
+
 ## Local usage
 
 ```bash
diff --git a/src/cli/command.ts b/src/cli/command.ts
index ee10fdbc4..b9f4ad16f 100644
--- a/src/cli/command.ts
+++ b/src/cli/command.ts
@@ -8,6 +8,8 @@ const SHORT_OPTION_PREFIX_REGEX = /^-/;
 export type CliGroup =
   | "Global"
   | "Project"
+  | "Integrations"
+  | "Beta"
   | "Extensions"
   | "Agents"
   | "Diagnostics"
@@ -111,6 +113,7 @@ export interface CliSpec {
   readonly name: string;
   readonly version: string;
   readonly summary: string;
+  readonly highlights?: readonly string[];
   readonly commands: readonly AnyCommandSpec[];
   readonly globalOptions: readonly OptionSpec[];
 }
diff --git a/src/cli/help.ts b/src/cli/help.ts
index f58e64353..09bd2834b 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -80,6 +80,14 @@ function renderRootHelp(cli: CliSpec): string {
   lines.push(`  ${cli.name} <command> [options]`);
   lines.push("");
 
+  if (cli.highlights && cli.highlights.length > 0) {
+    lines.push("Core promises:");
+    for (const [index, highlight] of cli.highlights.entries()) {
+      lines.push(`  ${index + 1}. ${highlight}`);
+    }
+    lines.push("");
+  }
+
   const grouped = groupRootEntries(cli);
   for (const group of groupsInOrder()) {
     const entries = grouped.get(group);
@@ -121,6 +129,15 @@ function renderRootHelpMarkdown(cli: CliSpec): string {
   lines.push("```");
   lines.push("");
 
+  if (cli.highlights && cli.highlights.length > 0) {
+    lines.push("### Core promises");
+    lines.push("");
+    for (const highlight of cli.highlights) {
+      lines.push(`1. ${mdEscape(highlight)}`);
+    }
+    lines.push("");
+  }
+
   const grouped = groupRootEntries(cli);
   for (const group of groupsInOrder()) {
     const entries = grouped.get(group);
@@ -393,6 +410,8 @@ function groupsInOrder(): readonly CliGroup[] {
   return [
     "Global",
     "Project",
+    "Integrations",
+    "Beta",
     "Extensions",
     "Agents",
     "Diagnostics",
@@ -405,8 +424,10 @@ function groupLabel(group: CliGroup): string {
   return (
     {
       Global: "Global commands",
-      Project: "Project commands",
-      Extensions: "Extensions",
+      Project: "Core workflows",
+      Integrations: "Collaboration & integrations",
+      Beta: "Beta workflows",
+      Extensions: "Extension commands",
       Agents: "Agent integrations",
       Diagnostics: "Diagnostics",
       Secrets: "Secrets",
diff --git a/src/cli/spec.ts b/src/cli/spec.ts
index 079084d87..ae589344a 100644
--- a/src/cli/spec.ts
+++ b/src/cli/spec.ts
@@ -50,8 +50,12 @@ const packageJson = pkg as unknown as PackageJsonType;
 export const CLI_SPEC = defineCli({
   name: "hack",
   version: packageJson.version,
-  summary:
-    "run multiple local projects concurrently (network isolation + https://*.hack)",
+  summary: "Local development without the port-collision tax",
+  highlights: [
+    "Run multiple repos or branches at the same time without port conflicts.",
+    "Give every project a stable HTTPS URL like https://myapp.hack.",
+    "Keep env, sessions, tickets, and integrations close to the repo.",
+  ] as const,
   globalOptions: [],
   commands: [
     globalCommand,
diff --git a/src/commands/auth.ts b/src/commands/auth.ts
index 243db4f65..8271491c4 100644
--- a/src/commands/auth.ts
+++ b/src/commands/auth.ts
@@ -41,7 +41,7 @@ const optRedirect = defineOption({
 const loginSpec = defineCommand({
   name: "login",
   summary: "Open a browser and sign in to Hack auth",
-  group: "Global",
+  group: "Integrations",
   options: [optJson, optNoOpen, optBrokerUrl, optRedirect] as const,
   positionals: [] as const,
   subcommands: [] as const,
@@ -50,7 +50,7 @@ const loginSpec = defineCommand({
 const logoutSpec = defineCommand({
   name: "logout",
   summary: "Clear the locally stored Hack auth session",
-  group: "Global",
+  group: "Integrations",
   options: [optJson] as const,
   positionals: [] as const,
   subcommands: [] as const,
@@ -59,7 +59,7 @@ const logoutSpec = defineCommand({
 const statusSpec = defineCommand({
   name: "status",
   summary: "Show whether Hack auth is configured locally",
-  group: "Global",
+  group: "Integrations",
   options: [optJson, optBrokerUrl] as const,
   positionals: [] as const,
   subcommands: [] as const,
@@ -68,7 +68,7 @@ const statusSpec = defineCommand({
 const whoamiSpec = defineCommand({
   name: "whoami",
   summary: "Resolve the current Hack auth identity via the broker",
-  group: "Global",
+  group: "Integrations",
   options: [optJson, optBrokerUrl] as const,
   positionals: [] as const,
   subcommands: [] as const,
@@ -76,9 +76,9 @@ const whoamiSpec = defineCommand({
 
 export const authCommand = defineCommand({
   name: "auth",
-  summary: "Manage Hack auth sessions",
-  group: "Global",
-  expandInRootHelp: true,
+  summary: "Manage Hack account sign-in",
+  group: "Integrations",
+  expandInRootHelp: false,
   options: [] as const,
   positionals: [] as const,
   subcommands: [
diff --git a/src/commands/dispatch.ts b/src/commands/dispatch.ts
index daf3877e5..5bda50bf6 100644
--- a/src/commands/dispatch.ts
+++ b/src/commands/dispatch.ts
@@ -211,8 +211,8 @@ const logsPositionals = [{ name: "runId", required: true }] as const;
 
 const dispatchSpec = defineCommand({
   name: "dispatch",
-  summary: "Dispatch branch-scoped jobs to remote nodes",
-  group: "Extensions",
+  summary: "Beta: run branch-scoped jobs on remote nodes",
+  group: "Beta",
   options: [],
   positionals: [],
   subcommands: [],
@@ -221,7 +221,7 @@ const dispatchSpec = defineCommand({
 const runSpec = defineCommand({
   name: "run",
   summary: "Dispatch a command to a node workspace",
-  group: "Extensions",
+  group: "Beta",
   options: runOptions,
   positionals: runPositionals,
   subcommands: [],
@@ -230,7 +230,7 @@ const runSpec = defineCommand({
 const statusSpec = defineCommand({
   name: "status",
   summary: "Show dispatched run status",
-  group: "Extensions",
+  group: "Beta",
   options: statusOptions,
   positionals: statusPositionals,
   subcommands: [],
@@ -239,7 +239,7 @@ const statusSpec = defineCommand({
 const logsSpec = defineCommand({
   name: "logs",
   summary: "Show or follow persisted/remote run logs",
-  group: "Extensions",
+  group: "Beta",
   options: logsOptions,
   positionals: logsPositionals,
   subcommands: [],
diff --git a/src/commands/env.ts b/src/commands/env.ts
index 844d0f8da..c6c10cb42 100644
--- a/src/commands/env.ts
+++ b/src/commands/env.ts
@@ -620,8 +620,8 @@ async function resolveEnvValue(opts: {
 
 export const envCommand = defineCommand({
   name: "env",
-  summary: "Manage project environment variables and secrets",
-  group: "Project",
+  summary: "Share project env contracts and store local secrets",
+  group: "Integrations",
   expandInRootHelp: true,
   options: [],
   positionals: [],
diff --git a/src/commands/gateway.ts b/src/commands/gateway.ts
index 41e89a12e..8fc5d60b2 100644
--- a/src/commands/gateway.ts
+++ b/src/commands/gateway.ts
@@ -49,8 +49,8 @@ import { isTty } from "../ui/terminal.ts";
 
 const gatewaySpec = defineCommand({
   name: "gateway",
-  summary: "Manage gateway enablement",
-  group: "Extensions",
+  summary: "Beta: manage the remote control plane entrypoint",
+  group: "Beta",
   options: [],
   positionals: [],
   subcommands: [],
@@ -61,7 +61,7 @@ const toggleOptions = [optPath, optProject] as const;
 const enableSpec = defineCommand({
   name: "enable",
   summary: "Enable the gateway and start hackd",
-  group: "Extensions",
+  group: "Beta",
   options: toggleOptions,
   positionals: [],
   subcommands: [],
@@ -93,7 +93,7 @@ const setupOptions = [optPath, optProject, optQr, optNoQr, optYes] as const;
 const setupSpec = defineCommand({
   name: "setup",
   summary: "Guided gateway setup (enable + token)",
-  group: "Extensions",
+  group: "Beta",
   options: setupOptions,
   positionals: [],
   subcommands: [],
@@ -102,7 +102,7 @@ const setupSpec = defineCommand({
 const disableSpec = defineCommand({
   name: "disable",
   summary: "Disable the gateway (does not stop hackd)",
-  group: "Extensions",
+  group: "Beta",
   options: toggleOptions,
   positionals: [],
   subcommands: [],
diff --git a/src/commands/linear.ts b/src/commands/linear.ts
index 7c3426f9c..a68922b34 100644
--- a/src/commands/linear.ts
+++ b/src/commands/linear.ts
@@ -13,7 +13,7 @@ import { logger } from "../ui/logger.ts";
  */
 const linearSpec = defineCommand({
   name: "linear",
-  summary: "Linear account connection and ticket sync",
+  summary: "Connect Linear and sync selected work into the repo",
   description: [
     "Usage:",
     "  hack linear status",
@@ -27,7 +27,7 @@ const linearSpec = defineCommand({
     "",
     "Alias for `hack x linear <command>`. Requires extension enabled.",
   ].join("\n"),
-  group: "Project",
+  group: "Integrations",
   options: [],
   positionals: [{ name: "args", required: false, multiple: true }],
   subcommands: [],
diff --git a/src/commands/node.ts b/src/commands/node.ts
index 61fa2d1aa..9fb268242 100644
--- a/src/commands/node.ts
+++ b/src/commands/node.ts
@@ -406,8 +406,8 @@ const optTailscaleTags = defineOption({
 
 const nodeSpec = defineCommand({
   name: "node",
-  summary: "Manage remote execution nodes",
-  group: "Extensions",
+  summary: "Beta: manage remote execution nodes",
+  group: "Beta",
   options: [],
   positionals: [],
   subcommands: [],
diff --git a/src/commands/remote.ts b/src/commands/remote.ts
index d00ac6b86..f37219bf6 100644
--- a/src/commands/remote.ts
+++ b/src/commands/remote.ts
@@ -146,8 +146,8 @@ const setupOptions = [optPath, optProject, optQr, optNoQr, optYes] as const;
 
 const remoteSpec = defineCommand({
   name: "remote",
-  summary: "Remote workflow helpers",
-  group: "Extensions",
+  summary: "Beta: guided remote access and gateway helpers",
+  group: "Beta",
   options: remoteOptions,
   positionals: [],
   subcommands: [],
@@ -156,7 +156,7 @@ const remoteSpec = defineCommand({
 const setupSpec = defineCommand({
   name: "setup",
   summary: "Run the guided gateway setup",
-  group: "Extensions",
+  group: "Beta",
   options: setupOptions,
   positionals: [],
   subcommands: [],
@@ -165,7 +165,7 @@ const setupSpec = defineCommand({
 const statusSpec = defineCommand({
   name: "status",
   summary: "Show remote/gateway status",
-  group: "Extensions",
+  group: "Beta",
   options: remoteOptions,
   positionals: [],
   subcommands: [],
@@ -174,7 +174,7 @@ const statusSpec = defineCommand({
 const monitorSpec = defineCommand({
   name: "monitor",
   summary: "Open a remote status TUI",
-  group: "Extensions",
+  group: "Beta",
   options: remoteOptions,
   positionals: [],
   subcommands: [],
@@ -183,7 +183,7 @@ const monitorSpec = defineCommand({
 const qrSpec = defineCommand({
   name: "qr",
   summary: "Print a QR payload for remote access",
-  group: "Extensions",
+  group: "Beta",
   options: qrOptions,
   positionals: [],
   subcommands: [],
diff --git a/src/commands/session.ts b/src/commands/session.ts
index 5d1a7a717..496084e9b 100644
--- a/src/commands/session.ts
+++ b/src/commands/session.ts
@@ -793,8 +793,8 @@ const handleTail = async ({
 
 export const sessionCommand = defineCommand({
   name: "session",
-  summary: "Manage tmux sessions for hack projects",
-  group: "Project",
+  summary: "Keep persistent work sessions for projects and agents",
+  group: "Integrations",
   options: [],
   positionals: [],
   handler: handleSessionPicker,
diff --git a/src/commands/ssh.ts b/src/commands/ssh.ts
index 83dcb64d8..76ac116ed 100644
--- a/src/commands/ssh.ts
+++ b/src/commands/ssh.ts
@@ -65,8 +65,8 @@ const optPort = defineOption({
 
 const sshSpec = defineCommand({
   name: "ssh",
-  summary: "Show SSH connection info for remote access to this machine",
-  group: "Project",
+  summary: "Show SSH details for reaching this machine and its sessions",
+  group: "Integrations",
   options: [optHost, optUser, optTailscale, optDirect, optPort],
   positionals: [
     { name: "session", description: "Session to connect to", required: false },
diff --git a/src/commands/tickets.ts b/src/commands/tickets.ts
index 8e0d691fc..fbcfe0663 100644
--- a/src/commands/tickets.ts
+++ b/src/commands/tickets.ts
@@ -14,7 +14,7 @@ import { logger } from "../ui/logger.ts";
  */
 const ticketsSpec = defineCommand({
   name: "tickets",
-  summary: "Git-backed ticket management",
+  summary: "Track repo-local work in git-backed tickets",
   description: [
     "Usage:",
     "  hack tickets list",
@@ -28,7 +28,7 @@ const ticketsSpec = defineCommand({
     "",
     "Alias for `hack x tickets <command>`. Requires extension enabled.",
   ].join("\n"),
-  group: "Project",
+  group: "Integrations",
   options: [],
   positionals: [{ name: "args", required: false, multiple: true }],
   subcommands: [],
diff --git a/tests/cli-help.test.ts b/tests/cli-help.test.ts
new file mode 100644
index 000000000..c0f3af68b
--- /dev/null
+++ b/tests/cli-help.test.ts
@@ -0,0 +1,52 @@
+import { expect, test } from "bun:test";
+import {
+  renderHelpForPath,
+  renderHelpMarkdownForPath,
+} from "../src/cli/help.ts";
+import { CLI_SPEC } from "../src/cli/spec.ts";
+
+test("root help leads with core promises and separates core from beta surfaces", () => {
+  const help = renderHelpForPath(CLI_SPEC, []);
+
+  expect(help).toContain("Local development without the port-collision tax");
+  expect(help).toContain("Core promises:");
+  expect(help).toContain(
+    "1. Run multiple repos or branches at the same time without port conflicts."
+  );
+  expect(help).toContain("Core workflows:");
+  expect(help).toContain("Collaboration & integrations:");
+  expect(help).toContain("Beta workflows:");
+  expect(help).toContain("Extension commands:");
+  expect(help).toMatch(
+    /hack remote\s+Beta: guided remote access and gateway helpers/
+  );
+  expect(help).toMatch(
+    /hack tickets(?: \[args\.\.\.\])?\s+Track repo-local work in git-backed tickets/
+  );
+
+  expect(help.indexOf("Core workflows:")).toBeLessThan(
+    help.indexOf("Beta workflows:")
+  );
+  expect(help).toMatch(/hack auth\s+Manage Hack account sign-in/);
+  expect(help.indexOf("Collaboration & integrations:")).toBeLessThan(
+    help.indexOf("hack auth")
+  );
+  expect(help.indexOf("hack auth")).toBeLessThan(
+    help.indexOf("Beta workflows:")
+  );
+  expect(help).not.toContain("hack auth login");
+});
+
+test("markdown help preserves the core offer and command grouping", () => {
+  const help = renderHelpMarkdownForPath(CLI_SPEC, []);
+
+  expect(help).toContain("### Core promises");
+  expect(help).toContain(
+    "1. Run multiple repos or branches at the same time without port conflicts."
+  );
+  expect(help).toContain("### Core workflows");
+  expect(help).toContain("### Collaboration & integrations");
+  expect(help).toContain("### Beta workflows");
+  expect(help).toContain("### Extension commands");
+  expect(help).toContain("`hack auth`");
+});

From a0daeec052928a603f7250f43e514aca814996df Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:07:57 +0000
Subject: [PATCH 015/134] docs(readme): center root docs on core promises

---
 README.md | 965 ++++++++----------------------------------------------
 1 file changed, 145 insertions(+), 820 deletions(-)

diff --git a/README.md b/README.md
index 31d64cc93..ca919d4f8 100644
--- a/README.md
+++ b/README.md
@@ -1,942 +1,267 @@
-<a id="readme-top"></a>
+# Hack
 
-<!-- PROJECT LOGO -->
-<br />
-<div align="center">
-<pre style="font-family:monospace;padding:0;margin:0;white-space:pre;font-size:12px;background:none!important;">
+```text
  █████   █████   █████████     █████████  █████   ████
-░░███   ░░███   ███░░░░░███   ███░░░░░███░░███   ███░ 
- ░███    ░███  ░███    ░███  ███     ░░░  ░███  ███   
- ░███████████  ░███████████ ░███          ░███████    
- ░███░░░░░███  ░███░░░░░███ ░███          ░███░░███   
- ░███    ░███  ░███    ░███ ░░███     ███ ░███ ░░███  
+░░███   ░░███   ███░░░░░███   ███░░░░░███░░███   ███░
+ ░███    ░███  ░███    ░███  ███     ░░░  ░███  ███
+ ░███████████  ░███████████ ░███          ░███████
+ ░███░░░░░███  ░███░░░░░███ ░███          ░███░░███
+ ░███    ░███  ░███    ░███ ░░███     ███ ░███ ░░███
  █████   █████ █████   █████ ░░█████████  █████ ░░████
-░░░░░   ░░░░░ ░░░░░   ░░░░░   ░░░░░░░░░  ░░░░░   ░░░░ 
-</p>
-<br/>
-</div>
-  <p align="center">
-    Opinionated local-dev orchestration for running <b>multiple projects</b> at the same time without port conflicts.
-    <br />
-  </p>
-
----
-**Network isolation per repo / branch**: every instance runs on its own Docker network (so Postgres/Redis/etc can stay on default ports *inside* the project).
-
-**Stable HTTPS hostnames**: `https://<project>.hack` (and subdomains like `https://api.<project>.hack`) routed by a global Caddy proxy.
-
-**Good logs UX**: instant `docker compose logs` tailing, plus Loki/Grafana for querying + history.
-
-**Opt-in per repo**: no invasive changes to your codebase; config lives in `.hack/`.
-
----
-
-### Why this exists
-
-Most of my projects run the same stack. That’s fine until you want to:
-
-- run two projects at the same time
-- run two branches of the same repo
-- run multiple worktrees in parallel
-
-At that point everything fights over `localhost` and default ports.
-
-The daily choice:
-
-- **Option A:** stop A → start B → ship fix → stop B → restart A  
-  you just spent 5–10 minutes paying the orchestration tax and nuking your focus.
-- **Option B:** don’t run it. code blind. push. let CI tell you what you broke.
-
-Neither scales. Both slow you down in dumb, repeatable ways.
-
-
-## Installation
+░░░░░   ░░░░░ ░░░░░   ░░░░░   ░░░░░░░░░  ░░░░░   ░░░░
+```
 
-### Prerequisites
-- **macOS**: supported.
-- **Docker + Compose**: [Orbstack](https://docs.orbstack.dev/quick-start) | [Docker Desktop](https://www.docker.com/get-started/) 
+Hack is a local-first platform for developers and agents who need to run more than one project, branch, or workflow at once.
 
-### Install
+It makes three promises: **run projects in parallel**, **normalize all your tickets**, and **manage project env safely**.
 
-**Option A: Shell script (CLI only)**
+When local dev breaks down, it usually breaks down in the same places: ports collide, work gets split across too many ticket systems, and env setup turns into tribal knowledge. Hack is the opinionated layer that makes those problems boring again.
 
-```bash
-curl -fsSL https://github.com/hack-dance/hack/releases/latest/download/hack-install.sh | bash
-```
+Sessions and integrations support those promises directly: sessions keep terminal work durable, and integrations let agents, ticket systems, and remote surfaces plug into the same project model.
 
-**Option B: macOS DMG (CLI + Desktop App)**
+## The Three Core Promises
 
-Download the latest DMG from [GitHub Releases](https://github.com/hack-dance/hack/releases/latest).
+### 1. Run projects in parallel
 
-The DMG includes:
-- **Hack Desktop** - macOS menu bar app for managing projects
-- **Install Hack CLI** - double-click to install the CLI to `~/.hack/bin`
+Hack lets each repo or branch run as its own isolated local environment instead of fighting over `localhost`, shared Docker networks, or ad-hoc port maps.
 
-### Setup
-```bash
-hack global install
-```
+- Run multiple repos at the same time.
+- Run multiple branches or worktrees of the same repo at the same time.
+- Keep service defaults like Postgres and Redis on their normal container ports.
+- Open stable HTTPS hostnames like `https://<project>.hack` and `https://api.<project>.hack`.
 
-### Quick start 
-Manual (CLI):
+Core commands:
 
 ```bash
-cd /path/to/your-repo
-hack init
 hack up --detach
+hack up --branch feature-x --detach
 hack open
+hack logs --pretty
 ```
 
-Agent-assisted (Cursor/Claude/Codex with shell access):
-
-```bash
-hack setup cursor   # or hack setup claude / hack setup codex
-hack setup agents   # optional: adds AGENTS.md + CLAUDE.md snippets
-hack setup sync --all-scopes   # optional: refresh project + user integrations
-hack agent init --client cursor   # or --client claude / --client codex
-hack agent patterns              # optional: dependency/ops checklist
-```
-
-If you omit `--client`, `hack agent init` will prompt you to choose (TTY only).
-If your agent does not auto-open, paste the output into the chat. Example:
-
-```
-I ran `hack agent init` and pasted the output below. Please follow it to set up hack for this repo,
-then run:
-- `hack init` (use --auto if dev scripts are detected)
-- `hack up --detach`
-- `hack open --json`
-If anything fails, use `hack logs --pretty` and summarize next steps.
-
-<PASTE HACK AGENT INIT OUTPUT HERE>
-```
-
-If the agent cannot run shell commands, use MCP instead: `hack setup mcp` and `hack mcp serve`.
-
-### Remote node runtime image (multi-node)
-
-Use the prebuilt node-runtime container to bootstrap remote nodes quickly (Linux/macOS hosts with Docker):
-
-```bash
-bun run build:node-runtime-image --tag hack-node-runtime:dev
-```
-
-Full operator guide: [`docs/guides/remote-node-container.md`](docs/guides/remote-node-container.md)
-
-### Tickets (optional, git-backed issue tracking)
-
-`hack` includes a lightweight, git-backed ticket system for tracking work without leaving your repo. Tickets are stored in a hidden git ref (`refs/hack/tickets`) so they sync with your code but don't clutter your branch list.
-
-**Quick setup:**
-
-```bash
-# Enable tickets for this repo
-hack x tickets setup
-
-# Create a ticket
-hack x tickets create --title "Add dark mode support"
-
-# List tickets
-hack x tickets list
-
-# Interactive TUI for managing tickets
-hack x tickets tui
-
-# Update status
-hack x tickets status T-00001 in_progress
-
-# Sync to remote
-hack x tickets sync
-```
-
-**Why use it:**
-- No external service required - tickets live in git
-- Agent-friendly - Claude/Cursor/Codex can create and manage tickets
-- Syncs with `git push/pull` via hidden refs
-- Works offline
-
-Tickets are ideal for solo devs, small teams, or agent-driven workflows where you want lightweight task tracking without context-switching to Jira/Linear/GitHub Issues.
-
-Full docs: [`docs/guides/tickets.md`](docs/guides/tickets.md)
-
-### macOS app (experimental)
-Source lives in `apps/macos`. See `apps/macos/README.md` for XcodeGen and build/run steps.
-Quick commands (repo root):
-
-```bash
-bun run macos:project-gen
-bun run macos:open
-bun run macos:dev
-bun run macos:build
-bun run macos:test
-```
-
-### Configuration (.hack/hack.config.json)
-- `name`: project slug (also used for Docker Compose project name)
-- `dev_host`: base hostname (`<dev_host>.hack`)
-
-*Optional `[logs]` settings*
-- `follow_backend`: `compose|loki` (default: `compose`)
-- `snapshot_backend`: `compose|loki` (default: `loki`)
-- `clear_on_down`: when running `hack down`, request Loki delete for this project (best-effort)
-- `retention_period`: e.g. `"24h"`; on `hack down`, prune older logs (best-effort)
-
-*Optional `[internal]` settings (container DNS/TLS)*
-- `dns`: use CoreDNS to resolve `*.hack` inside containers (default: `true`)
-- `tls`: mount Caddy Local CA + set common SSL env vars (default: `true`)
-- `extra_hosts`: static Compose `extra_hosts` entries (hostname → IP/target), merged into the internal override
-
-If you need **dynamic** `extra_hosts` (e.g. Pulumi outputs / local tunnels that change), use:
-
-```bash
-hack internal extra-hosts set <hostname> <target>
-hack internal extra-hosts unset <hostname>
-hack internal extra-hosts list
-```
-
-This writes `.hack/.internal/extra-hosts.json` and is merged into `extra_hosts` when you run `hack up` / `hack restart`.
-
-*Optional `[oauth]` settings (OAuth-safe alias host)*
-- `enabled`: when true, `hack init` generates Caddy labels so routed services answer on both:
-- primary: `https://<dev_host>`
-- OAuth alias: `https://<dev_host>.<tld>` (e.g. `https://sickemail.hack.gy`)
-- `tld`: optional (default: `"gy"`). Only `*.hack.gy` is bootstrapped automatically by `hack global install`; other TLDs require manual DNS setup.
-
-The file includes a JSON Schema reference for editor validation:
+### 2. Normalize all your tickets
 
-```json
-{
-  "$schema": "https://schemas.hack/hack.config.schema.json"
-}
-```
+Hack keeps a local-first, git-backed ticket substrate in your repo, then lets external systems like Linear sync into that substrate instead of forcing your workflow to live in five different places.
 
-Schemas are served locally by the global Caddy proxy at `https://schemas.hack`.
+- Track work in git with lightweight hack tickets.
+- Sync issues and projects with Linear when you need shared coordination.
+- Preserve ownership and provenance so local and synced tickets stay understandable.
+- Give the CLI, agents, and the macOS app one normalized ticket model to work against.
 
-Quick edits:
+Core commands:
 
 ```bash
-hack config get dev_host
-hack config set dev_host "myapp.hack"
-hack config set logs.snapshot_backend "compose"
+hack tickets setup
+hack tickets create --title "Investigate flaky auth flow"
+hack tickets list
+hack linear project-bind --project-id "<linear-project-id>"
+hack linear sync-project --from linear
 ```
 
-## Commands (high level)
-
-Run `hack help` (or `hack help <command>`) for full usage.
-
-Common:
-- `hack global install|up|down`
-- `hack init|up|down|logs|open|tui`
-- `hack status`
-- `hack remote setup`
-- `hack gateway enable`
-
-Full command table + flags: `docs/cli.md`.
+Docs:
 
-Run `hack help <command>` for detailed help.
+- [Tickets guide](docs/guides/tickets.md)
+- [Linear integration architecture](docs/guides/linear-integration-architecture.md)
 
-Project commands that call Docker Compose accept `--profile` (up/down/restart/ps/logs/run).
+### 3. Manage project env safely
 
-## JSON output
+Hack separates shareable env structure from secret values so teams and agents can understand what a project needs without leaking sensitive material into git.
 
-Use `--json` for machine-readable output:
+- Commit an env contract in `.hack/hack.env.json`.
+- Keep plain local values in gitignored `.hack/.env`.
+- Store secrets in the OS keychain or another configured backend.
+- Resolve env requirements before `hack up`, `hack run`, or `hack restart`.
 
-- `hack projects --json`
-- `hack ps --json`
-- `hack logs --json` (NDJSON stream; use `--no-follow` for snapshots)
-- `hack open --json` (returns `{ "url": "..." }`)
-
-When the daemon is running, `hack projects --json` and `hack ps --json` use it for faster results.
-
-`hack logs --json` emits event envelopes (`start`, `log`, `end`) so MCP/TUI consumers can stream safely.
-
-## Daemon (optional)
-
-`hackd` is a local daemon that caches Docker state for fast status/ps queries.
-
-```bash
-hack daemon start
-hack daemon status
-hack daemon metrics
-hack daemon stop
-hack daemon logs
-```
-
-### launchd integration (macOS)
-
-On macOS, you can install `hackd` as a launchd service for automatic management:
+Core commands:
 
 ```bash
-# Install (auto-start on login by default)
-hack daemon install
-
-# Install without auto-start (manual start/stop via launchd)
-hack daemon install --no-run-at-load
-
-# Uninstall the launchd service
-hack daemon uninstall
+hack env list
+hack env set AWS_PROFILE=dev
+hack env set --secret DATABASE_URL=postgres://...
+hack env backend status
 ```
 
-Options:
-- `--run-at-load` / `--no-run-at-load`: Start automatically on login
-- `--gui-only` / `--no-gui-only`: Only run in GUI sessions (default: GUI only)
-
-The service uses label `dance.hack.hackd` and writes to `~/Library/LaunchAgents/`.
-
-Use it when:
-- You run `hack projects --json` / `hack ps --json` frequently (scripts, agent workflows, TUI).
-- You want faster status snapshots without shelling out to Docker each time.
-
-Skip it when:
-- You prefer zero background processes.
-- You rarely use JSON status/ps outputs.
-
-If it is not running (or version-mismatched), the CLI falls back to direct Docker calls.
-
-## Control plane + extensions (optional)
-
-`hack` includes a small control-plane kernel so features like jobs, tickets, and remote access can
-ship as extensions without bloating the core CLI.
+Docs:
 
-- Extension commands run via `hack x <namespace> <command>`.
-- Global control-plane config lives at `~/.hack/hack.config.json` (`hack config set --global ...`).
-- Per-project overrides live in `.hack/hack.config.json` and win over global values.
-- `controlPlane.gateway.enabled` is project-scoped and implicitly enables the gateway extension.
+- [Env and secrets](docs/env.md)
 
-See `SPECS/control-plane/consolidated.md` and `docs/extensions.md` for the extension SDK surface.
+## First Run
 
-### Gateway (remote access)
+### Prerequisites
 
-The gateway exposes `hackd` over HTTP/WS with token auth. It binds to `127.0.0.1` by default and
-should be exposed via a Zero Trust/VPN or SSH tunnel when needed. `hack remote setup` is the
-one-command flow that enables the gateway, creates a token, and can configure + start exposure
-(Cloudflare/Tailscale/SSH) via prompts. It prints a QR by default (use `--no-qr` to skip).
+- macOS
+- Docker + Compose via [OrbStack](https://docs.orbstack.dev/quick-start) or [Docker Desktop](https://www.docker.com/get-started/)
 
-```bash
-hack remote setup
-# or:
-hack gateway setup
-# or manually:
-hack gateway enable
-hack daemon stop && hack daemon start
-hack x gateway token-create
-```
+### 1. Install Hack
 
-Gateway tokens default to read-only. For non-GET requests, set
-`controlPlane.gateway.allowWrites = true` globally and create a write-scoped token:
+CLI only:
 
 ```bash
-hack config set --global 'controlPlane.gateway.allowWrites' true
+curl -fsSL \
+  https://github.com/hack-dance/hack/releases/latest/download/hack-install.sh \
+  | bash
 ```
 
-```bash
-hack x gateway token-create --scope write
-```
-
-Current gateway API (HTTP/WS):
-- status/metrics/projects/ps (`/v1/*`)
-- supervisor jobs: list/create/show/cancel + log/event stream (`/control-plane/*`)
-- supervisor shells: create/show + PTY stream (write token + allowWrites)
-- CLI shell client: `hack x supervisor shell` (gateway + write token required)
-
-Interactive shells are available over the gateway WebSocket; the CLI can attach with
-`hack x supervisor shell` (write token + allowWrites required). Use SSH/Zero Trust for a full
-terminal UI, or run commands via supervisor jobs.
-
-See `docs/gateway-api.md` for full API usage, structured workflow patterns, and a runnable demo.
-
-Remote access options (recommended order):
-1) SSH tunnel to the gateway port for quick, ad-hoc access.
-2) Zero Trust/VPN (Tailscale, Cloudflare, etc.) for persistent access.
-3) Optional Caddy route (`https://gateway.hack`) for local convenience.
+CLI + desktop app:
 
-Note: Cloudflare Tunnel is ideal for the gateway HTTP/WS surface. It is not a direct SSH
-replacement on iOS; use Tailscale/VPN for SSH access from mobile clients.
-If you already use Cloudflare WARP, configure a private network route to your laptop and
-use that IP/hostname for SSH in your mobile client.
+- Download the latest DMG from [GitHub Releases](https://github.com/hack-dance/hack/releases/latest)
+- Install the CLI from the DMG
+- Optionally keep the macOS app for the beta desktop surface
 
-Remote helper:
-- `hack remote` shows status and offers to run setup when needed.
-- `hack remote status` prints gateway + exposure status.
-- `hack remote qr` prints a QR payload for SSH or gateway usage (confirm before sharing).
-- `hack remote monitor` opens a mini TUI (status + gateway audit log tail).
-
-Cloudflare tunnel helper:
+### 2. Set up your machine
 
 ```bash
-hack x cloudflare tunnel-setup --hostname gateway.example.com
-hack x cloudflare tunnel-start
+hack global install
 ```
 
-Tailscale helper:
+### 3. Start your first project
 
 ```bash
-hack x tailscale setup
-hack x tailscale status
+cd /path/to/your-repo
+hack init
+hack up --detach
+hack open
 ```
 
-DNS note: `cloudflared tunnel route dns <tunnel> <hostname>` creates the required CNAME to
-`<tunnel-id>.cfargotunnel.com` in your Cloudflare zone (proxied).
-
-### Supervisor (jobs + shells)
+If you want the shortest non-interactive path for an existing repo, use `hack init --auto`.
 
-The supervisor is the job/shell runner that powers agent workflows and remote execution. It can run
-commands, stream logs, and host PTY-backed shells. Use it locally with `hack x supervisor` or
-remotely over the gateway.
+### 4. Optional: install agent integrations
 
-Docs: `docs/supervisor.md`.
-
-## Docs
-
-Start here:
-- `docs/README.md` (index)
-- `docs/architecture.md`
-- `docs/gateway.md`
-- `docs/extensions.md`
-
-## Agent setup (CLI-first)
-
-Use `hack setup` to install local integrations. Default is project scope; add `--global` for user scope.
+Use these when you want Cursor, Claude, or Codex to understand Hack workflows directly.
 
 ```bash
 hack setup cursor
 hack setup claude
 hack setup codex
-hack setup agents
 hack setup sync --all-scopes
 ```
 
-What each setup command does:
-- `hack setup cursor`: installs Cursor rules in `.cursor/rules/hack.mdc`
-- `hack setup claude`: installs Claude Code hooks in `.claude/settings.local.json` (or user scope)
-- `hack setup codex`: installs the Codex skill in `.codex/skills/hack-cli/SKILL.md`
-- `hack setup agents`: adds/updates hack usage snippets in `AGENTS.md` and `CLAUDE.md`
-- `hack setup mcp`: writes MCP configs for no-shell clients
-- `hack setup sync --all-scopes`: refreshes docs, skills, and MCP config at project + user scope
-
-Automatic guardrail:
-- Project-level `hack` commands (interactive sessions) auto-check docs/skills/MCP drift and attempt auto-sync.
-- To warn-only: `HACK_SETUP_SYNC_MODE=warn`
-- To disable: `HACK_SETUP_SYNC_MODE=off`
-
-Primer helpers:
-- `hack agent prime`: short CLI-first primer used by Claude Code hooks
-- `hack agent init`: repo-specific setup prompt agents can follow to scaffold/verify hack config
-- `hack agent init --client cursor|claude|codex`: open the prompt directly in an agent client
-- `hack agent patterns`: dependency/ops checklist for agents
-
-Recommended flow:
-- Use `hack setup cursor|claude|codex` for your agent client
-- Use `hack setup agents` to document hack usage inside the repo
-- Use `hack setup sync --all-scopes` after `hack update` to refresh generated integrations
-- Use `hack setup mcp` only when the agent has no shell access
-
-## MCP (no-shell clients)
-
-Use MCP only when the CLI is not available (e.g. no shell access).
-
-Run the MCP server locally over stdio:
-
-```bash
-hack mcp serve
-```
-
-Most MCP clients spawn this on demand. Running it directly will wait for a client connection.
-
-Install MCP configs (Cursor, Claude CLI, Codex):
+If your agent does not have shell access, use MCP instead:
 
 ```bash
-# Project-scoped (default via setup)
-hack setup mcp
-
-# User-scoped (default; writes to your home config directories)
-hack mcp install --all
-
-# Project-scoped (writes .cursor/.claude/.codex in the repo)
 hack mcp install --all --scope project
 ```
 
-Project scope writes `.cursor/mcp.json`, `.claude/settings.json`, and `.codex/config.toml`.
-For `--scope project`, `hack mcp install` also updates `AGENTS.md` and `CLAUDE.md` by default.
+Docs:
 
-Print config snippets without writing:
+- [Initialize a project](docs/guides/init-project.md)
+- [CLI reference](docs/cli.md)
 
-```bash
-hack mcp print --codex
-```
+## Supporting Capabilities
 
-`hack init` can prompt to install local agent integrations after scaffolding a repo.
-For agent-driven scaffolding without prompts, use `hack init --auto` and run `hack setup` manually.
+### Sessions
 
-## Branch builds (worktree-friendly)
+Sessions keep terminal work durable. They are not the headline promise, but they are a first-class support capability for parallel project work, remote access, and long-running agents.
 
-Use `--branch <name>` on project commands to run isolated instances with unique hostnames and compose
-project names:
+- Backed by `tmux` or `zellij`
+- Started from the project root, not from `.hack/`
+- Useful for remote attach, agent execution, and multi-terminal workflows
 
 ```bash
-hack up --branch feature-x --detach
-hack logs --branch feature-x
-hack open --branch feature-x
+hack session
+hack session start my-project --up
+hack session attach my-project
+hack session exec my-project "bun test"
 ```
 
-Using `--branch` will create/update `.hack/hack.branches.json` with a `last_used_at` timestamp. Branch
-instances show up in `hack projects --details`.
-
-Optional: track branch aliases in `.hack/hack.branches.json` for quick lookup:
-
-```bash
-hack branch add feature-x --note "worktree for PR 123"
-hack branch list
-hack branch open feature-x
-```
-
-
-## Service-to-service connections (HTTP vs DB/Redis)
-
-If your app runs in Docker (the default in `hack`), don’t connect to `127.0.0.1` / `localhost` for Postgres/Redis.
-Inside a container, `localhost` is that container, not the other compose services.
-
-If you previously ran everything on your host and used `localhost:PORT`, update those references when you
-move into containers:
+Docs:
 
-- **HTTP services**: use the same `https://*.hack` hostname you open from the host (whatever you configured in Caddy labels, e.g. `https://api.myapp.hack`).
-- **Non-HTTP services** (DB/Redis/etc.): use the Compose service hostname (e.g. `db`, `redis`).
+- [Sessions](docs/sessions.md)
 
-For HTTP services, use the same `https://*.hack` URLs you use on the host. `hack up` injects internal DNS,
-TLS trust, and `extra_hosts` mappings so `*.hack` resolves reliably inside containers. If you see `ENOTFOUND`
-inside containers, run `hack restart` to refresh the host mappings.
+### Integrations
 
-For non-HTTP services, use the Compose service hostname on the default network:
+Integrations make the core promises more usable without changing what Hack is.
 
-- `Postgres: db:5432`
-- `Redis: redis:6379`
-
-Note: Caddy’s CA is mounted into containers when `internal.tls: true` so HTTPS calls to `*.hack` work for most runtimes.
-If you’re using Java/Kotlin, you’ll need to import the CA into the JVM truststore manually.
-
-Example:
-
-```yaml
-environment:
-  DATABASE_URL: postgres://postgres:postgres@db:5432/mydb
-  REDIS_URL: redis://redis:6379
-```
-
-If you need host access for debugging, prefer `docker compose exec` so you don’t reintroduce port conflicts:
-
-```bash
-docker compose -f .hack/docker-compose.yml exec db psql -U postgres -d mydb
-docker compose -f .hack/docker-compose.yml exec redis redis-cli
-```
+- Agent integrations via `hack setup`
+- MCP for no-shell clients via `hack mcp`
+- Linear as a ticket-normalization extension, not the center of the product
 
-## Logs (why both Compose and Loki)
+If your agent has shell access, prefer the CLI. Use MCP only when shell access is unavailable.
 
-By default, `hack logs` uses `docker compose logs` because it’s the lowest latency tail.
-The daemon does not proxy logs yet; `hack logs` still talks directly to Docker Compose or Loki.
+Docs:
 
-Loki is still valuable for:
+- [Extensions](docs/extensions.md)
+- [Gateway overview](docs/gateway.md)
 
-- querying across time (history)
-- filtering by labels (project/service/container)
-- Grafana Explore / dashboards
+## Beta Capabilities
 
-### CLI
+> Beta surfaces are real and useful, but they are not the core promise of Hack yet.
 
-```bash
-# Tail (fast)
-hack logs --pretty
+### Remote control plane
 
-# Snapshot
-hack logs --no-follow --pretty
+The gateway, supervisor, and remote shell flows let you control Hack over HTTP and remote transports. This is the foundation for off-device control, but it is still a secondary surface.
 
-# Snapshot JSON
-hack logs --no-follow --json
+Docs:
 
-# Query/history (force Loki)
-hack logs --loki --pretty
+- [Gateway overview](docs/gateway.md)
+- [Gateway API](docs/gateway-api.md)
+- [Supervisor](docs/supervisor.md)
 
-# Range (Loki only)
-hack logs --loki --since 2h --pretty
-hack logs --loki --since 4h --until 1h --pretty
+### Multi-node
 
-# Filter Loki by service
-hack logs --loki --services api,worker --pretty
+Hack can pair remote nodes, bootstrap workspaces, and dispatch work across machines. This is useful when your local machine is not enough, but it is still beta-level product surface area.
 
-# Raw LogQL
-hack logs --loki --query '{project="my-project"} |= "error"' --pretty
-```
+Docs:
 
-### Grafana
+- [Remote node quickstart](docs/guides/remote-node-quickstart.md)
+- [Remote node container guide](docs/guides/remote-node-container.md)
+- [Remote supervisor guide](docs/guides/remote-supervisor.md)
 
-- Open: `hack open logs` or visit `https://logs.hack`
-- Explore queries:
+### macOS app
 
-```logql
-{project="my-project"}
-{project="my-project", service="api"}
-```
+Hack Desktop gives you a native dashboard for projects, tickets, sessions, and integrations. It is a beta companion to the CLI, not the primary entry point.
 
-Alloy labels logs with:
+Docs:
 
-- project: `Docker Compose project name`
-- service: `Docker Compose service name`
-- container: `Docker container name`
+- [macOS app README](apps/macos/README.md)
 
+## How Hack Works
 
-## Projects registry (bird’s-eye view)
+- Project config lives in `.hack/`.
+- Each project or branch instance gets its own isolated Docker network and compose identity.
+- A global Caddy proxy gives routed services stable local HTTPS hostnames.
+- `hack logs` uses Compose for the fast path and Loki/Grafana for history and querying.
+- `hackd` is an optional daemon for faster `projects` and `ps` snapshots.
 
-`hack` maintains a best-effort registry under `~/.hack/projects.json` so you can target a project from anywhere:
+Useful commands:
 
 ```bash
+hack help
 hack projects
-hack logs --project my-project --pretty
-hack up --project my-project
-```
-
-## .hack and valid tld requirements
-
-OAuth providers (notably Google) require `localhost` or a host that ends with a real public suffix.
-
-We keep `.hack` as the primary local dev domain, and optionally expose an alias domain for OAuth flows.
-If the OAuth alias is enabled, `hack global install` configures `*.hack.gy` to resolve to the Caddy
-container IP via dnsmasq + the OS resolver (bypasses port forwarding issues with Tailscale/VPNs).
-
-Routing rules:
-
-- `https://*.hack` is the default local-dev hostname space.
-- `https://*.hack.gy` is an OAuth-safe alias host space (public-suffix-style domain).
-- Only services with Caddy labels and attached to `hack-dev` are exposed via these hostnames.
-- These domains are local routes by default; use tunnels/remote ingress separately for internet-reachable webhooks.
-
-If you use Next.js (or another dev server that cares about dev origins), configure its dev allowlist to include the proxy domains.
-Next.js supports `allowedDevOrigins` (wildcards supported) in `next.config.js`:
-
-```js
-module.exports = {
-  allowedDevOrigins: ["*.hack", "*.hack.gy"],
-}
-```
-
-Optionally you can pass in your own custom `dev_host` to the config.
-
-
-## SSL
-
-`hack` uses Caddy’s internal PKI to issue certs for `*.hack` (and any OAuth alias host). This covers
-HTTPS for services routed through Caddy, but it does not create cert/key files for services running
-outside of Caddy.
-
-- macOS: run `hack global trust` to trust the Caddy Local CA in the System keychain.
-- Other OS: run `hack global ca` to export the CA cert path, then add it to your OS/browser trust store.
-- If you need the PEM directly: `hack global ca --print`.
-- If you are running a local service outside of Caddy, use `hack global cert <host...>` (mkcert required) to generate a cert/key under `~/.hack/certs` and wire it into your service. This is only needed for non-Caddy services that still want trusted TLS.
-- macOS: `hack global install` can optionally install mkcert (needed for `hack global cert`).
-
-Install mkcert if you don't already have it (macOS example):
-
-```bash
-brew install mkcert
-mkcert -install
-```
-
-Example (non-Caddy service):
-
-```bash
-hack global cert --install api.myapp.hack
-```
-
-Use `--out <dir>` if you want certs written somewhere else.
-
-## Internal DNS (containers)
-
-`hack global install` runs CoreDNS on the `hack-dev` network. CoreDNS answers `*.hack` and `*.hack.*` with
-Caddy’s current IP so containers can use the same `https://*.hack` URLs as the host.
-
-This is the core isolation model: each repo keeps its own compose network, while routed HTTP services get stable hostnames
-through shared Caddy ingress. That means you can call local services by hostname from host or container without relying on
-host-published `localhost:<port>` patterns.
-
-Some runtimes don’t honor custom DNS for `*.hack` reliably, so `hack up` also injects `extra_hosts` mappings
-to the Caddy IP. If the Caddy IP changes, `hack status`, `hack doctor`, and the TUI show a warning; fix it
-with `hack restart` to refresh the mapping.
-
-If you also need `extra_hosts` for non-`*.hack` hostnames (common when you run host-local tunnels/proxies
-and want containers to reach them by their real domain), use `hack internal extra-hosts set` to write a
-repo-local `.hack/.internal/extra-hosts.json` that gets merged into the generated Compose override.
-
-When `internal.tls` is enabled, `hack up` mounts the Caddy Local CA into each container and sets common
-SSL env vars so HTTPS to `*.hack` is trusted inside containers.
-
-If you update `hack`, rerun `hack global install` once to refresh the CoreDNS config.
-
-
-
-
-## Why not just use X?
-
-### Docker / Compose alone
-
-They run containers. They don’t give you stable hostnames, HTTPS, or a way to run many isolated copies of the same stack without custom glue. 
-
-You can build that layer yourself. I did. That’s this.
-
-### Kubernetes
-
-Kubernetes solves cluster orchestration. This problem is local parallelism.  
-It adds complexity without fixing ports, routing, or developer feedback loops.
-
-### Different ports
-
-This is the default answer and it doesn’t scale.  
-Ports leak into config, break OAuth and cookies, and turn into debt.  
-Hostnames scale. Ports don’t.
-
-There isn’t an off-the-shelf tool that gives you full local network isolation, real HTTPS, and near zero per-repo setup.
-
-If you want that, you have to build it yourself.
-
-
-## How it works
-
-`hack` is a thin layer on top of Docker Compose plus a tiny global proxy.
-
-- each project/branch runs in its own Docker network
-- services use their normal ports inside that network
-- a shared proxy routes `https://*.hack` and handles HTTPS
-- logs are captured centrally
-
-Your code doesn’t change. Your mental overhead does.
-
-### Global (once per machine)
-
-`hack global install` provisions `~/.hack/` and starts:
-
-- **Caddy** (`lucaslorentz/caddy-docker-proxy`) on ports `80/443`
-  - watches Docker labels and auto-routes `https://*.hack`
-- **Logging stack**: Grafana + Loki + Alloy
-  - reachable via `https://logs.hack`
-
-### Per-project (per repo)
-
-`hack init` creates `.hack/` in the repo root:
-
-- `.hack/docker-compose.yml`: your project services
-- `.hack/hack.config.json`: project config (name, dev host, log preferences)
-
-Each project’s compose network stays isolated; only services you want “public” get attached to the shared ingress network so Caddy can reach them.
-
-
-## Common patterns (deps + ops)
-
-Agents: run `hack agent patterns` for a compact checklist based on this section.
-
-### 1) Containerized dependency installs (recommended)
-
-If you run `bun install` on the host and then start Linux containers, you can hit platform
-mismatches (native modules, postinstall scripts, OS-specific binaries). The clean pattern is to
-install dependencies **inside** Docker and share them via a volume.
-
-Add a one-shot deps service and make your app services depend on it:
-
-```yaml
-deps:
-  image: imbios/bun-node:latest
-  working_dir: /app
-  volumes:
-    - ..:/app
-    - node_modules:/app/node_modules
-  command: bun install
-  networks:
-    - default
-
-www:
-  image: imbios/bun-node:latest
-  working_dir: /app/apps/www
-  volumes:
-    - ..:/app
-    - node_modules:/app/node_modules
-  depends_on:
-    deps:
-      condition: service_completed_successfully
-```
-
-This keeps dependency resolution in the same OS as your containers and avoids host/guest drift.
-
-### 2) Networked ops commands (DB schema tooling, migrations)
-
-Because `hack` avoids publishing DB ports to your host, run schema/ops commands inside the
-compose network.
-
-Option A (recommended): add an ops-only service:
-
-```yaml
-db-ops:
-  image: imbios/bun-node:latest
-  working_dir: /app/packages/db # where your db schema + package.json live
-  volumes:
-    - ..:/app
-    - node_modules:/app/node_modules
-  environment:
-    DATABASE_URL: postgres://postgres:postgres@db:5432/mydb
-  depends_on:
-    - db
-    - deps
-  networks:
-    - default
-  profiles: ["ops"]
-  # Examples:
-  # - Prisma:  bunx prisma migrate deploy
-  # - Drizzle: bunx drizzle-kit push
-  command: bun run db:push
-```
-
-Run it on demand:
-
-```bash
-docker compose -f .hack/docker-compose.yml --profile ops run --rm db-ops
-```
-
-Option B: run via `hack run` (thin wrapper over `docker compose run --rm`):
-
-```bash
-hack run --workdir /app/packages/db email-sync -- bunx prisma generate
-hack run --workdir /app/packages/db email-sync -- bunx prisma migrate dev
-hack run --workdir /app/packages/db email-sync -- bunx drizzle-kit push
-hack run --workdir /app bun run turbo db:migrate
-```
-
-If your ops service is behind a compose profile, enable it:
-
-```bash
-hack run --profile ops --workdir /app/packages/db db-ops -- bun run db:push
+hack status
+hack daemon start
+hack open logs
 ```
 
-See examples:
-- `examples/next-app/README.md`
-
-
-## Troubleshooting
-
-- `*.hack` doesn’t resolve: run `hack doctor`, then `hack global install` (macOS: ensure dnsmasq is running).
-
-- Stale global setup / CoreDNS issues: run `hack doctor --fix` (refreshes network + CoreDNS + CA).
-
-- TLS warnings: run `hack global trust` (macOS).
-
-- Logs missing in Grafana: ensure Alloy is running (`hack global status`) and try `{app="docker"}` in Explore.
-
-- `ENOTFOUND` for `*.hack` inside containers: run `hack restart` to refresh `extra_hosts` mappings (check
-  `hack status` or the TUI for Caddy IP mismatch warnings).
+## Documentation
 
-- `EAI_AGAIN` for external domains inside containers (e.g. `api.clerk.com`): CoreDNS isn’t forwarding.
-  Run `hack global install` and restart CoreDNS:
-  `docker compose -f ~/.hack/caddy/docker-compose.yml restart coredns`.
-
-- `hack global up` warns about `hack-dev` network labels or missing subnet: remove the network and reinstall:
-  `docker network rm hack-dev` then `hack global install`.
-
-- OAuth redirect errors: use the OAuth alias host (`*.hack.gy`) or `localhost` (providers may reject non-public suffixes like `.hack`).
+Start here:
 
+- [Docs index](docs/README.md)
+- [CLI reference](docs/cli.md)
+- [Architecture](docs/architecture.md)
+- [Env and secrets](docs/env.md)
+- [Sessions](docs/sessions.md)
+- [Extensions](docs/extensions.md)
 
+Common guides:
 
-## Development
+- [Initialize a project](docs/guides/init-project.md)
+- [Tickets guide](docs/guides/tickets.md)
+- [Remote node quickstart](docs/guides/remote-node-quickstart.md)
+- [Global settings](docs/guides/global-settings.md)
 
-### From source
+## Develop From Source
 
 ```bash
 bun install
 bun run install:dev
 hack --help
 ```
-This installs a small `hack` shim into `~/.hack/bin/hack` that runs your working tree directly (no rebuild needed).
-
-If `hack` isn’t found, add this to your shell config:
-
-```bash
-export PATH="$HOME/.hack/bin:$PATH"
-```
-
-### Compiled binary (release-like)
-
-```bash
-bun install
-bun run install:bin
-hack --help
-```
-This builds `dist/hack` via `bun build --compile` and installs it to `~/.hack/bin/hack`.
 
-### Check which install is active
+Useful repo commands:
 
 ```bash
-bun run install:status
+bun test
+bun x ultracite check
 ```
-Reports whether `hack` is a dev shim or a compiled binary (and where it points).
-
-
-### Run in place
-
-```bash
-bun dev --help
-```
-
-### Tests
-
-```bash
-bun run test
-```
-
-Runs workspace tests via Turbo (`@hack/cli`, `@hack/auth-broker`, `@hack/db`).
-
-### Workspace command model
-
-Root commands are orchestration wrappers. For package-local work, run commands directly:
-
-```bash
-bun run --cwd packages/cli build
-bun run --cwd packages/cli macos:ghostty:bundle
-bun run --cwd services/auth-broker test
-bun run --cwd packages/db db:migrate
-```
-
-### Conventional commits
-
-```bash
-bun run commit
-```
-
-Commitlint runs on `git commit` via husky, and semantic-release uses Conventional Commits to
-compute versions.
-
-### Build a standalone binary
-
-```bash
-bun run build
-./dist/hack --help
-```
-
-### Build a release bundle
-
-```bash
-bun run build:release
-```
-Produces `dist/release/hack-<version>-release/`, a tarball, and `hack-install.sh`.
-
-### Release (tag + GitHub workflow)
-
-```bash
-bun run release:prepare
-git push --follow-tags
-```
-
-Updates `CHANGELOG.md` plus root/workspace `package.json` versions, creates the release commit and tag, and triggers the GitHub Release workflow on push.
-
-See `PACKAGING.md` for details.
-
-
-See also:
-- [Examples](examples/next-app/README.md)
-- [Docs](docs/README.md)
-- [Architecture](docs/architecture.md)
-
-
-<p align="right">(<a href="#readme-top">back to top</a>)</p>

From fcad81474b47cb1d3c24a308efa7c7a1da52fd2e Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:10:19 +0000
Subject: [PATCH 016/134] docs: define teams and organizations admin program

---
 ...ams-and-organizations-management-design.md | 488 ++++++++++++++++++
 ...teams-and-organizations-management-plan.md | 299 +++++++++++
 2 files changed, 787 insertions(+)
 create mode 100644 docs/plans/2026-03-14-teams-and-organizations-management-design.md
 create mode 100644 docs/plans/2026-03-14-teams-and-organizations-management-plan.md

diff --git a/docs/plans/2026-03-14-teams-and-organizations-management-design.md b/docs/plans/2026-03-14-teams-and-organizations-management-design.md
new file mode 100644
index 000000000..d725e4a1e
--- /dev/null
+++ b/docs/plans/2026-03-14-teams-and-organizations-management-design.md
@@ -0,0 +1,488 @@
+# Teams and Organizations Management Design
+
+## Context
+
+Hack already has partial team and organization signals in broker-backed auth and integration state, but the administrative contract is still implicit. That is acceptable for single-user local workflows and unacceptable for shared ownership, project transfer, or environment sharing.
+
+The missing piece is not only storage. The product needs an explicit command model, explicit trust boundaries, and explicit privilege escalation rules so users can answer three questions without guessing:
+
+- who owns this resource?
+- who can act on it?
+- is this operation local-only or broker-mediated?
+
+## Goals
+
+- Define a command model for organizations, teams, projects, and shared envs.
+- Make privileges explicit and secure by default.
+- Tie team/org administration directly to project ownership and env sharing.
+- Preserve Hack's local-first workflow while making shared admin operations clearly remote.
+- Break the work into child issues that cover lifecycle, permissions, and admin boundaries.
+
+## Non-Goals
+
+- Do not make local `hack up`, `hack down`, `hack logs`, `hack session`, or local tickets require sign-in.
+- Do not introduce hidden auto-sharing of local secrets or project state.
+- Do not collapse provider identity into Hack org/team identity.
+- Do not design billing, quotas, or enterprise SSO in this slice.
+
+## Approaches Considered
+
+### 1. Broker-first administration everywhere
+
+Treat all team, org, project ownership, and env management as broker-owned from day one.
+
+Why reject it:
+- It conflicts with the repo's existing local-first behavior.
+- It would turn previously local project/admin actions into authenticated cloud operations.
+- It creates a larger migration and failure surface than the milestone requires.
+
+### 2. Local-first with explicit broker escalation
+
+Keep local workflows local. Introduce org/team lifecycle, shared project ownership, and shared env operations as broker-mediated features with explicit commands and explicit auth requirements.
+
+Why recommend it:
+- It matches current `hack auth`, env contract, and gateway boundary patterns.
+- It preserves offline and single-user workflows.
+- It gives shared collaboration a trustworthy model without hidden trust assumptions.
+
+### 3. Team-only model with organizations deferred
+
+Support teams as the top-level shared scope now and postpone orgs.
+
+Why reject it:
+- The current broker auth responses already expose organization and team context.
+- Project transfer, team creation, and future policy inheritance are cleaner with an explicit org container.
+- Deferring orgs would force a second administrative migration later.
+
+## Approved Direction
+
+Adopt approach 2: local-first with explicit broker escalation.
+
+Core rule:
+
+- local-only resources stay local and unauthenticated
+- shared resources require Hack auth and broker mediation
+
+There is no silent promotion from local to shared.
+
+## Resource Model
+
+Hack administration needs four resource layers:
+
+### User
+
+- The local operator on a machine.
+- May also be an authenticated Hack account principal.
+- Owns local-only projects and local-only env values by default.
+
+### Organization
+
+- Top-level shared administrative boundary.
+- Owns teams.
+- Can own projects directly when the project is meant to be org-wide rather than team-scoped.
+
+### Team
+
+- Collaboration boundary inside an organization.
+- Primary shared owner for most projects.
+- Membership alone does not grant env write access.
+
+### Project
+
+- Runtime and collaboration unit for a repo/workspace.
+- Has an explicit owner scope:
+  - `user`
+  - `team`
+  - `organization`
+- Ownership determines who can administer access, but does not automatically expose secret values.
+
+### Environment Bundle
+
+- Named set of declared env keys and optionally broker-portable secret material.
+- Has its own access policy and lifecycle.
+- Can be attached to a project, but attachment is not the same as disclosure.
+
+## Ownership and Scope Rules
+
+### Project ownership
+
+Every project must resolve to one of two modes:
+
+- `local`
+  - owned by the current user/device context
+  - no broker dependency
+- `shared`
+  - owned by a Hack team or organization
+  - broker-backed metadata and access grants
+
+Default is `local`.
+
+Projects are only promoted to `shared` through an explicit transfer/share command.
+
+### Env ownership
+
+Every env bundle must resolve to one of three policies:
+
+- `local_only`
+  - values remain in `.hack/.env`, local keychain, or configured local secret backend
+- `shared_metadata_only`
+  - contract, descriptions, and required keys are shared; values remain local
+- `shared_values`
+  - encrypted values are broker-mediated and access-controlled
+
+Default is `local_only`.
+
+The default shared policy for newly shared projects is still `local_only`. Sharing a project must not silently share secrets.
+
+## Role Model
+
+Roles are intentionally minimal and explicit.
+
+### Organization roles
+
+- `org_owner`
+  - delete org
+  - transfer org ownership
+  - manage org admins
+  - create/delete teams
+  - override project ownership within the org
+- `org_admin`
+  - invite/remove members
+  - create/archive teams
+  - manage shared projects and grants
+  - cannot delete org or transfer org ownership
+- `org_member`
+  - can view org/team membership they belong to
+  - no admin rights by default
+
+### Team roles
+
+- `team_admin`
+  - manage team membership
+  - administer team-owned projects
+  - administer team env grants
+- `team_member`
+  - use team resources only where separately granted
+
+### Project roles
+
+- `project_owner`
+  - transfer project ownership
+  - grant/revoke project access
+  - manage project-level policies
+- `project_maintainer`
+  - manage project runtime/admin settings
+  - cannot transfer ownership
+- `project_operator`
+  - run approved project actions
+  - cannot change access policy
+- `project_viewer`
+  - inspect metadata and status only
+
+### Env roles
+
+- `env_admin`
+  - rotate values
+  - grant/revoke env access
+  - change env sharing mode
+- `env_consumer`
+  - resolve values for permitted runs
+- `env_metadata_viewer`
+  - inspect contract and state without value access
+
+## Secure-by-Default Rules
+
+- Local projects start as `local` and private.
+- Shared projects do not automatically disclose env values.
+- Team membership does not automatically grant project admin.
+- Project access does not automatically grant env value access.
+- Broker writes require authenticated Hack account context.
+- Destructive admin actions require explicit target scope and fail closed when scope is ambiguous.
+- CLI defaults to read-only inspection when ownership or auth state is unresolved.
+
+## Command Model
+
+The command model should reflect the trust boundary instead of hiding it.
+
+### `hack auth`
+
+Purpose:
+- authenticate the Hack account used for broker-mediated operations
+
+Rules:
+- remains separate from provider auth
+- required for org/team/shared-project/shared-env admin
+- not required for local-only runtime commands
+
+### `hack org`
+
+Broker-mediated only.
+
+Primary surface:
+- `hack org list`
+- `hack org show <org>`
+- `hack org create`
+- `hack org invite`
+- `hack org members list`
+- `hack org members remove`
+- `hack org teams list`
+
+Rule:
+- no local-only `org` mode; organizations are shared constructs
+
+### `hack team`
+
+Broker-mediated only.
+
+Primary surface:
+- `hack team list`
+- `hack team show <team>`
+- `hack team create`
+- `hack team archive <team>`
+- `hack team members list`
+- `hack team members add`
+- `hack team members remove`
+
+Rule:
+- teams only exist inside an organization
+- team lifecycle must always be explicit and authenticated
+
+### `hack project owner`
+
+Hybrid surface.
+
+Primary surface:
+- `hack project owner show`
+- `hack project owner set --user self`
+- `hack project owner transfer --team <team>`
+- `hack project owner transfer --org <org>`
+
+Rules:
+- `show` works for local and shared projects
+- setting local user ownership remains local-only
+- transfer to team/org is broker-mediated and explicit
+- transfer must not succeed unless the caller holds the required admin role in the target scope
+
+### `hack project access`
+
+Hybrid surface with a sharp boundary.
+
+Primary surface:
+- `hack project access list`
+- `hack project access grant`
+- `hack project access revoke`
+
+Rules:
+- local projects may expose only local access metadata if any
+- team/org grants are only valid for shared projects
+- commands fail with a clear error if the project is still local
+
+### `hack env`
+
+Split into local env management and shared env management.
+
+Local surfaces remain:
+- `hack env list`
+- `hack env set`
+- `hack env unset`
+- `hack env backend ...`
+
+New shared surfaces:
+- `hack env share enable`
+- `hack env share disable`
+- `hack env access list`
+- `hack env access grant`
+- `hack env access revoke`
+- `hack env rotate`
+
+Rules:
+- plain `hack env set` stays local by default
+- sharing env metadata or values is a separate command
+- secret value disclosure requires both project context and env grant context
+
+## Local vs Broker Boundary
+
+This boundary must be product-visible and documentation-visible.
+
+### Local-only operations
+
+- local project/runtime management
+- local sessions
+- local tickets
+- local `.hack/.env` editing
+- local secret backend configuration
+- local project owner inspection
+- local user ownership assignment
+
+### Broker-mediated operations
+
+- organization lifecycle
+- team lifecycle
+- org/team membership changes
+- project transfer to team/org ownership
+- shared project access grants
+- shared env metadata/value grants
+- shared env rotation
+- audit logging for shared admin actions
+
+### Boundary rule
+
+If the operation changes shared identity, shared membership, shared project access, or shared secret custody, it is broker-mediated.
+
+If the operation only changes device-local runtime state, it is local-only.
+
+## Project Ownership Contract
+
+Projects need explicit ownership metadata, not inference from git remotes, provider accounts, or current user.
+
+Required project fields:
+
+- `ownership.mode`: `local` | `shared`
+- `ownership.ownerType`: `user` | `team` | `organization`
+- `ownership.ownerId`
+- `ownership.managedBy`: `local` | `broker`
+
+Semantics:
+
+- `local` implies `managedBy=local`
+- `shared` implies `managedBy=broker`
+- a project cannot be both local and shared
+- access grants are ignored for purely local projects
+
+## Env Sharing Contract
+
+Env sharing must be explicit at both the bundle and grant levels.
+
+Required env policy fields:
+
+- `sharing.mode`: `local_only` | `shared_metadata_only` | `shared_values`
+- `sharing.ownerType`
+- `sharing.ownerId`
+- `sharing.managedBy`
+
+Rules:
+
+- project ownership does not override env policy
+- a shared project may still use local-only env values
+- `shared_values` requires encrypted broker custody and audit events
+- value resolution for remote/shared operations must check env grants separately from project grants
+
+## Lifecycle Coverage
+
+The child work needs to cover the full lifecycle:
+
+### Organization lifecycle
+
+- create
+- invite members
+- promote/demote admins
+- create/archive teams
+- transfer or dissolve shared ownership safely
+
+### Team lifecycle
+
+- create
+- add/remove members
+- grant/revoke admin
+- archive team without orphaning projects or env bundles
+
+### Project lifecycle
+
+- local project creation
+- explicit promotion to shared ownership
+- access grant management
+- transfer between team and org scopes
+- archive/delete behavior for shared projects
+
+### Env lifecycle
+
+- local contract declaration
+- enable sharing
+- grant consumer/admin access
+- rotate or revoke values
+- downgrade back to metadata-only or local-only when allowed
+
+## Audit and Enforcement Direction
+
+Shared admin operations need durable audit events with:
+
+- acting Hack user
+- target resource type and id
+- previous and new role/policy state
+- project/env scope
+- timestamp
+
+Enforcement must happen in two places:
+
+- broker-side authorization for shared operations
+- client-side refusal to pretend a local command can mutate shared state
+
+The CLI should never imply success for a shared admin mutation that the broker did not authorize.
+
+## Child Workstreams
+
+The program should split into the following child issues:
+
+1. Org and team lifecycle primitives
+2. Org/team membership and RBAC enforcement
+3. Project ownership metadata and transfer flow
+4. Project access grants and permission checks
+5. Shared env policy, grants, and encrypted value custody
+6. CLI command/help/docs updates for local vs broker boundaries
+7. Audit events and operator-facing diagnostics
+
+## Proposed Child Tickets
+
+The queue for this program is:
+
+1. `T-00001` Org and Team Lifecycle Primitives
+2. `T-00002` Org/Team Membership and RBAC Enforcement
+3. `T-00003` Project Ownership Metadata and Transfer Flow
+4. `T-00004` Project Access Grants and Permission Checks
+5. `T-00005` Shared Env Policy, Grants, and Encrypted Value Custody
+6. `T-00006` CLI Help and Docs for Local vs Broker Admin Boundaries
+7. `T-00007` Audit Events and Diagnostics for Shared Admin Operations
+
+Recommended dependency order:
+
+- Ticket 2 depends on Ticket 1
+- Ticket 3 depends on Ticket 1
+- Ticket 4 depends on Tickets 2 and 3
+- Ticket 5 depends on Tickets 2 and 3
+- Ticket 6 depends on Tickets 1, 3, 4, and 5
+- Ticket 7 depends on Tickets 2, 4, and 5
+
+Coverage rule:
+
+- Tickets 1 and 2 own lifecycle and authorization primitives
+- Tickets 3 and 4 own project ownership and access semantics
+- Ticket 5 owns env sharing and secret custody semantics
+- Tickets 6 and 7 own the operator-visible trust boundary, help text, and audit trail
+
+## Acceptance Mapping
+
+### Understandable operations without hidden trust assumptions
+
+Covered by:
+- explicit resource model
+- explicit command namespaces
+- explicit local vs broker rule
+
+### Roles and privileges explicit and safe by default
+
+Covered by:
+- minimal role model
+- separate project and env grants
+- no silent sharing or privilege inheritance
+
+### Child issues cover lifecycle, permissions, and admin boundaries
+
+Covered by:
+- lifecycle sections for org/team/project/env
+- seven child workstreams above
+
+## Open Questions
+
+- Whether org-owned projects should be common or reserved for a small set of shared infrastructure projects.
+- Whether shared env value access should support approval workflows later, or remain direct grant-based access for now.
+- Whether the first implementation surface should be CLI-only or should include macOS admin views in the same milestone.
diff --git a/docs/plans/2026-03-14-teams-and-organizations-management-plan.md b/docs/plans/2026-03-14-teams-and-organizations-management-plan.md
new file mode 100644
index 000000000..687375d43
--- /dev/null
+++ b/docs/plans/2026-03-14-teams-and-organizations-management-plan.md
@@ -0,0 +1,299 @@
+# Teams and Organizations Management Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add an explicit, secure-by-default admin model for organizations, teams, shared project ownership, and env sharing without regressing Hack's local-first workflows.
+
+**Architecture:** Keep local runtime/project/env operations local by default, and add broker-mediated ownership, membership, grants, and audit flows only for shared resources. The CLI should expose the trust boundary directly through `auth`, `org`, `team`, `project owner/access`, and shared `env` surfaces.
+
+**Tech Stack:** Bun, TypeScript, Hack CLI, auth-broker, existing env contract system, existing Hack auth session model
+
+---
+
+## Program Split
+
+`HACK-436` is the program-definition issue, not the implementation bucket. The expected output for this issue is:
+
+- a reviewed design for the command and access-control model
+- a dependency-ordered child ticket set covering lifecycle, permissions, ownership, env sharing, and admin boundaries
+- a concrete implementation sequence that downstream tickets can execute without re-deciding trust assumptions
+
+Recommended child ticket order:
+
+1. `T-00001` Org and Team Lifecycle Primitives
+2. `T-00002` Org/Team Membership and RBAC Enforcement
+3. `T-00003` Project Ownership Metadata and Transfer Flow
+4. `T-00004` Project Access Grants and Permission Checks
+5. `T-00005` Shared Env Policy, Grants, and Encrypted Value Custody
+6. `T-00006` CLI Help and Docs for Local vs Broker Admin Boundaries
+7. `T-00007` Audit Events and Diagnostics for Shared Admin Operations
+
+Recommended dependencies:
+
+- Ticket 2 depends on Ticket 1
+- Ticket 3 depends on Ticket 1
+- Ticket 4 depends on Tickets 2 and 3
+- Ticket 5 depends on Tickets 2 and 3
+- Ticket 6 depends on Tickets 1, 3, 4, and 5
+- Ticket 7 depends on Tickets 2, 4, and 5
+
+The task breakdown below is the implementation scaffold those child tickets should follow.
+
+---
+
+### Task 1: Capture the shared admin vocabulary in config and docs
+
+**Files:**
+- Modify: `docs/architecture.md`
+- Modify: `docs/env.md`
+- Modify: `docs/gateway.md` if boundary wording needs tightening
+- Test: documentation review plus focused grep validation
+
+**Step 1: Write the failing documentation checklist**
+- Confirm the docs do not currently define:
+  - local vs shared project ownership
+  - project vs env grant separation
+  - org/team admin boundary
+
+**Step 2: Run the repo search to verify the gap**
+Run:
+```bash
+grep -RInE 'project ownership|env grant|team role|org role|shared env' docs src tests
+```
+Expected: incomplete or missing shared admin contract language.
+
+**Step 3: Add the minimal shared admin vocabulary**
+- define `local` vs `shared` ownership
+- define org/team/project/env role terms
+- define broker-mediated admin boundary
+
+**Step 4: Re-run the search and readback**
+Run:
+```bash
+grep -RInE 'local vs broker|project_owner|env_admin|team_admin|org_owner' docs
+```
+Expected: PASS with the new contract represented in docs.
+
+### Task 2: Add explicit project ownership metadata and read surfaces
+
+**Files:**
+- Modify: `src/lib/project.ts`
+- Modify: `src/lib/project-meta.ts`
+- Modify: `src/commands/project.ts`
+- Test: `tests/project-config.test.ts`
+- Test: `tests/project-views.test.ts`
+
+**Step 1: Write the failing tests**
+- local projects default to `ownership.mode=local`
+- shared project metadata can represent `team` or `organization` ownership
+- CLI/project views surface ownership without inferring from unrelated state
+
+**Step 2: Run focused tests to verify failure**
+Run:
+```bash
+bun test tests/project-config.test.ts tests/project-views.test.ts
+```
+Expected: FAIL because ownership metadata and views are not explicit yet.
+
+**Step 3: Write minimal implementation**
+- add project ownership metadata schema/helpers
+- expose read-only ownership inspection in the CLI
+
+**Step 4: Re-run focused tests**
+Run:
+```bash
+bun test tests/project-config.test.ts tests/project-views.test.ts
+```
+Expected: PASS
+
+### Task 3: Add org and team lifecycle CLI surfaces backed by broker auth
+
+**Files:**
+- Modify: `src/commands/auth.ts`
+- Create: `src/commands/org.ts`
+- Create: `src/commands/team.ts`
+- Modify: `src/cli/spec.ts`
+- Test: `tests/auth-command.test.ts`
+- Test: new focused tests such as `tests/org-command.test.ts` and `tests/team-command.test.ts`
+
+**Step 1: Write the failing tests**
+- unauthenticated `org` and `team` mutations fail with a clear Hack auth requirement
+- list/show surfaces parse and render target scope correctly
+- mutating calls require broker-backed auth context
+
+**Step 2: Run focused tests to verify failure**
+Run:
+```bash
+bun test tests/auth-command.test.ts tests/org-command.test.ts tests/team-command.test.ts
+```
+Expected: FAIL because the new command surfaces do not exist.
+
+**Step 3: Write minimal implementation**
+- add `hack org ...` and `hack team ...` command trees
+- wire auth/session guards
+- keep scope explicit in command output and errors
+
+**Step 4: Re-run focused tests**
+Run:
+```bash
+bun test tests/auth-command.test.ts tests/org-command.test.ts tests/team-command.test.ts
+```
+Expected: PASS
+
+### Task 4: Add project transfer and access-grant flows
+
+**Files:**
+- Modify: `src/commands/project.ts`
+- Modify: project ownership/access helper modules under `src/lib/`
+- Test: `tests/project-up-command.test.ts`
+- Test: new focused project access tests
+
+**Step 1: Write the failing tests**
+- `hack project owner show` returns local or shared ownership explicitly
+- transfer to team/org requires authenticated broker context
+- project access grants are rejected for local-only projects
+
+**Step 2: Run focused tests to verify failure**
+Run:
+```bash
+bun test tests/project-up-command.test.ts tests/project-config.test.ts tests/project-views.test.ts
+```
+Expected: FAIL because ownership transfer and grant behavior is missing.
+
+**Step 3: Write minimal implementation**
+- add `project owner` read/transfer commands
+- add `project access` list/grant/revoke commands
+- fail closed when project mode is local or auth context is missing
+
+**Step 4: Re-run focused tests**
+Run:
+```bash
+bun test tests/project-up-command.test.ts tests/project-config.test.ts tests/project-views.test.ts
+```
+Expected: PASS
+
+### Task 5: Add shared env policy and access controls
+
+**Files:**
+- Modify: `src/commands/env.ts`
+- Modify: `src/lib/env.ts`
+- Modify: `docs/env.md`
+- Test: `tests/env-backend-command.test.ts`
+- Test: add focused env-sharing tests
+
+**Step 1: Write the failing tests**
+- local env operations remain local by default
+- enabling env sharing requires explicit mode selection
+- shared env value access is checked separately from project access
+
+**Step 2: Run focused tests to verify failure**
+Run:
+```bash
+bun test tests/env-backend-command.test.ts
+```
+Expected: FAIL because shared env policy/grants are not implemented.
+
+**Step 3: Write minimal implementation**
+- add env sharing policy representation
+- add `env access` and `env share` subcommands
+- preserve local `env set/unset` semantics
+
+**Step 4: Re-run focused tests**
+Run:
+```bash
+bun test tests/env-backend-command.test.ts
+```
+Expected: PASS
+
+### Task 6: Add broker authorization and audit contracts for shared admin actions
+
+**Files:**
+- Modify: `services/auth-broker/src/...` relevant auth/admin modules
+- Modify: `packages/db/src/schema/...` if shared admin tables/events are needed
+- Test: `services/auth-broker/tests/...`
+- Test: `packages/db` focused schema tests
+
+**Step 1: Write the failing tests**
+- shared admin operations enforce org/team/project/env roles
+- unauthorized callers receive explicit permission failures
+- successful mutations emit durable audit events
+
+**Step 2: Run focused broker tests to verify failure**
+Run:
+```bash
+bun test --cwd services/auth-broker
+bun test --cwd packages/db
+```
+Expected: FAIL in the new authorization/audit scenarios.
+
+**Step 3: Write minimal implementation**
+- add shared admin role checks
+- add audit event recording for shared mutations
+- keep local-only workflows outside this enforcement path
+
+**Step 4: Re-run focused broker tests**
+Run:
+```bash
+bun test --cwd services/auth-broker
+bun test --cwd packages/db
+```
+Expected: PASS
+
+### Task 7: Tighten CLI help, docs, and diagnostics around the trust boundary
+
+**Files:**
+- Modify: `docs/cli.md`
+- Modify: `src/cli/help.ts`
+- Modify: `src/commands/help.ts`
+- Test: `tests/cli-command.test.ts`
+
+**Step 1: Write the failing test**
+- help output names the local-only versus broker-mediated distinction where the new commands appear
+
+**Step 2: Run focused tests to verify failure**
+Run:
+```bash
+bun test tests/cli-command.test.ts
+```
+Expected: FAIL because help text does not yet describe the boundary clearly.
+
+**Step 3: Write minimal implementation**
+- update help text for new admin surfaces
+- add boundary-oriented examples and failure guidance
+
+**Step 4: Re-run focused tests**
+Run:
+```bash
+bun test tests/cli-command.test.ts
+```
+Expected: PASS
+
+### Task 8: Final verification
+
+**Files:**
+- Verify only
+
+**Step 1: Run focused tests for touched areas**
+Run:
+```bash
+bun test tests/auth-command.test.ts tests/project-config.test.ts tests/project-views.test.ts tests/project-up-command.test.ts tests/env-backend-command.test.ts tests/cli-command.test.ts
+```
+Expected: PASS
+
+**Step 2: Run repo verification gates**
+Run:
+```bash
+bun run build
+bun run typecheck
+bun run test
+bun run check
+```
+Expected: PASS
+
+**Step 3: Run ticket and runtime checks**
+Run:
+```bash
+bun run index.ts tickets list
+bun run index.ts doctor
+```
+Expected: PASS, or explicit blocker output if ticket remote/auth setup is unavailable in the environment.

From 565f1b27d4a5fb5597951359ade9522e59bb71a7 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:10:34 +0000
Subject: [PATCH 017/134] docs: add linear project artifact design

---
 ...6-03-14-linear-project-artifacts-design.md | 293 ++++++++++++
 ...026-03-14-linear-project-artifacts-plan.md | 434 ++++++++++++++++++
 2 files changed, 727 insertions(+)
 create mode 100644 docs/plans/2026-03-14-linear-project-artifacts-design.md
 create mode 100644 docs/plans/2026-03-14-linear-project-artifacts-plan.md

diff --git a/docs/plans/2026-03-14-linear-project-artifacts-design.md b/docs/plans/2026-03-14-linear-project-artifacts-design.md
new file mode 100644
index 000000000..42dee4eff
--- /dev/null
+++ b/docs/plans/2026-03-14-linear-project-artifacts-design.md
@@ -0,0 +1,293 @@
+# Linear Project Artifacts Design
+
+## Goal
+Add a Hack-managed model for Linear project documents, milestones, and status updates so project planning can live in the repo with explicit pull, plan, and apply flows instead of staying manual in Linear.
+
+## Existing State
+- Hack already supports Linear auth profiles, project binding, issue sync, webhook deliveries, and autosync subscriptions.
+- The current Linear CLI surface is centered on account setup, issue/project sync, and delivery review.
+- There is no repo-managed representation for Linear project documents, milestones, or status updates.
+- This project still creates those planning artifacts directly in Linear, which breaks the "Hack manages project state" story.
+
+## Requirements
+- Documents, milestones, and status updates must be manageable as repo artifacts.
+- The CLI shape must fit the existing `hack linear` surface instead of introducing a separate product.
+- The model must stay manual-first for outbound writes: no background mutation of Linear project planning data.
+- The design must be specific enough to drive CLI and client implementation work.
+
+## Approaches Considered
+
+### 1. Direct pass-through commands only
+Examples:
+- `hack linear documents create --title ... --body-stdin`
+- `hack linear milestones update --id ...`
+- `hack linear status-updates create --stdin`
+
+Pros:
+- Smallest implementation surface.
+- No new local file model.
+
+Cons:
+- Not actually Hack-managed state.
+- No diffable planning artifacts in git.
+- Hard to review or batch changes.
+- Poor fit for long-form project docs.
+
+### 2. Config-only project artifact metadata
+Examples:
+- Store documents/milestones/status updates inside `hack.config.json` or extension config blobs.
+
+Pros:
+- Reuses existing config write paths.
+- Easy to resolve target profile/project defaults.
+
+Cons:
+- Bad fit for Markdown bodies and multi-document projects.
+- Encourages giant config blobs.
+- Awkward review experience.
+- Weak separation between routing config and content artifacts.
+
+### 3. Repo-managed artifact files with explicit pull/plan/apply commands
+Examples:
+- Local Markdown/frontmatter artifacts under `.hack/linear/projects/<project-id>/...`
+- `hack linear documents list|pull|plan|apply`
+- `hack linear milestones list|pull|plan|apply`
+- `hack linear status-updates list|pull|publish`
+
+Pros:
+- Git-visible planning artifacts.
+- Works for long-form docs.
+- Matches Hack’s “managed local state with explicit sync” model.
+- Supports safe previews before mutating Linear.
+
+Cons:
+- Requires new file parsing and reconciliation code.
+- Needs a clear local artifact contract.
+
+## Recommendation
+Adopt approach 3.
+
+Documents, milestones, and status updates should become repo-managed artifacts with explicit lifecycle commands. Routing stays in `hack.config.json`, but artifact content lives in dedicated files under `.hack/linear/projects/<project-id>/`. This keeps the current project-binding model intact while adding a planning surface that can be reviewed, committed, synced, and reapplied from the repo.
+
+## Artifact Model
+
+### Repository layout
+Use one canonical directory per bound Linear project:
+
+```text
+.hack/linear/projects/<project-id>/
+  documents/
+    <slug>.md
+  milestones/
+    <slug>.md
+  status-updates/
+    drafts/
+      <yyyy-mm-dd>-<slug>.md
+    published/
+      <yyyy-mm-dd>-<slug>.md
+```
+
+Rules:
+- `<project-id>` is the stable key, not project name, so project renames do not churn paths.
+- All artifact files are user-editable source-of-truth files, not generated state.
+- Remote IDs are persisted in frontmatter after first pull or apply so future updates remain idempotent.
+- Routing defaults continue to come from `controlPlane.routing.overrides.linear.*`.
+
+### Shared file contract
+Every artifact file uses Markdown with YAML frontmatter.
+
+Required frontmatter fields:
+- `kind`
+- `linearProjectId`
+- `title`
+
+Optional common fields:
+- `linearProfile`
+- `linearProjectName`
+- `linearId`
+- `slug`
+- `archived`
+- `updatedAt`
+
+The Markdown body is the artifact content. Milestones can use the body for notes/context even if Linear only exposes structured milestone fields.
+
+### Document files
+Path:
+- `.hack/linear/projects/<project-id>/documents/<slug>.md`
+
+Frontmatter:
+- `kind: linear-project-document`
+- `title`
+- `linearId`
+- `slug`
+- `sortOrder`
+- `icon`
+- `archived`
+
+Behavior:
+- Multiple documents per project are supported.
+- Removing a local file does not delete the remote document implicitly.
+- Remote archive/delete requires an explicit command or `--prune`.
+
+### Milestone files
+Path:
+- `.hack/linear/projects/<project-id>/milestones/<slug>.md`
+
+Frontmatter:
+- `kind: linear-project-milestone`
+- `title`
+- `linearId`
+- `slug`
+- `targetDate`
+- `sortOrder`
+- `state`
+- `archived`
+
+Behavior:
+- Milestones are treated as upsertable structured artifacts.
+- The body is optional notes/context, kept locally even if not all fields round-trip to Linear.
+
+### Status update files
+Draft path:
+- `.hack/linear/projects/<project-id>/status-updates/drafts/<yyyy-mm-dd>-<slug>.md`
+
+Published path:
+- `.hack/linear/projects/<project-id>/status-updates/published/<yyyy-mm-dd>-<slug>.md`
+
+Frontmatter:
+- `kind: linear-project-status-update`
+- `title`
+- `linearId`
+- `slug`
+- `health`
+- `date`
+- `linkedMilestoneIds`
+
+Behavior:
+- Status updates are append-only snapshots, not mutable upserts.
+- `publish` creates a new remote update from a draft file.
+- After publish, Hack updates the file with the remote ID and moves it into `published/`.
+- Pulling status updates imports remote history into `published/`; it does not recreate drafts.
+
+## CLI Shape
+
+### Command families
+Add three new `hack linear` command families:
+- `hack linear documents <verb>`
+- `hack linear milestones <verb>`
+- `hack linear status-updates <verb>`
+
+This is the cleanest fit with the existing top-level `hack linear` namespace:
+- existing nouns already group related workflows (`projects`, `subscriptions`, `deliveries`)
+- documents/milestones/status-updates are recognizable Linear concepts
+- each family can parse its own verbs without exploding the extension command count
+
+### Standard verbs
+Documents:
+- `list`
+- `pull`
+- `plan`
+- `apply`
+- `archive`
+
+Milestones:
+- `list`
+- `pull`
+- `plan`
+- `apply`
+- `archive`
+
+Status updates:
+- `list`
+- `pull`
+- `plan`
+- `publish`
+
+Reasoning:
+- `plan` is the non-mutating diff/preflight verb across all families.
+- `apply` is correct for upsertable artifacts.
+- `publish` is clearer than `apply` for append-only status updates.
+
+### Shared targeting flags
+All three families should accept the same routing flags:
+- `--profile <id>`
+- `--project-id <linear-project-id>`
+- `--project-name <name>`
+- `--team-id <linear-team-id>`
+- `--path <artifact-file-or-dir>`
+- `--json`
+
+Resolution order:
+1. explicit CLI flags
+2. current project’s bound Linear routing
+3. selected/default Linear profile
+
+### UX rules
+1. No remote writes on plain `list` or `pull`.
+2. `plan` is required for safe review and should show create/update/archive counts before `apply` or `publish`.
+3. `apply` and `publish` must be explicit; no autosync for planning artifacts in this slice.
+4. Missing project binding should fail with the same pattern as existing project-bound commands and suggest `hack linear project-bind`.
+5. `--json` output must be stable and structured so desktop/MCP clients can adopt the same surface later.
+6. Human output should prefer table or kv layouts consistent with current Linear commands.
+7. Removing a file locally must not archive/delete remote state unless the user passes an explicit destructive flag.
+8. Remote IDs and last-sync metadata should be written back only after successful remote mutation.
+
+## Sync Semantics
+
+### Pull
+- Fetch remote artifacts for the selected project.
+- Create local files when missing.
+- Update frontmatter/body for files that are already Hack-managed.
+- Never overwrite untracked local drafts without `--force`.
+
+### Plan
+- Compare local files and remote artifacts.
+- Categorize results as `create`, `update`, `archive`, `noop`, `conflict`.
+- Exit non-zero only for hard resolution failures, not for pending work.
+
+### Apply
+- Documents and milestones: upsert remote artifacts from local files.
+- Status updates: only publish draft files that have no remote ID yet, unless a future `republish` mode is added.
+
+### Conflict rules
+- Same remote ID mapped from multiple local files is a hard error.
+- Same local slug mapping to different remote IDs is a hard error.
+- Local file missing remote ID but matching remote slug/title is review-needed, not silent overwrite.
+- Status updates with an existing remote ID are treated as immutable unless an explicit repair command is added later.
+
+## Data Boundary
+- Repo-managed:
+  - artifact files under `.hack/linear/projects/<project-id>/...`
+  - remote IDs in frontmatter
+  - local draft/published distinction for status updates
+- Broker-managed:
+  - OAuth connections
+  - webhook deliveries
+  - autosync subscriptions
+  - assignee mappings
+
+Project planning artifacts belong in the repo because they are collaborative project state, not secret integration state.
+
+## MCP / Desktop Implications
+- MCP should eventually expose the same noun/verb families instead of inventing separate project-planning tools.
+- Desktop can build on the same structured `--json` responses for listing, planning, and publishing.
+- The CLI remains the source of truth for artifact mutation rules.
+
+## Non-Goals
+- No background autosync for project documents, milestones, or status updates.
+- No implicit remote deletion from file removal.
+- No migration of issue sync or ticket storage.
+- No replacement of existing `project-bind`, `sync-project`, or delivery workflows.
+
+## Rollout
+1. Add Linear client support for project documents, milestones, and status updates.
+2. Add local artifact parsing/materialization for the `.hack/linear/projects/<project-id>/` tree.
+3. Add the three CLI command families with `list/pull/plan/apply|publish`.
+4. Expose structured JSON outputs for MCP/desktop reuse.
+5. Add destructive/archive flows only after the base upsert/publish path is stable.
+
+## Risks
+- Linear’s GraphQL shape for project documents/status updates may not line up cleanly with the local Markdown contract and may need lossy field selection.
+- File/path churn can become noisy if slug and title normalization are unstable.
+- Status updates are more timeline-like than documents; over-generalizing them as editable artifacts would cause accidental rewrites.
+- If `plan` output is weak, users will not trust `apply` for project planning state.
diff --git a/docs/plans/2026-03-14-linear-project-artifacts-plan.md b/docs/plans/2026-03-14-linear-project-artifacts-plan.md
new file mode 100644
index 000000000..68d8b7c8f
--- /dev/null
+++ b/docs/plans/2026-03-14-linear-project-artifacts-plan.md
@@ -0,0 +1,434 @@
+# Linear Project Artifacts Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add Hack-managed Linear project documents, milestones, and status updates with repo-backed artifacts and explicit CLI pull/plan/apply workflows.
+
+**Architecture:** Extend the existing Linear extension in three layers: GraphQL client support for project artifact operations, a repo-backed artifact file model under `.hack/linear/projects/<project-id>/`, and three new CLI noun families (`documents`, `milestones`, `status-updates`) that share routing and diff semantics. Keep the feature manual-first: outbound writes happen only through explicit `apply` or `publish` commands.
+
+**Tech Stack:** Bun, TypeScript, existing Linear extension/client code, Bun test, Markdown + YAML frontmatter parsing, current display helpers.
+
+---
+
+### Task 1: Add failing Linear client tests for project artifact queries and mutations
+
+**Files:**
+- Modify: `tests/linear-client.test.ts`
+- Modify: `src/control-plane/extensions/linear/client.ts`
+
+**Step 1: Write the failing tests**
+
+Add focused tests for:
+- listing project documents
+- creating/updating a project document
+- listing project milestones
+- creating/updating a milestone
+- listing project status updates
+- creating a status update
+
+Model them after the existing issue/project tests so they assert:
+- GraphQL operation names
+- key variables
+- parsed response shape
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/linear-client.test.ts
+```
+
+Expected: FAIL because the client does not expose these project artifact methods yet.
+
+**Step 3: Write minimal implementation**
+
+Extend `src/control-plane/extensions/linear/client.ts` with:
+- new types for project document, milestone, and status update payloads
+- request helpers for list/create/update operations
+- parsing helpers that normalize the GraphQL payload into small stable TS types
+
+Do not add CLI logic in this task.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/linear-client.test.ts
+```
+
+Expected: PASS for the new client coverage.
+
+**Step 5: Commit**
+
+```bash
+git add tests/linear-client.test.ts src/control-plane/extensions/linear/client.ts
+git commit -m "feat: add linear project artifact client support"
+```
+
+### Task 2: Add failing tests for local artifact file parsing and materialization
+
+**Files:**
+- Create: `tests/linear-project-artifacts.test.ts`
+- Create: `src/control-plane/extensions/linear/project-artifacts.ts`
+
+**Step 1: Write the failing tests**
+
+Cover:
+- parsing Markdown + YAML frontmatter for documents
+- parsing milestones with structured fields
+- parsing status update drafts
+- resolving project artifact root from bound project id
+- detecting duplicate remote IDs or duplicate local slugs
+- planning create/update/noop sets from local + remote inputs
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/linear-project-artifacts.test.ts
+```
+
+Expected: FAIL because the artifact parser/planner module does not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Create `src/control-plane/extensions/linear/project-artifacts.ts` with:
+- TS types for local artifact records
+- frontmatter parsing/serialization helpers
+- repo path resolution helpers
+- reconciliation helpers for `pull` and `plan`
+
+Keep remote API calls out of this module.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/linear-project-artifacts.test.ts
+```
+
+Expected: PASS for parser/planner coverage.
+
+**Step 5: Commit**
+
+```bash
+git add tests/linear-project-artifacts.test.ts src/control-plane/extensions/linear/project-artifacts.ts
+git commit -m "feat: add linear project artifact file model"
+```
+
+### Task 3: Add failing command-parser tests for the new Linear noun families
+
+**Files:**
+- Modify: `tests/linear-commands.test.ts`
+- Modify: `src/control-plane/extensions/linear/commands.ts`
+
+**Step 1: Write the failing tests**
+
+Add parser tests for:
+- `documents list|pull|plan|apply`
+- `milestones list|pull|plan|apply`
+- `status-updates list|pull|plan|publish`
+
+Assert:
+- verb parsing
+- shared routing flags
+- path handling
+- `--json`
+- invalid verbs error clearly
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/linear-commands.test.ts
+```
+
+Expected: FAIL because the new parser helpers and command registrations are missing.
+
+**Step 3: Write minimal implementation**
+
+In `src/control-plane/extensions/linear/commands.ts`:
+- register new commands named `documents`, `milestones`, and `status-updates`
+- add shared parser helpers for verb-driven command families
+- wire handlers to existing profile/project binding resolution
+
+Keep handlers thin; they should delegate planning/file logic to `project-artifacts.ts`.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/linear-commands.test.ts
+```
+
+Expected: PASS for parser coverage without full remote mutation behavior yet.
+
+**Step 5: Commit**
+
+```bash
+git add tests/linear-commands.test.ts src/control-plane/extensions/linear/commands.ts
+git commit -m "feat: add linear project artifact command families"
+```
+
+### Task 4: Implement `list` and `pull` end to end
+
+**Files:**
+- Modify: `src/control-plane/extensions/linear/commands.ts`
+- Modify: `src/control-plane/extensions/linear/project-artifacts.ts`
+- Modify: `tests/linear-commands.test.ts`
+- Modify: `tests/linear-client.test.ts`
+- Modify: `tests/mcp.test.ts`
+
+**Step 1: Write the failing tests**
+
+Add command-level tests for:
+- listing remote documents/milestones/status updates
+- pulling them into the repo artifact tree
+- preserving remote IDs in frontmatter
+- honoring project binding defaults
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/linear-commands.test.ts tests/mcp.test.ts
+```
+
+Expected: FAIL because handlers do not yet perform end-to-end listing or file writes.
+
+**Step 3: Write minimal implementation**
+
+Implement:
+- remote fetch via the new client methods
+- local file writes through the artifact helpers
+- stable `--json` payloads for machine consumers
+- MCP registrations for any new CLI command IDs exposed through the existing bridge
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/linear-commands.test.ts tests/mcp.test.ts
+```
+
+Expected: PASS for `list` and `pull`.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/linear/commands.ts src/control-plane/extensions/linear/project-artifacts.ts tests/linear-commands.test.ts tests/linear-client.test.ts tests/mcp.test.ts
+git commit -m "feat: pull linear project artifacts into repo state"
+```
+
+### Task 5: Implement `plan`
+
+**Files:**
+- Modify: `src/control-plane/extensions/linear/project-artifacts.ts`
+- Modify: `src/control-plane/extensions/linear/commands.ts`
+- Modify: `tests/linear-project-artifacts.test.ts`
+- Modify: `tests/linear-commands.test.ts`
+
+**Step 1: Write the failing tests**
+
+Add plan tests for:
+- local create vs remote missing
+- local update vs remote drift
+- remote-only artifacts reported without mutation
+- duplicate mapping errors
+- immutable published status update handling
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/linear-project-artifacts.test.ts tests/linear-commands.test.ts
+```
+
+Expected: FAIL because the planner does not yet compute a complete action set.
+
+**Step 3: Write minimal implementation**
+
+Implement a planner that returns:
+- `creates`
+- `updates`
+- `archives`
+- `noops`
+- `conflicts`
+
+Render human output with existing `display.table` / `display.kv` helpers and structured JSON for machine use.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/linear-project-artifacts.test.ts tests/linear-commands.test.ts
+```
+
+Expected: PASS for non-mutating plan behavior.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/linear/project-artifacts.ts src/control-plane/extensions/linear/commands.ts tests/linear-project-artifacts.test.ts tests/linear-commands.test.ts
+git commit -m "feat: plan linear project artifact changes"
+```
+
+### Task 6: Implement document/milestone `apply` and status update `publish`
+
+**Files:**
+- Modify: `src/control-plane/extensions/linear/client.ts`
+- Modify: `src/control-plane/extensions/linear/project-artifacts.ts`
+- Modify: `src/control-plane/extensions/linear/commands.ts`
+- Modify: `tests/linear-client.test.ts`
+- Modify: `tests/linear-commands.test.ts`
+- Modify: `tests/linear-project-artifacts.test.ts`
+
+**Step 1: Write the failing tests**
+
+Cover:
+- applying a new document writes back `linearId`
+- applying an updated milestone preserves file path/slug
+- publishing a draft status update moves it to `published/`
+- already-published status updates are rejected unless explicit repair mode exists
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/linear-client.test.ts tests/linear-commands.test.ts tests/linear-project-artifacts.test.ts
+```
+
+Expected: FAIL because mutation handlers and post-success file rewrites are incomplete.
+
+**Step 3: Write minimal implementation**
+
+Implement:
+- document create/update
+- milestone create/update
+- status update publish
+- safe local file rewrites only after confirmed remote success
+
+Do not add delete/prune in this task.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/linear-client.test.ts tests/linear-commands.test.ts tests/linear-project-artifacts.test.ts
+```
+
+Expected: PASS for explicit apply/publish flows.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/linear/client.ts src/control-plane/extensions/linear/project-artifacts.ts src/control-plane/extensions/linear/commands.ts tests/linear-client.test.ts tests/linear-commands.test.ts tests/linear-project-artifacts.test.ts
+git commit -m "feat: apply managed linear project artifacts"
+```
+
+### Task 7: Update command help and docs after behavior is live
+
+**Files:**
+- Modify: `src/commands/linear.ts`
+- Modify: `src/control-plane/extensions/linear/extension.ts`
+- Modify: `docs/cli.md`
+- Modify: `docs/extensions.md`
+- Modify: `docs/guides/linear-integration-architecture.md`
+
+**Step 1: Write the failing test**
+
+Add or extend a CLI/help test that asserts `hack linear` help includes the new command families once implemented.
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/linear-command-alias.test.ts
+```
+
+Expected: FAIL because help/docs do not mention the new project artifact commands yet.
+
+**Step 3: Write minimal implementation**
+
+Update summaries and examples so Linear is described as:
+- account connection
+- ticket sync
+- project planning artifacts
+
+Cross-link the architecture guide and extension docs to the repo-backed artifact model.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/linear-command-alias.test.ts
+```
+
+Expected: PASS for help coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/commands/linear.ts src/control-plane/extensions/linear/extension.ts docs/cli.md docs/extensions.md docs/guides/linear-integration-architecture.md tests/linear-command-alias.test.ts
+git commit -m "docs: document linear project artifact workflows"
+```
+
+### Task 8: Run final quality gates
+
+**Files:**
+- Modify: none
+
+**Step 1: Run focused tests**
+
+Run:
+
+```bash
+bun test tests/linear-client.test.ts tests/linear-commands.test.ts tests/linear-project-artifacts.test.ts tests/linear-command-alias.test.ts tests/mcp.test.ts
+```
+
+Expected: PASS
+
+**Step 2: Run lint/format gates**
+
+Run:
+
+```bash
+bun x ultracite check
+```
+
+Expected: PASS with no remaining issues.
+
+**Step 3: Run any required autofixes if needed**
+
+Run:
+
+```bash
+bun x ultracite fix
+```
+
+Then rerun:
+
+```bash
+bun x ultracite check
+```
+
+**Step 4: Commit final polish**
+
+```bash
+git add .
+git commit -m "chore: finish linear project artifact support"
+```

From 23f2dd8c14a923e2ac4d5d75784af0a61ab4e048 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:10:38 +0000
Subject: [PATCH 018/134] docs: cross-link planned linear project artifacts

---
 docs/extensions.md                             |  2 ++
 docs/guides/linear-integration-architecture.md | 18 ++++++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/docs/extensions.md b/docs/extensions.md
index b4c8b0a81..543df7263 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -323,6 +323,8 @@ Notes:
   - `dependencies` (default `true`)
   - `projects` (default `true`)
 - Architecture + rollout guide: `docs/guides/linear-integration-architecture.md`.
+- Planned managed project artifacts (documents, milestones, status updates):
+  `docs/plans/2026-03-14-linear-project-artifacts-design.md`.
 
 #### job-show
 
diff --git a/docs/guides/linear-integration-architecture.md b/docs/guides/linear-integration-architecture.md
index 02f3db9bd..f89266bfe 100644
--- a/docs/guides/linear-integration-architecture.md
+++ b/docs/guides/linear-integration-architecture.md
@@ -69,3 +69,21 @@ This guarantees filtering by local-only, Linear-only, or mixed sets without ambi
 1. Phase 1 (current): manual sync only, explicit one-off operations.
 2. Phase 2: webhook-driven candidate updates (still gated/manual apply).
 3. Phase 3: selective autosync per project/profile with conflict policies.
+4. Phase 4 (planned): repo-managed project documents, milestones, and status updates.
+
+## Planned Project Artifact Layer
+
+The next Linear planning slice should extend the existing project binding model with repo-managed
+project artifacts:
+
+- documents
+- milestones
+- status updates
+
+These artifacts should not live in `hack.config.json` blobs or direct one-shot CLI flags. They
+should live in a dedicated repo tree under `.hack/linear/projects/<project-id>/` and use explicit
+`pull`, `plan`, and `apply`/`publish` workflows.
+
+Detailed design:
+- `docs/plans/2026-03-14-linear-project-artifacts-design.md`
+- `docs/plans/2026-03-14-linear-project-artifacts-plan.md`

From 43474189f4c1795ad03475ce59e7ed32c930e532 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:16:04 +0000
Subject: [PATCH 019/134] docs: survey agent-native runtime baselines

---
 docs/README.md                                |   4 +
 docs/agent-native-runtime-landscape.md        | 589 ++++++++++++++++++
 ...nt-native-runtime-provider-capabilities.md | 124 ++++
 3 files changed, 717 insertions(+)
 create mode 100644 docs/agent-native-runtime-landscape.md
 create mode 100644 docs/agent-native-runtime-provider-capabilities.md

diff --git a/docs/README.md b/docs/README.md
index e493be242..085e4269d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -6,6 +6,8 @@ This directory contains the public documentation for hack. Specs remain in `SPEC
 
 - [CLI reference](cli.md)
 - [Architecture](architecture.md)
+- [Agent-native runtime landscape](agent-native-runtime-landscape.md)
+- [Agent-native runtime provider capabilities](agent-native-runtime-provider-capabilities.md)
 - [Sessions](sessions.md) - mux session management (tmux or zellij) + API
 - [Env & secrets](env.md) - env contract + `.hack/.env` + OS keychain secrets
 - [Lifecycle](lifecycle.md) - project startup hooks + managed host processes
@@ -16,10 +18,12 @@ This directory contains the public documentation for hack. Specs remain in `SPEC
 - [Control-plane SDK](sdk.md)
 
 Monorepo note:
+
 - Root scripts orchestrate workspace tasks through Turbo.
 - Package-local commands remain available via `bun run --cwd <workspace> <script>`.
 
 Quick diagnostics:
+
 - `hack usage` (resource usage across running projects)
 - `hack usage --watch` (live resource trends)
 - `hack node routes status` (controller-side remote route bridge state)
diff --git a/docs/agent-native-runtime-landscape.md b/docs/agent-native-runtime-landscape.md
new file mode 100644
index 000000000..3976f2e25
--- /dev/null
+++ b/docs/agent-native-runtime-landscape.md
@@ -0,0 +1,589 @@
+# Agent-Native Runtime Landscape
+
+Updated: March 13, 2026
+
+This document surveys the runtimes and adjacent systems that are most relevant to Hack's next runtime baseline. It is intentionally decision-oriented: the goal is not to catalog everything in the market, but to extract the architecture and control-plane patterns that should shape Hack's future runtime work.
+
+This analysis uses the current Hack implementation as the local baseline, especially [architecture.md](architecture.md) and [gateway.md](gateway.md). Primary claims below were validated against official project documentation on March 13, 2026. The referenced Linear Zig runtime spec URL was reachable but did not expose readable content from this workspace during authoring, so any "future runtime" implications below are inferred from the issue scope plus the current repo architecture.
+
+For the concrete backend contract derived from this survey, see [agent-native-runtime-provider-capabilities.md](agent-native-runtime-provider-capabilities.md).
+
+## Executive Summary
+
+### Emulate
+
+- Keep a simple app model like Compose: a small project graph, explicit services, explicit optional profiles, and a human-editable source of truth.
+- Treat recovery as a first-class design area, not an afterthought. Nomad's separation between local restart and scheduler-level reschedule is the right conceptual model for Hack.
+- Keep the control plane optional and least-privilege by default. Podman and Hack already point in the right direction: local sockets first, remote access only through deliberate exposure.
+- Preserve stable service identity across local and remote environments. Dev Containers and DevPod show the value of a portable environment contract even when the underlying runtime changes.
+- Make inactivity handling and resume semantics explicit. DevPod's stop/resume model is more aligned with agent workflows than "everything runs forever."
+- Model resources and dependencies explicitly. Tilt's resource graph is a better mental model for agent-driven orchestration than raw "bring everything up."
+
+### Avoid
+
+- Do not make Hack's baseline depend on a heavyweight cluster scheduler, CRD ecosystem, or Kubernetes object model.
+- Do not tie the control plane to an always-on network listener. Local sockets plus opt-in remote gateways are safer.
+- Do not rely on engine-specific health or restart heuristics as the sole source of truth. They are useful inputs, not the whole runtime state model.
+- Do not make the runtime spec synonymous with dev environment configuration. Dev Containers are a good interchange layer, but they are not a sufficient runtime architecture by themselves.
+
+### Defer
+
+- Full cluster scheduling, placement optimization, and multi-node failover.
+- VM-backed isolation as the baseline local path.
+- Rich live-reload/build-loop features like Tilt's `live_update`; these are useful higher-level accelerators, not the core runtime substrate.
+- A containerd-native baseline unless Hack is ready to own more low-level networking, image, and lifecycle wiring.
+
+## Evaluation Dimensions
+
+The systems below were compared against the dimensions Hack actually cares about:
+
+- Architecture and composition model
+- Isolation and security boundaries
+- Networking and service identity
+- Recovery and restart behavior
+- Control-plane and API shape
+- Portability across local, remote, and agent-driven workflows
+
+## At-A-Glance Comparison
+
+| System | Primary Value | Best Pattern To Borrow | Main Risk For Hack |
+| --- | --- | --- | --- |
+| Docker Engine + Compose | Ubiquitous local baseline | Simple service graph, profiles, health-gated startup | Weak control-plane semantics and engine coupling |
+| Podman | Rootless, daemon-light container runtime | Socket-activated API, rootless bias, Kubernetes YAML bridge | Linux-centric operational edges and compatibility drift |
+| containerd + nerdctl + CNI | Embedded runtime substrate | Clear layering and namespace support | Higher integration burden for networking and UX |
+| Dev Containers spec | Portable environment contract | Reusable workspace definition, lifecycle hooks, prebuilds | Config spec is not a runtime/control plane |
+| DevPod | Provider abstraction over devcontainers | Provider model, stop/resume, SSH-first workspace access | Workspace-centric model can be heavier than project-local orchestration |
+| Colima + Lima | Practical macOS substrate adapter | Explicit VM/network/mount capabilities over Docker or containerd | VM indirection changes networking and filesystem assumptions |
+| Tilt | Explicit resource graph for inner-loop dev | Dependency graph, selective enablement, readiness-driven orchestration | High complexity and implicit build-loop behavior |
+| Nomad | Clear runtime and scheduler semantics | Restart vs reschedule split, pluggable drivers | Scheduler scope is broader than Hack's baseline need |
+
+## Survey
+
+### 1. Docker Engine + Compose
+
+Relevant sources:
+
+- [Compose profiles](https://docs.docker.com/compose/how-tos/profiles/)
+- [Compose startup order and health checks](https://docs.docker.com/compose/how-tos/startup-order/)
+- [Restart policies](https://docs.docker.com/engine/containers/start-containers-automatically/)
+- [Live restore](https://docs.docker.com/engine/daemon/live-restore/)
+- [Storage driver notes](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/)
+
+Architecture:
+
+- Compose remains the simplest widely adopted model for describing a local multi-service app.
+- Profiles are a practical mechanism for optional resources without introducing a separate scheduler.
+- The model is declarative enough for humans, but the real control plane still lives in the Docker engine and CLI.
+
+Isolation:
+
+- Isolation is container-first and engine-managed.
+- On Linux, storage defaults still center on OverlayFS-style copy-on-write layers, and newer Docker installs now use the containerd image store by default.
+- Isolation is good enough for local app services, but not a strong agent boundary on its own.
+
+Networking:
+
+- Compose gives stable service naming within a project network, but Hack already had to add Caddy, CoreDNS, and `extra_hosts` repair logic to get durable host/container identity across developer workflows.
+- Compose health-aware dependency ordering is useful, but it is still startup coordination, not a full dependency or recovery graph.
+
+Recovery:
+
+- Docker restart policies and live restore are valuable primitives.
+- They are still daemon-centric. They help containers survive daemon restarts or restart after exits, but they do not provide a richer runtime state machine for agent tooling.
+
+Control plane:
+
+- The Docker API is widely supported, but it is an engine API rather than an app-centric project control plane.
+- Hack's current `hackd` layer already exists because raw engine data is not enough for Hack's UX.
+
+Implications for Hack:
+
+- Emulate Compose's small, explicit project model and profiles.
+- Keep Compose compatibility or importability for the near term.
+- Avoid making Docker engine state the sole source of truth for project/runtime state.
+- Defer any attempt to compete with Docker as a general-purpose container engine.
+
+### 2. Podman
+
+Relevant sources:
+
+- [Podman system service](https://docs.podman.io/en/latest/markdown/podman-system-service.1.html)
+- [Podman network create](https://docs.podman.io/en/latest/markdown/podman-network-create.1.html)
+- [Podman kube play](https://docs.podman.io/en/latest/markdown/podman-kube-play.1.html)
+- [Podman systemd units / Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)
+
+Architecture:
+
+- Podman is attractive because it reduces the "always-running daemon" assumption and leans into system tooling such as systemd socket activation and generated service units.
+- Its API service is optional and can be activated on demand, which matches Hack's "optional daemon/control plane" philosophy better than Docker's default posture.
+
+Isolation:
+
+- Podman has strong rootless and user namespace stories, which matter if Hack wants a safer local agent substrate.
+- The platform still has meaningful Linux-first behavior differences, especially around networking and host access.
+
+Networking:
+
+- Podman exposes network choices more explicitly. Internal bridge networks, network-scoped DNS, and route settings are first-class.
+- Rootless networking has real constraints. That is a benefit for security clarity, but it also makes "just make the host visible everywhere" less reliable than many Docker users assume.
+
+Recovery:
+
+- Systemd integration is the headline pattern here. Socket activation and generated units create a crisp relationship between desired state and host process supervision.
+- `kube play --replace` is also a good example of an idempotent reconcile operation on top of a local runtime.
+
+Control plane:
+
+- Podman's API docs are unusually direct about security: local socket access is the security model, and remote TCP exposure should be avoided unless mutually authenticated.
+- That advice maps almost exactly to how Hack should treat its own remote control surface.
+
+Implications for Hack:
+
+- Emulate the optional API/socket-activation pattern.
+- Emulate the bias toward local socket control and explicit remote exposure.
+- Borrow the idea that "reconcile from declarative input" can be a first-class local runtime operation.
+- Avoid a Linux-only baseline if Hack still needs broad macOS-first developer ergonomics.
+
+### 3. containerd + nerdctl + CNI
+
+Relevant sources:
+
+- [containerd README](https://github.com/containerd/containerd)
+- [nerdctl README](https://github.com/containerd/nerdctl)
+- [CNI overview](https://www.cni.dev/)
+- [CNI plugin overview](https://www.cni.dev/plugins/current/main/)
+
+Architecture:
+
+- containerd is explicit about its intended role: it is designed to be embedded into a larger system.
+- That makes it architecturally relevant to Hack's long-term direction. A future Hack runtime could reasonably sit on top of containerd rather than on top of Docker CLI behaviors.
+- nerdctl demonstrates that a Docker-like UX can be rebuilt over containerd, including Compose-style workflows.
+
+Isolation:
+
+- containerd gives a cleaner layering boundary between runtime, image store, snapshotters, and higher-level tooling.
+- The cost is that Hack would own more assembly work: image build integration, rootless setup, network plugins, and cross-platform packaging become Hack responsibilities.
+
+Networking:
+
+- nerdctl depends on CNI plugins for container networking.
+- CNI's strength is narrow scope: it focuses on network connectivity and cleanup, with plugins for bridge, `ptp`, `macvlan`, `ipvlan`, and others.
+- That narrowness is good for composition but means Hack would need a stronger opinionated layer above CNI if it wants stable developer-facing service identity, ingress, and route repair.
+
+Recovery:
+
+- containerd is strong at lifecycle primitives, but it does not hand you a product-level project control plane.
+- Namespace support in nerdctl is particularly relevant. It offers a clean separation tool that is more explicit than many Docker-based local stacks.
+
+Control plane:
+
+- This stack is a toolkit, not a finished local-dev product.
+- That is both the opportunity and the risk: it aligns with Hack's possible future, but it raises the bar on owning more runtime UX and reliability directly.
+
+Implications for Hack:
+
+- Emulate the layering discipline: runtime substrate below, Hack project control plane above.
+- Consider containerd as a future substrate if Hack wants less Docker coupling and more runtime ownership.
+- Defer a containerd-native baseline until Hack is ready to own networking, rootless ergonomics, and cross-platform integration as product features rather than incidental plumbing.
+
+### 4. Dev Containers Specification
+
+Relevant sources:
+
+- [Development Containers overview](https://containers.dev/)
+- [devcontainers/spec](https://github.com/devcontainers/spec)
+- [Using images, Dockerfiles, and Docker Compose](https://containers.dev/guide/dockerfile)
+- [Prebuilds](https://containers.dev/guide/prebuild)
+- [Supporting tools and services](https://containers.dev/supporting.html)
+
+Architecture:
+
+- Dev Containers solve a different problem than Hack's runtime, but they solve an adjacent one extremely well: portable workspace definition.
+- The key design win is separation between environment contract and the underlying executor. A `devcontainer.json` can target local or cloud-backed experiences through multiple tools.
+
+Isolation:
+
+- Isolation is intentionally inherited from the underlying container platform.
+- The spec provides lifecycle hooks, Features, and mounting/config semantics, but it does not define a richer runtime supervisor or scheduling model.
+
+Networking:
+
+- The spec can reuse Docker Compose and define forwarded ports, but networking behavior varies across supporting tools.
+- That portability gap is important: the spec is useful as a contract, but Hack should not assume every field maps cleanly across all runtime backends.
+
+Recovery:
+
+- Dev Containers are oriented around create/recreate/reopen flows rather than scheduler-style recovery semantics.
+- Prebuilds are a useful performance pattern, but not a runtime control pattern.
+
+Control plane:
+
+- The spec is intentionally not a unified remote control plane.
+- It is a configuration and interoperability layer.
+
+Implications for Hack:
+
+- Emulate the idea of a portable workspace/project contract that can survive backend changes.
+- Consider import/export or compatibility with `devcontainer.json` for agent workspaces.
+- Avoid conflating "dev environment config" with "agent-native runtime design."
+
+### 5. DevPod
+
+Relevant sources:
+
+- [What is DevPod?](https://devpod.sh/docs/what-is-devpod)
+- [What are Workspaces?](https://devpod.sh/docs/developing-in-workspaces/what-are-workspaces)
+- [What are Providers?](https://devpod.sh/docs/managing-providers/what-are-providers)
+- [Create a Workspace](https://devpod.sh/docs/developing-in-workspaces/create-a-workspace)
+- [Auto-inactivity timeout](https://devpod.sh/docs/developing-in-workspaces/inactivity-timeout)
+
+Architecture:
+
+- DevPod is a strong example of separating workspace UX from backend execution through a provider model.
+- It reuses `devcontainer.json`, then layers provider-specific machine or container execution behind a common CLI/UI.
+- This is highly relevant to Hack's local-vs-remote node ambitions.
+
+Isolation:
+
+- DevPod's isolation story depends on the provider.
+- The important pattern is not "best isolation," but "stable user experience across multiple isolation substrates."
+
+Networking:
+
+- DevPod's SSH-first access pattern is notable. The workspace becomes addressable through a stable SSH target rather than a custom always-open HTTP control plane.
+- That is a useful model for agent attachment, especially when paired with explicit gateway exposure only when needed.
+
+Recovery:
+
+- Stop/resume/recreate/reset are explicit user-facing lifecycle states.
+- Automatic inactivity shutdown is especially relevant for agent-native workflows where unused environments should pause rather than accumulate indefinitely.
+
+Control plane:
+
+- Providers are CLI-defined and extensible. That is the cleanest adjacent example of a backend abstraction that still feels product-level rather than purely infrastructural.
+- The client-only posture is also instructive: many workflows do not need a large always-on central service.
+
+Implications for Hack:
+
+- Emulate the provider/driver abstraction.
+- Emulate explicit pause/resume and inactivity semantics.
+- Consider SSH or socket-first attach flows as a default agent transport.
+- Avoid copying the full "workspace product" scope into Hack's runtime baseline if Hack's main need is project and service orchestration.
+
+### 6. Colima + Lima
+
+Relevant sources:
+
+- [Colima README](https://github.com/abiosoft/colima)
+- [Lima VM types](https://lima-vm.io/docs/config/vmtype/)
+- [Lima network](https://lima-vm.io/docs/config/network/)
+- [Lima VMNet networks](https://lima-vm.io/docs/config/network/vmnet/)
+- [Lima filesystem mounts](https://lima-vm.io/docs/config/mount/)
+
+Architecture:
+
+- Colima is not a runtime in the same sense as Docker Engine or containerd. It is a practical local adapter that gives macOS users a Linux VM plus a chosen container runtime.
+- Lima is the more important architectural reference for Hack. It makes the hidden VM layer explicit by exposing VM type, mount type, port forwarding, and network mode as top-level configuration.
+- This matters because Hack is macOS-heavy today. Any future runtime baseline that ignores VM-backed local execution will mis-model real-world behavior for a large part of Hack's user base.
+
+Isolation:
+
+- The real isolation boundary is often the guest VM first and the container runtime second.
+- That can be a feature: it is a clearer substrate boundary than pretending macOS containers are "just Linux containers on the host."
+- But it also means filesystem behavior depends on mount strategy such as `virtiofs`, `9p`, or SSH-backed sharing. Host/container parity is not guaranteed.
+
+Networking:
+
+- Lima's docs are unusually useful because they make network mode tradeoffs explicit: user-mode networking, `vzNAT`, `socket_vmnet`, additional guest IPs, and port-forwarding behavior are all separate choices.
+- Colima's automatic port forwarding is convenient, but it can hide the fact that host-to-container reachability on macOS is VM-mediated rather than native bridge behavior.
+- For Hack, this validates a key design point: service identity, ingress, and route repair must be Hack-owned semantics, not assumptions inherited from a specific local runtime stack.
+
+Recovery:
+
+- Recovery is mostly substrate restart at the VM/runtime layer rather than app-aware project recovery.
+- When the VM restarts or reconfigures, host reachability, forwarded ports, and mounted filesystem behavior can all drift even if the container runtime conceptually "came back."
+- That pattern is directly relevant to Hack's stale-runtime and route-repair logic.
+
+Control plane:
+
+- Colima and Lima expose machine/runtime controls, not project-level app semantics.
+- That makes them strong adjacent references but weak candidates for Hack's actual control plane model.
+- They should be treated as environment adapters that Hack can observe and accommodate, not as the shape of the Hack runtime itself.
+
+Implications for Hack:
+
+- Emulate explicit capability reporting for host OS, VM layer, network mode, and mount behavior.
+- Emulate the honesty of treating macOS local backends as VM-backed substrates with different guarantees than native Linux.
+- Avoid assuming Docker-compatible CLI behavior implies Docker-compatible networking or filesystem semantics.
+- Defer any deep Lima/Colima-specific integration unless Hack decides it wants to optimize for macOS substrate introspection directly.
+
+### 7. Tilt
+
+Relevant sources:
+
+- [Tilt overview](https://docs.tilt.dev/)
+- [Resource dependencies](https://docs.tilt.dev/resource_dependencies.html)
+- [Live Update reference](https://docs.tilt.dev/live_update_reference.html)
+- [Tiltfile API](https://docs.tilt.dev/api.html)
+- [Disable resources](https://docs.tilt.dev/disable_resources.html)
+
+Architecture:
+
+- Tilt is best understood as a resource graph controller for development workflows.
+- It manages local commands, Docker Compose resources, Kubernetes resources, and custom logic under one graph.
+- That graph-centric model is closer to how agents reason than raw Compose is.
+
+Isolation:
+
+- Tilt delegates isolation to the underlying targets.
+- Its value is orchestration, readiness tracking, and update behavior, not runtime sandboxing.
+
+Networking:
+
+- Tilt can work across Compose and Kubernetes, but it is not primarily a networking system.
+- The important pattern is that it treats resources and their readiness as first-class, rather than just issuing a one-shot `up` command.
+
+Recovery:
+
+- Tilt's `resource_deps` and readiness semantics are useful, but they are optimized for inner-loop iteration.
+- A notable caveat: for Docker Compose resources, Tilt does not currently observe Compose health checks for readiness. That is exactly the sort of backend mismatch Hack should avoid depending on blindly.
+
+Control plane:
+
+- Tilt shows the value of a rich local control plane with selective enable/disable, parallelism settings, and a graph model.
+- Its `live_update` system is powerful, but it is not a baseline runtime primitive. It is an optimization layer.
+
+Implications for Hack:
+
+- Emulate explicit resource graphs, readiness, and selective activation.
+- Emulate the idea that a control plane should reason about dependencies, not just shell out to runtime commands.
+- Defer advanced build/live-update ergonomics until the core runtime state model is solid.
+
+### 8. Nomad
+
+Relevant sources:
+
+- [Job specification](https://developer.hashicorp.com/nomad/docs/job-specification)
+- [Restart block](https://developer.hashicorp.com/nomad/docs/job-specification/restart)
+- [Reschedule block](https://developer.hashicorp.com/nomad/docs/job-specification/reschedule)
+- [Network block](https://developer.hashicorp.com/nomad/docs/job-specification/network)
+- [Task driver plugins](https://developer.hashicorp.com/nomad/plugins/drivers)
+
+Architecture:
+
+- Nomad is broader than Hack's current scope, but it contains some of the clearest control-plane semantics in this survey.
+- Jobs, groups, and tasks make placement and co-location explicit without dragging in Kubernetes' full object model.
+
+Isolation:
+
+- Nomad's task driver model is important conceptually. Execution is pluggable, and isolation quality is a property of the driver rather than hidden behind a fake universal abstraction.
+- That honesty is useful for Hack if it wants multiple backend types in the future.
+
+Networking:
+
+- Nomad's group-level network model is strong: network mode and allocated ports are part of the job spec, and CNI integration is explicit rather than implied.
+- Shared network namespaces within groups map well to "service plus sidecars/helpers" patterns.
+
+Recovery:
+
+- Nomad's clean split between restart and reschedule is probably the single most important recovery pattern in this survey.
+- Restart is local and client-side. Reschedule is scheduler-side and can move work elsewhere.
+- That distinction gives operators and tooling much clearer mental models than many local runtimes expose.
+
+Control plane:
+
+- Nomad is a real scheduler, which is more than Hack needs today.
+- But its jobspec and lifecycle semantics are an excellent source of concepts for a lighter-weight Hack control plane.
+
+Implications for Hack:
+
+- Emulate the restart/reschedule distinction directly.
+- Emulate pluggable execution drivers or providers, with honest capability reporting.
+- Defer full scheduling and cluster placement logic.
+
+## Cross-Cutting Takeaways For Hack
+
+### 1. Hack should keep a small declarative app model
+
+Compose still wins on approachability. Hack should preserve a simple service graph with optional profiles and human-editable config, even if the underlying runtime eventually stops being Docker-centric.
+
+### 2. The runtime substrate and the Hack control plane should stay separate
+
+containerd and Nomad both reinforce the same lesson from different directions:
+
+- the runtime substrate should own primitive execution and isolation
+- Hack should own project semantics, readiness, recovery policy, networking policy, and agent-facing APIs
+
+That is already implicit in today's `hackd` and gateway architecture. The future runtime should make it more explicit, not less.
+
+### 3. Recovery needs at least two layers
+
+Hack should adopt terminology and behavior closer to:
+
+- `restart`: retry or recreate inside the same local execution context
+- `reschedule` or `recreate elsewhere`: move to a different node, backend, or substrate when local recovery is not enough
+
+Without this split, local and remote runtime behavior will stay ambiguous for agents and operators.
+
+### 4. Networking should be treated as a product subsystem
+
+Hack's current Caddy/CoreDNS/route-repair work already shows the gap between engine networking and developer-facing networking.
+
+The baseline runtime should therefore define:
+
+- stable service identity
+- ingress policy
+- host/container name resolution policy
+- repair behavior when local routing state changes
+- backend capability differences, rather than pretending they do not exist
+
+### 5. The control plane should remain socket-first and opt-in for remote exposure
+
+Podman is the clearest external validation of this posture. The safest default is:
+
+- local Unix socket or equivalent local transport
+- no remote writes unless explicitly enabled
+- remote exposure through SSH/Tailscale/Cloudflare-style operator actions, not ambient open TCP listeners
+
+That also fits agent workflows better, because it makes capability and trust boundaries explicit.
+
+### 6. Provider or driver abstraction is worth keeping
+
+DevPod, Colima/Lima, and Nomad converge on a similar idea from different angles:
+
+- a top-level product can keep a stable UX
+- execution backends still need honest capability boundaries
+
+Hack should keep moving toward explicit provider/driver capability reporting for local Docker-like backends, remote node runtimes, and future alternative substrates.
+
+### 7. macOS support means Hack must model VM-backed local execution explicitly
+
+Colima and Lima make a reality explicit that many local tools gloss over: on macOS, the "local container runtime" is often a Linux VM plus forwarding, mounts, and compatibility layers.
+
+For Hack, that means the backend capability contract should expose at least:
+
+- whether execution is native-host or VM-mediated
+- how host/container networking is implemented
+- how filesystem mounts are bridged
+- which assumptions survive VM restart or reconfiguration
+
+### 8. Hack should import workspace standards, not become one
+
+`devcontainer.json` compatibility is attractive for agent workspaces and remote onboarding, but it should sit above the runtime, not define it.
+
+The right likely direction is:
+
+- Hack runtime defines execution, networking, recovery, and control-plane semantics
+- Hack can ingest or generate higher-level workspace/environment definitions when useful
+
+## Mapping To Current Hack Architecture
+
+The current repo already contains several pieces of the eventual runtime boundary. The practical question is which ones should remain compatibility layers and which ones should become core runtime abstractions.
+
+### 1. Compose should become a backend, not the architecture
+
+Current baseline:
+
+- [architecture.md](architecture.md) treats `.hack/docker-compose.yml` as the project runtime source of truth today.
+- [cli.md](cli.md) still defines core runtime flows in terms of `docker compose up`, `down`, `ps`, `logs`, and `run`.
+
+Implication:
+
+- The next runtime should preserve Compose import/export and migration value.
+- But Hack's architecture should define its own project graph, dependency semantics, health model, and recovery policy above whichever backend executes the workload.
+
+### 2. `hackd` is already the beginning of the real control plane
+
+Current baseline:
+
+- [architecture.md](architecture.md) already separates `hackd` from the underlying container runtime.
+- The daemon caches state, fingerprints runtime resets, and reports stale runtime metadata when the engine changes or disappears.
+
+Implication:
+
+- This is the right direction and should be extended into a first-class runtime state machine.
+- The future runtime spec should define project states, service states, readiness, stale cache, reset detection, and recovery transitions in Hack terms instead of inheriting them implicitly from Docker status strings.
+
+### 3. Networking is already a Hack-owned subsystem
+
+Current baseline:
+
+- [architecture.md](architecture.md) documents the current Caddy, CoreDNS, TLS cert, and `extra_hosts` repair stack.
+- Hack already treats stable service naming and local ingress as product responsibilities rather than leaving them to Compose defaults.
+
+Implication:
+
+- The future runtime should formalize networking as a runtime subsystem with explicit capabilities and repair semantics.
+- That includes service identity, host/container resolution behavior, ingress policy, and what happens when route or IP assumptions drift under the runtime.
+
+### 4. The gateway posture is directionally correct
+
+Current baseline:
+
+- [gateway.md](gateway.md) already keeps remote access optional, local by default, and gated by explicit write enablement.
+
+Implication:
+
+- The control plane should stay socket-first and local-first.
+- Remote access should remain a deliberate operator action layered on top, not a default runtime posture.
+
+### 5. Remote nodes expose the current substrate coupling
+
+Current baseline:
+
+- [guides/remote-node-container.md](guides/remote-node-container.md) shows that today's remote node runtime still bundles the `hack` CLI and shells out through Docker plus the Docker socket.
+
+Implication:
+
+- That is acceptable as a compatibility and bootstrap layer.
+- It also highlights exactly where Hack is still substrate-coupled: remote nodes currently package Hack's control plane and Docker integration together rather than separating "Hack runtime semantics" from "Docker-backed execution."
+
+### 6. Capability reporting should become explicit
+
+Current baseline:
+
+- The gateway and node docs already distinguish capabilities such as runtime, gateway, and supervisor.
+
+Implication:
+
+- The next runtime should make capability reporting richer and backend-aware.
+- At minimum, Hack should report which backends support restart semantics, pause/resume, health probes, ingress, remote shells, snapshots, and route repair rather than assuming every backend behaves like Docker on the local host.
+
+## Recommended Baseline Requirements For The Next Hack Runtime
+
+Based on this survey, a credible baseline should include:
+
+1. A small declarative project model with services, profiles, mounts, env, and explicit dependencies.
+2. First-class runtime state with health, readiness, stale-cache, and reset detection semantics.
+3. Distinct restart and reschedule behaviors, with room for local and remote backends.
+4. Stable service identity and explicit networking policy across host and container contexts.
+5. Optional local control plane with socket-first access and explicit remote exposure.
+6. Capability-aware provider/driver abstraction for backend differences.
+7. Backend capability reporting that can distinguish native Linux execution from VM-mediated local backends on macOS.
+8. Explicit pause/resume or inactivity behavior for agent-managed environments.
+9. Compatibility paths for Compose and likely future workspace-contract import, but no hard dependency on either as the long-term architecture.
+
+## Questions The Runtime Spec Should Answer Explicitly
+
+The survey narrows the next spec work to a small set of architecture questions:
+
+1. What is Hack's canonical project and service model once Compose is treated as an adapter rather than the source of truth?
+2. Which lifecycle states are Hack-defined, and which are merely backend observations?
+3. What is the exact difference between restart, recreate, reschedule, and resume in local and remote contexts?
+4. Which networking guarantees are required across all supported backends, and which are best-effort capabilities?
+5. What is the minimum backend capability contract for a "Hack runtime provider"?
+6. How should Hack model VM-mediated local backends on macOS versus native Linux backends?
+7. Which pieces of agent workspace setup belong in the runtime versus in higher-level workspace contracts such as devcontainers?
+
+## Suggested Near-Term Architecture Direction
+
+If Hack wants the most credible near-term baseline, the best path is:
+
+- Keep the current Compose-backed model as the compatibility and migration layer.
+- Strengthen Hack-owned runtime state, recovery semantics, and networking policy in `hackd` and the gateway.
+- Introduce clearer provider/driver capability reporting for local and remote runtimes.
+- Use [agent-native-runtime-provider-capabilities.md](agent-native-runtime-provider-capabilities.md) as the starting contract for backend capability modeling.
+- Design the future runtime boundary so Docker/Compose can be one backend, not the definition of Hack itself.
+- Delay a containerd-native substrate until Hack explicitly wants to own more low-level runtime assembly.
+
+That path preserves today's leverage while still moving toward an agent-native architecture.
diff --git a/docs/agent-native-runtime-provider-capabilities.md b/docs/agent-native-runtime-provider-capabilities.md
new file mode 100644
index 000000000..31441ed5d
--- /dev/null
+++ b/docs/agent-native-runtime-provider-capabilities.md
@@ -0,0 +1,124 @@
+# Agent-Native Runtime Provider Capabilities
+
+Updated: March 13, 2026
+
+This document turns the runtime landscape survey into a concrete capability contract for Hack runtime providers. It is meant to be used alongside [agent-native-runtime-landscape.md](agent-native-runtime-landscape.md), not instead of it.
+
+## Purpose
+
+Hack needs a provider contract that is honest about backend differences while still keeping one stable project and control-plane model for agents and operators.
+
+This document answers three practical questions:
+
+- Which backend capabilities are required for a credible Hack runtime baseline?
+- Which capabilities are optional or backend-specific?
+- Which areas should remain compatibility layers or be deferred?
+
+## Capability Terms
+
+- `Required`: every Hack runtime provider must support this directly or through a Hack-owned adapter.
+- `Optional`: useful capability that should be reported explicitly when present.
+- `Deferred`: not part of the baseline provider contract.
+- `Adapter-owned`: Hack can provide the behavior above the backend rather than requiring native support.
+
+## Baseline Provider Matrix
+
+Provider classes used below:
+
+- `Local Docker-like (Linux)`: Docker Engine + Compose on a native Linux host.
+- `Local Docker-like (macOS VM)`: Docker Desktop, Colima, Lima-backed Docker-like environments.
+- `Local Podman rootless`: rootless Podman-style local execution.
+- `Remote Docker-backed node`: current Hack remote node model with Docker socket access.
+- `Future containerd provider`: a more native Hack-owned runtime substrate.
+
+| Capability | Contract Level | Local Docker-like (Linux) | Local Docker-like (macOS VM) | Local Podman rootless | Remote Docker-backed node | Future containerd provider |
+| --- | --- | --- | --- | --- | --- | --- |
+| Start/stop/recreate services | Required | Native | Native | Native | Native | Native |
+| Project-scoped service graph | Required | Adapter-owned | Adapter-owned | Adapter-owned | Adapter-owned | Adapter-owned or native |
+| Readiness/health observation | Required | Native + adapter normalization | Native + adapter normalization | Native + adapter normalization | Native + adapter normalization | Native + adapter normalization |
+| Restart in same execution context | Required | Native | Native | Native | Native | Native |
+| Reschedule to another backend/node | Required at Hack layer | Hack-owned | Hack-owned | Hack-owned | Hack-owned | Hack-owned |
+| Stable service identity | Required | Adapter-owned | Adapter-owned | Adapter-owned | Adapter-owned | Adapter-owned or native |
+| Host/container name resolution policy | Required | Adapter-owned | Adapter-owned | Adapter-owned | Adapter-owned | Adapter-owned |
+| Ingress policy for developer-facing hosts | Required | Adapter-owned | Adapter-owned | Adapter-owned | Adapter-owned | Adapter-owned |
+| Route repair after substrate drift | Required | Adapter-owned | Adapter-owned and critical | Adapter-owned | Adapter-owned and critical | Adapter-owned |
+| Socket-first local control surface | Required | Native | Native | Native | Native on node | Native |
+| Explicit remote exposure gating | Required | Hack-owned | Hack-owned | Hack-owned | Hack-owned | Hack-owned |
+| Capability reporting | Required | Hack-owned | Hack-owned and critical | Hack-owned | Hack-owned | Hack-owned |
+| Native pause/resume | Optional | Limited | VM-level and backend-specific | Backend-specific | Backend-specific | Plausible future native support |
+| Snapshot/export checkpoints | Optional | Limited | Limited | Limited | Limited | Plausible future native support |
+| Honest mount semantics reporting | Required | Hack-owned | Hack-owned and critical | Hack-owned | Hack-owned | Hack-owned |
+| Workspace-contract import (`devcontainer.json`) | Optional | Adapter-owned | Adapter-owned | Adapter-owned | Adapter-owned | Adapter-owned |
+| Scheduler placement optimization | Deferred | No | No | No | No | No |
+| Live-update/build-sync acceleration | Deferred | No | No | No | No | No |
+
+## Minimum Provider Contract
+
+Every Hack runtime provider should expose, at minimum, the following contract to `hackd` and the gateway:
+
+### 1. Execution primitives
+
+- Create, start, stop, restart, and recreate a project-scoped unit of execution.
+- Enumerate service instances with stable provider IDs.
+- Stream stdout/stderr and exit transitions.
+
+### 2. State observation
+
+- Report whether a service is `running`, `stopped`, `failed`, or `unknown`.
+- Report whether health/readiness is native, emulated, or unavailable.
+- Report substrate resets or loss of connectivity so Hack can mark cached state stale.
+
+### 3. Networking description
+
+- Declare whether the backend is native-host or VM-mediated.
+- Describe whether service-to-service DNS is native or Hack-managed.
+- Describe whether host ingress depends on port forwarding, bridge networking, or a Hack-owned proxy.
+
+### 4. Filesystem and mount description
+
+- Report whether mounts are native, VM-bridged, or otherwise translated.
+- Report whether hot-reload-sensitive mount behavior should be treated as degraded or best-effort.
+
+### 5. Control-plane posture
+
+- Provide a local transport suitable for socket-first control.
+- Never assume ambient remote write access.
+- Require explicit opt-in for remote execution paths.
+
+## Provider Capability Schema
+
+The runtime provider contract should report capability flags in Hack terms rather than leaking raw backend assumptions. A provider record should be able to answer at least:
+
+| Field | Meaning |
+| --- | --- |
+| `execution_kind` | `container`, `vm_container`, `process`, or other future substrate |
+| `host_os` | host operating system class |
+| `network_mode` | native bridge, rootless bridge, VM port-forwarded, or equivalent |
+| `mount_mode` | native, VM-bridged, networked, or unknown |
+| `supports_restart` | can retry/recreate in the same execution context |
+| `supports_reschedule` | can participate in Hack-driven relocation to another provider/node |
+| `supports_health_probes` | native, adapter-emulated, or unavailable |
+| `supports_pause_resume` | whether pause/resume semantics exist and at what layer |
+| `supports_snapshots` | whether checkpoint/export exists |
+| `supports_remote_shells` | whether Hack can expose PTY-backed shells safely |
+| `supports_route_repair_hooks` | whether backend emits enough data for route or IP drift repair |
+| `control_transport` | unix socket, named pipe, SSH, HTTP-over-localhost, or similar |
+
+## Adopt, Keep, Defer
+
+| Decision | Items |
+| --- | --- |
+| Adopt now | Socket-first control plane, restart vs reschedule split, Hack-owned networking semantics, backend capability reporting, explicit VM-mediated macOS classification |
+| Keep as compatibility layers | Compose project import/export, Docker-backed remote nodes, `devcontainer.json` compatibility, current gateway/gateway-token model |
+| Defer | Cluster scheduling, placement optimization, CRD-style control objects, live-update acceleration, containerd-native baseline ownership until Hack wants deeper substrate control |
+
+## Decision Summary
+
+The immediate architectural consequence is straightforward:
+
+- Hack should define one project model and one control-plane model.
+- Runtime providers should advertise honest capabilities instead of pretending every backend behaves like local Docker on Linux.
+- Networking, stale-state handling, and remote-write posture should remain Hack-owned semantics.
+- Compose should remain an adapter path, not the definition of the runtime.
+
+That gives the runtime spec a clear next move: define Hack-native lifecycle and capability terms first, then map current Docker/Compose and remote-node behavior into that contract.

From 2b20d89c508396465ead18b6fa7ac4c012d40559 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:16:56 +0000
Subject: [PATCH 020/134] test(global): add explicit command test timeouts

---
 tests/global-command.test.ts | 294 +++++++++++++++++++----------------
 1 file changed, 156 insertions(+), 138 deletions(-)

diff --git a/tests/global-command.test.ts b/tests/global-command.test.ts
index 2d727fb2a..d617f2748 100644
--- a/tests/global-command.test.ts
+++ b/tests/global-command.test.ts
@@ -109,111 +109,173 @@ async function writeStaticCaddyCompose(path: string): Promise<void> {
   );
 }
 
-test("global up runs docker compose up for caddy and logging", async () => {
-  const caddyCompose = join(
-    tempDir!,
-    GLOBAL_HACK_DIR_NAME,
-    GLOBAL_CADDY_DIR_NAME,
-    GLOBAL_CADDY_COMPOSE_FILENAME
-  );
-  const loggingCompose = join(
-    tempDir!,
-    GLOBAL_HACK_DIR_NAME,
-    GLOBAL_LOGGING_DIR_NAME,
-    GLOBAL_LOGGING_COMPOSE_FILENAME
-  );
-  await writeComposeFile(caddyCompose);
-  await writeComposeFile(loggingCompose);
+test(
+  "global up runs docker compose up for caddy and logging",
+  async () => {
+    const caddyCompose = join(
+      tempDir!,
+      GLOBAL_HACK_DIR_NAME,
+      GLOBAL_CADDY_DIR_NAME,
+      GLOBAL_CADDY_COMPOSE_FILENAME
+    );
+    const loggingCompose = join(
+      tempDir!,
+      GLOBAL_HACK_DIR_NAME,
+      GLOBAL_LOGGING_DIR_NAME,
+      GLOBAL_LOGGING_COMPOSE_FILENAME
+    );
+    await writeComposeFile(caddyCompose);
+    await writeComposeFile(loggingCompose);
 
-  const { runCli } = await import("../src/cli/run.ts");
-  const code = await runCli(["global", "up"]);
-  expect(code).toBe(0);
-  expect(
-    runCalls.some((call) => call.includes("daemon") && call.includes("start"))
-  ).toBe(true);
-  expect(
-    runCalls.some((call) => call.includes(caddyCompose) && call.includes("up"))
-  ).toBe(true);
-  expect(
-    runCalls.some(
-      (call) => call.includes(loggingCompose) && call.includes("up")
-    )
-  ).toBe(true);
-});
+    const { runCli } = await import("../src/cli/run.ts");
+    const code = await runCli(["global", "up"]);
+    expect(code).toBe(0);
+    expect(
+      runCalls.some((call) => call.includes("daemon") && call.includes("start"))
+    ).toBe(true);
+    expect(
+      runCalls.some(
+        (call) => call.includes(caddyCompose) && call.includes("up")
+      )
+    ).toBe(true);
+    expect(
+      runCalls.some(
+        (call) => call.includes(loggingCompose) && call.includes("up")
+      )
+    ).toBe(true);
+  },
+  { timeout: 20_000 }
+);
 
-test("global up reassigns containers when reserved ingress IPs are occupied", async () => {
-  const caddyCompose = join(
-    tempDir!,
-    GLOBAL_HACK_DIR_NAME,
-    GLOBAL_CADDY_DIR_NAME,
-    GLOBAL_CADDY_COMPOSE_FILENAME
-  );
-  const loggingCompose = join(
-    tempDir!,
-    GLOBAL_HACK_DIR_NAME,
-    GLOBAL_LOGGING_DIR_NAME,
-    GLOBAL_LOGGING_COMPOSE_FILENAME
-  );
-  await writeStaticCaddyCompose(caddyCompose);
-  await writeComposeFile(loggingCompose);
+test(
+  "global up reassigns containers when reserved ingress IPs are occupied",
+  async () => {
+    const caddyCompose = join(
+      tempDir!,
+      GLOBAL_HACK_DIR_NAME,
+      GLOBAL_CADDY_DIR_NAME,
+      GLOBAL_CADDY_COMPOSE_FILENAME
+    );
+    const loggingCompose = join(
+      tempDir!,
+      GLOBAL_HACK_DIR_NAME,
+      GLOBAL_LOGGING_DIR_NAME,
+      GLOBAL_LOGGING_COMPOSE_FILENAME
+    );
+    await writeStaticCaddyCompose(caddyCompose);
+    await writeComposeFile(loggingCompose);
 
-  let inspectCallCount = 0;
-  execMockResponder = (cmd) => {
-    if (
-      cmd[0] === "docker" &&
-      cmd[1] === "network" &&
-      cmd[2] === "inspect" &&
-      cmd[3] === DEFAULT_INGRESS_NETWORK
-    ) {
-      inspectCallCount += 1;
-      if (inspectCallCount === 1) {
-        return {
-          exitCode: 0,
-          stdout: JSON.stringify([
-            {
-              Containers: {
-                abc123: {
-                  Name: "omega-temporal-server-1",
-                  IPv4Address: `${DEFAULT_CADDY_IP}/16`,
+    let inspectCallCount = 0;
+    execMockResponder = (cmd) => {
+      if (
+        cmd[0] === "docker" &&
+        cmd[1] === "network" &&
+        cmd[2] === "inspect" &&
+        cmd[3] === DEFAULT_INGRESS_NETWORK
+      ) {
+        inspectCallCount += 1;
+        if (inspectCallCount === 1) {
+          return {
+            exitCode: 0,
+            stdout: JSON.stringify([
+              {
+                Containers: {
+                  abc123: {
+                    Name: "omega-temporal-server-1",
+                    IPv4Address: `${DEFAULT_CADDY_IP}/16`,
+                  },
                 },
               },
-            },
-          ]),
+            ]),
+            stderr: "",
+          };
+        }
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify([{ Containers: {} }]),
           stderr: "",
         };
       }
-      return {
-        exitCode: 0,
-        stdout: JSON.stringify([{ Containers: {} }]),
-        stderr: "",
-      };
-    }
 
-    return null;
-  };
+      return null;
+    };
 
-  const { runCli } = await import("../src/cli/run.ts");
-  const code = await runCli(["global", "up"]);
-  expect(code).toBe(0);
+    const { runCli } = await import("../src/cli/run.ts");
+    const code = await runCli(["global", "up"]);
+    expect(code).toBe(0);
 
-  expect(
-    execCalls.some(
-      (call) =>
-        call.join(" ") ===
-        `docker network disconnect -f ${DEFAULT_INGRESS_NETWORK} omega-temporal-server-1`
-    )
-  ).toBe(true);
-  expect(
-    execCalls.some(
-      (call) =>
-        call.join(" ") ===
-        `docker network connect ${DEFAULT_INGRESS_NETWORK} omega-temporal-server-1`
-    )
-  ).toBe(true);
-  expect(
-    runCalls.some((call) => call.includes(caddyCompose) && call.includes("up"))
-  ).toBe(true);
-});
+    expect(
+      execCalls.some(
+        (call) =>
+          call.join(" ") ===
+          `docker network disconnect -f ${DEFAULT_INGRESS_NETWORK} omega-temporal-server-1`
+      )
+    ).toBe(true);
+    expect(
+      execCalls.some(
+        (call) =>
+          call.join(" ") ===
+          `docker network connect ${DEFAULT_INGRESS_NETWORK} omega-temporal-server-1`
+      )
+    ).toBe(true);
+    expect(
+      runCalls.some(
+        (call) => call.includes(caddyCompose) && call.includes("up")
+      )
+    ).toBe(true);
+  },
+  { timeout: 20_000 }
+);
+
+test(
+  "global install writes compose files and starts stacks",
+  async () => {
+    const gumPath = join(tempDir!, GLOBAL_HACK_DIR_NAME, "bin", "gum");
+    const mutagenPath = join(tempDir!, GLOBAL_HACK_DIR_NAME, "bin", "mutagen");
+    await writeExecutable(gumPath);
+    await writeExecutable(mutagenPath);
+    const { runCli } = await import("../src/cli/run.ts");
+    const code = await runCli(["global", "install"]);
+    expect(code).toBe(0);
+
+    const caddyCompose = join(
+      tempDir!,
+      GLOBAL_HACK_DIR_NAME,
+      GLOBAL_CADDY_DIR_NAME,
+      GLOBAL_CADDY_COMPOSE_FILENAME
+    );
+    const loggingCompose = join(
+      tempDir!,
+      GLOBAL_HACK_DIR_NAME,
+      GLOBAL_LOGGING_DIR_NAME,
+      GLOBAL_LOGGING_COMPOSE_FILENAME
+    );
+    const hasCaddy = await Bun.file(caddyCompose).exists();
+    const hasLogging = await Bun.file(loggingCompose).exists();
+    const managedEnvSchema = join(
+      tempDir!,
+      GLOBAL_HACK_DIR_NAME,
+      GLOBAL_SCHEMAS_DIR_NAME,
+      GLOBAL_MANAGED_ENV_SCHEMA_FILENAME
+    );
+    const hasManagedEnvSchema = await Bun.file(managedEnvSchema).exists();
+
+    expect(hasCaddy).toBe(true);
+    expect(hasLogging).toBe(true);
+    expect(hasManagedEnvSchema).toBe(true);
+    expect(
+      runCalls.some(
+        (call) => call.includes(caddyCompose) && call.includes("up")
+      )
+    ).toBe(true);
+    expect(
+      runCalls.some(
+        (call) => call.includes(loggingCompose) && call.includes("up")
+      )
+    ).toBe(true);
+  },
+  { timeout: 20_000 }
+);
 
 test("global down runs docker compose down when files exist", async () => {
   const caddyCompose = join(
@@ -252,50 +314,6 @@ test("global up fails when compose files are missing", async () => {
   expect(code).toBe(1);
 });
 
-test("global install writes compose files and starts stacks", async () => {
-  const gumPath = join(tempDir!, GLOBAL_HACK_DIR_NAME, "bin", "gum");
-  const mutagenPath = join(tempDir!, GLOBAL_HACK_DIR_NAME, "bin", "mutagen");
-  await writeExecutable(gumPath);
-  await writeExecutable(mutagenPath);
-  const { runCli } = await import("../src/cli/run.ts");
-  const code = await runCli(["global", "install"]);
-  expect(code).toBe(0);
-
-  const caddyCompose = join(
-    tempDir!,
-    GLOBAL_HACK_DIR_NAME,
-    GLOBAL_CADDY_DIR_NAME,
-    GLOBAL_CADDY_COMPOSE_FILENAME
-  );
-  const loggingCompose = join(
-    tempDir!,
-    GLOBAL_HACK_DIR_NAME,
-    GLOBAL_LOGGING_DIR_NAME,
-    GLOBAL_LOGGING_COMPOSE_FILENAME
-  );
-  const hasCaddy = await Bun.file(caddyCompose).exists();
-  const hasLogging = await Bun.file(loggingCompose).exists();
-  const managedEnvSchema = join(
-    tempDir!,
-    GLOBAL_HACK_DIR_NAME,
-    GLOBAL_SCHEMAS_DIR_NAME,
-    GLOBAL_MANAGED_ENV_SCHEMA_FILENAME
-  );
-  const hasManagedEnvSchema = await Bun.file(managedEnvSchema).exists();
-
-  expect(hasCaddy).toBe(true);
-  expect(hasLogging).toBe(true);
-  expect(hasManagedEnvSchema).toBe(true);
-  expect(
-    runCalls.some((call) => call.includes(caddyCompose) && call.includes("up"))
-  ).toBe(true);
-  expect(
-    runCalls.some(
-      (call) => call.includes(loggingCompose) && call.includes("up")
-    )
-  ).toBe(true);
-});
-
 test("global status --json returns summary payload", async () => {
   const caddyCompose = join(
     tempDir!,

From 8eebcf3bf880c6c9da9c88acc42f72b9fa657531 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:17:16 +0000
Subject: [PATCH 021/134] test: cover local prerequisite handling exclusions

---
 src/cli/prerequisites.ts           | 52 ++++++++++++++++++++++++++++++
 tests/prerequisites-matrix.test.ts | 22 +++++++++++++
 2 files changed, 74 insertions(+)

diff --git a/src/cli/prerequisites.ts b/src/cli/prerequisites.ts
index 331e39d22..da1c536a2 100644
--- a/src/cli/prerequisites.ts
+++ b/src/cli/prerequisites.ts
@@ -52,6 +52,15 @@ export type CommandPrerequisiteContract = {
   readonly rules: readonly CommandPrerequisiteRule[];
 };
 
+/**
+ * A user-facing command that is intentionally handled outside the shared
+ * prerequisite interception matrix.
+ */
+export type LocalPrerequisiteHandling = {
+  readonly command: string;
+  readonly reason: string;
+};
+
 export const PREREQUISITE_CHECKS = [
   {
     id: "docker_cli",
@@ -619,6 +628,39 @@ export const COMMANDS_THAT_INVOKE_PREREQUISITE_CHECKS = [
   ),
 ] as const;
 
+export const COMMANDS_WITH_LOCAL_PREREQUISITE_HANDLING = [
+  {
+    command: "x github connect",
+    reason:
+      "GitHub connect is already the primary repair/bootstrap path, so it should keep command-local validation instead of redirecting into shared interception.",
+  },
+  {
+    command: "linear setup",
+    reason:
+      "Linear setup is a local project wiring command that can run before auth or profile state exists, so it should stay outside the shared interception matrix.",
+  },
+  {
+    command: "x github disconnect",
+    reason:
+      "Disconnect only removes stored local auth material and should keep command-local validation.",
+  },
+  {
+    command: "linear disconnect",
+    reason:
+      "Disconnect only removes stored local auth material and should keep command-local validation.",
+  },
+  {
+    command: "linear assignee-mappings",
+    reason:
+      "Assignee mapping inspection should continue to rely on command-local validation rather than shared prerequisite interception.",
+  },
+  {
+    command: "linear project-unlink",
+    reason:
+      "Project unlink is local cleanup state and should not be hidden behind shared setup guidance.",
+  },
+] as const satisfies readonly LocalPrerequisiteHandling[];
+
 export function getCommandPrerequisiteContracts(input: {
   readonly command: string;
 }): readonly CommandPrerequisiteContract[] {
@@ -626,3 +668,13 @@ export function getCommandPrerequisiteContracts(input: {
     contract.commands.includes(input.command)
   );
 }
+
+export function getLocalPrerequisiteHandling(input: {
+  readonly command: string;
+}): LocalPrerequisiteHandling | null {
+  return (
+    COMMANDS_WITH_LOCAL_PREREQUISITE_HANDLING.find(
+      (entry) => entry.command === input.command
+    ) ?? null
+  );
+}
diff --git a/tests/prerequisites-matrix.test.ts b/tests/prerequisites-matrix.test.ts
index 40322cbd1..693aef8eb 100644
--- a/tests/prerequisites-matrix.test.ts
+++ b/tests/prerequisites-matrix.test.ts
@@ -3,7 +3,9 @@ import { expect, test } from "bun:test";
 import {
   COMMAND_PREREQUISITE_CONTRACTS,
   COMMANDS_THAT_INVOKE_PREREQUISITE_CHECKS,
+  COMMANDS_WITH_LOCAL_PREREQUISITE_HANDLING,
   getCommandPrerequisiteContracts,
+  getLocalPrerequisiteHandling,
   PREREQUISITE_CHECKS,
 } from "../src/cli/prerequisites.ts";
 
@@ -150,6 +152,26 @@ test("cleanup and local-config commands stay out of shared prerequisite intercep
   ).toEqual([]);
 });
 
+test("major setup commands can be explicitly excluded from shared interception", () => {
+  expect(
+    COMMANDS_WITH_LOCAL_PREREQUISITE_HANDLING.map((entry) => entry.command)
+  ).toEqual([
+    "x github connect",
+    "linear setup",
+    "x github disconnect",
+    "linear disconnect",
+    "linear assignee-mappings",
+    "linear project-unlink",
+  ]);
+
+  expect(
+    getLocalPrerequisiteHandling({ command: "x github connect" })?.reason
+  ).toContain("primary repair/bootstrap path");
+  expect(
+    getLocalPrerequisiteHandling({ command: "linear setup" })?.reason
+  ).toContain("local project wiring command");
+});
+
 test("broker-backed linear commands guide through Hack auth", () => {
   const [connections] = getCommandPrerequisiteContracts({
     command: "linear connections",

From 7b316b7374ce19c070627f174d51cd3219d211a3 Mon Sep 17 00:00:00 2001
From: Symphony <symphony@hack>
Date: Sat, 14 Mar 2026 04:17:44 +0000
Subject: [PATCH 022/134] docs(tickets): design sqlite projection and journal

---
 ...3-14-hack-tickets-sqlite-journal-design.md | 331 ++++++++++++++++++
 1 file changed, 331 insertions(+)
 create mode 100644 docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md

diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
new file mode 100644
index 000000000..0aadc0891
--- /dev/null
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
@@ -0,0 +1,331 @@
+# Hack Tickets SQLite Projection And Journal Design
+
+## Goal
+Define a durable local storage architecture for Hack Tickets that keeps the git-backed JSONL journal as the canonical, portable source of truth while adding a deterministic SQLite projection for fast reads, sync queries, and repeated replay.
+
+## Current Foundation
+- Ticket history is stored as append-only monthly JSONL segments in `.hack/tickets/events/events-YYYY-MM.jsonl`.
+- The tickets ref is transported through git, so the system already has good offline and multi-machine portability.
+- Reads currently parse the full journal and materialize ticket state in memory on demand.
+- Sync-oriented reads such as external id lookup, conflict lookup, and checkpoint lookup are derived by replaying every event.
+
+## Design Summary
+- Keep the JSONL journal in the tickets git ref as the only portable source of truth.
+- Add a local SQLite database as a projection and replay index, not as a second authority.
+- Make replay idempotent by event identity first and deterministic by a total ordering key second.
+- Allow the projection to be deleted and rebuilt entirely from journal files at any time.
+- Treat recovery as a normal path: if the projection is missing, stale, corrupted, or on an old schema, rebuild it from the journal.
+
+## Non-Goals
+- Do not replace the git-backed journal with SQLite.
+- Do not require SQLite files to sync through git.
+- Do not introduce mutable event updates, event compaction that changes meaning, or snapshot files that become a new source of truth.
+- Do not redesign ticket semantics beyond what is needed for deterministic replay and indexed reads.
+
+## Alternatives Considered
+### Recommended: journal as source of truth, SQLite as local projection
+This keeps portability and inspectability in git while solving the current replay cost for reads and sync. It also gives a clean recovery story because the projection is disposable.
+
+### Rejected: SQLite as the primary store with git export/import
+This would improve local read performance, but it would weaken the current portability model and create a second system boundary around export timing, merge semantics, and operational recovery.
+
+### Rejected: keep pure JSONL replay and optimize the in-memory materializer
+This avoids a new storage layer, but it does not materially improve cold-start reads, repeated sync scans, or future richer queries such as open conflicts by provider or external id lookup.
+
+## Storage Layout
+### Canonical journal
+Keep the existing git-backed journal layout inside the tickets ref worktree:
+- `.hack/tickets/events/events-YYYY-MM.jsonl`
+
+Each line remains one immutable event envelope:
+- `eventId`
+- `ts`
+- `tsIso`
+- `actor`
+- `orderKey?`
+- `projectId?`
+- `projectName?`
+- `ticketId`
+- `type`
+- `payload`
+
+### Local-only projection
+Add a local SQLite file outside the synced tickets worktree:
+- `.hack/tickets/state/projection.sqlite`
+
+Companion files that are safe to delete:
+- `.hack/tickets/state/projection.sqlite-shm`
+- `.hack/tickets/state/projection.sqlite-wal`
+
+This directory should stay local-only and be ignored by both the main repo and the tickets ref.
+
+## Journal Semantics
+### Source of truth
+The journal is authoritative. SQLite is derived state. If the two disagree, the journal wins and the projection must be rebuilt or repaired.
+
+### Append-only rule
+Published events are immutable. The only allowed rewrite is semantic-preserving normalization during sync:
+- remove duplicate lines with the same `eventId`
+- keep exactly one payload for a given `eventId`
+- rewrite segment ordering into the canonical replay order
+
+### Event identity
+`eventId` is the logical identity of an event across machines. Reapplying the same `eventId` is a no-op if the payload hash matches.
+
+If the same `eventId` appears with different content, that is corruption, not conflict. Replay must stop and report the bad event ids instead of guessing.
+
+### Canonical replay order
+Replay uses this total order:
+1. `ts` ascending
+2. `orderKey` ascending when present
+3. `eventId` ascending
+
+This order is deterministic across machines and rebuilds, even when segment files were merged from multiple writers. Segment filename and line number are recorded for diagnostics and incremental scanning, but they are not part of domain ordering.
+
+### Idempotency rule
+Applying an event more than once must have the same effect as applying it once.
+
+The projection enforces this by inserting the event envelope into `journal_events` first. If the insert conflicts on `event_id`, replay compares the stored payload hash:
+- same hash: skip as already applied
+- different hash: stop replay and mark the projection unhealthy
+
+## SQLite Projection Schema
+### Projection metadata
+`projection_meta`
+- `key TEXT PRIMARY KEY`
+- `value TEXT NOT NULL`
+
+Required keys:
+- `schema_version`
+- `journal_format_version`
+- `projection_status` with values `ready` or `rebuilding`
+- `last_replayed_ts`
+- `last_replayed_order_key`
+- `last_replayed_event_id`
+- `last_replayed_at`
+
+### Replay index
+`journal_events`
+- `event_id TEXT PRIMARY KEY`
+- `ticket_id TEXT NOT NULL`
+- `ts INTEGER NOT NULL`
+- `ts_iso TEXT NOT NULL`
+- `order_key TEXT`
+- `actor TEXT NOT NULL`
+- `project_id TEXT`
+- `project_name TEXT`
+- `type TEXT NOT NULL`
+- `payload_json TEXT NOT NULL`
+- `payload_hash TEXT NOT NULL`
+- `segment_name TEXT NOT NULL`
+- `segment_line INTEGER NOT NULL`
+- `applied_at TEXT NOT NULL`
+
+Indexes:
+- `journal_events_ticket_order_idx (ticket_id, ts, order_key, event_id)`
+- `journal_events_type_idx (type, ts, event_id)`
+- `journal_events_project_idx (project_id, ts, event_id)`
+
+This table is the durable idempotency fence and powers fast `show` queries without reparsing JSONL.
+
+### Ticket projection
+`tickets`
+- `ticket_id TEXT PRIMARY KEY`
+- `title TEXT NOT NULL`
+- `body TEXT`
+- `status TEXT NOT NULL`
+- `created_at TEXT NOT NULL`
+- `updated_at TEXT NOT NULL`
+- `owner TEXT NOT NULL`
+- `source TEXT NOT NULL`
+- `assignee TEXT`
+- `external_system TEXT`
+- `external_id TEXT`
+- `external_key TEXT`
+- `external_url TEXT`
+- `external_project_id TEXT`
+- `external_project_name TEXT`
+- `external_team_id TEXT`
+- `project_id TEXT`
+- `project_name TEXT`
+- `last_event_id TEXT NOT NULL`
+
+Indexes:
+- `tickets_status_updated_idx (status, updated_at DESC)`
+- `tickets_project_updated_idx (project_id, updated_at DESC)`
+- `tickets_external_lookup_idx (external_system, external_id)`
+- `tickets_source_status_idx (source, status, updated_at DESC)`
+
+### Multi-value projections
+`ticket_dependencies`
+- `ticket_id TEXT NOT NULL`
+- `depends_on_ticket_id TEXT NOT NULL`
+- `PRIMARY KEY (ticket_id, depends_on_ticket_id)`
+
+`ticket_blocks`
+- `ticket_id TEXT NOT NULL`
+- `blocks_ticket_id TEXT NOT NULL`
+- `PRIMARY KEY (ticket_id, blocks_ticket_id)`
+
+`ticket_tags`
+- `ticket_id TEXT NOT NULL`
+- `tag TEXT NOT NULL`
+- `PRIMARY KEY (ticket_id, tag)`
+
+Indexes:
+- `ticket_dependencies_depends_idx (depends_on_ticket_id, ticket_id)`
+- `ticket_blocks_blocks_idx (blocks_ticket_id, ticket_id)`
+- `ticket_tags_tag_idx (tag, ticket_id)`
+
+### Append-only child entities
+`ticket_comments`
+- `comment_id TEXT PRIMARY KEY`
+- `ticket_id TEXT NOT NULL`
+- `body TEXT NOT NULL`
+- `source TEXT NOT NULL`
+- `actor TEXT NOT NULL`
+- `created_at TEXT NOT NULL`
+- `external_id TEXT`
+- `external_url TEXT`
+- `last_event_id TEXT NOT NULL`
+
+`ticket_review_notes`
+- `note_id TEXT PRIMARY KEY`
+- `ticket_id TEXT NOT NULL`
+- `body TEXT NOT NULL`
+- `actor TEXT NOT NULL`
+- `created_at TEXT NOT NULL`
+- `context TEXT`
+- `last_event_id TEXT NOT NULL`
+
+`ticket_sync_checkpoints`
+- `checkpoint_id TEXT PRIMARY KEY`
+- `ticket_id TEXT NOT NULL`
+- `provider TEXT NOT NULL`
+- `profile_id TEXT`
+- `direction TEXT`
+- `remote_cursor TEXT`
+- `remote_updated_at TEXT`
+- `local_updated_at TEXT`
+- `actor TEXT NOT NULL`
+- `created_at TEXT NOT NULL`
+- `last_event_id TEXT NOT NULL`
+
+`ticket_sync_conflicts`
+- `conflict_id TEXT PRIMARY KEY`
+- `ticket_id TEXT NOT NULL`
+- `provider TEXT NOT NULL`
+- `field TEXT NOT NULL`
+- `status TEXT NOT NULL`
+- `authority TEXT`
+- `summary TEXT`
+- `local_value_json TEXT`
+- `remote_value_json TEXT`
+- `created_at TEXT NOT NULL`
+- `updated_at TEXT NOT NULL`
+- `resolution TEXT`
+- `resolution_summary TEXT`
+- `resolved_at TEXT`
+- `resolved_by TEXT`
+- `last_event_id TEXT NOT NULL`
+
+Indexes:
+- `ticket_comments_ticket_created_idx (ticket_id, created_at, comment_id)`
+- `ticket_review_notes_ticket_created_idx (ticket_id, created_at, note_id)`
+- `ticket_sync_checkpoints_lookup_idx (ticket_id, provider, profile_id, created_at DESC)`
+- `ticket_sync_conflicts_open_idx (status, provider, updated_at DESC)`
+- `ticket_sync_conflicts_ticket_idx (ticket_id, updated_at DESC)`
+
+## Replay Rules
+### Startup path
+1. Open SQLite in WAL mode.
+2. Read `projection_meta`.
+3. If the file is missing, schema version is wrong, status is `rebuilding`, or SQLite reports corruption, delete and rebuild.
+4. Otherwise scan journal segments for new or changed lines after the last applied sort key.
+
+### Incremental replay
+For each journal line in canonical order:
+1. Parse and validate the event envelope.
+2. Start a transaction.
+3. Insert into `journal_events`.
+4. If the insert is a duplicate with the same hash, commit a no-op transaction.
+5. If it is new, apply the event to the relevant projection tables.
+6. Update `projection_meta` with the last applied sort key.
+7. Commit.
+
+This keeps replay crash-safe and allows progress to resume from the last committed event.
+
+### Event application rules
+- `ticket.created`: insert a row into `tickets`, replace dependency/block/tag sets from payload, set `created_at` and `updated_at` from the event timestamp.
+- `ticket.updated`: patch only provided fields, replace dependency/block/tag sets only when they appear in payload, set `updated_at`.
+- `ticket.status_changed`: update `status` and `updated_at`.
+- `ticket.comment_appended`: insert into `ticket_comments`.
+- `ticket.comment_linked`: patch `external_id` and `external_url` for the existing comment row.
+- `ticket.review_note_appended`: insert into `ticket_review_notes`.
+- `ticket.sync_checkpoint_recorded`: insert into `ticket_sync_checkpoints`.
+- `ticket.sync_conflict_recorded`: insert into `ticket_sync_conflicts` with `status = open`.
+- `ticket.sync_conflict_resolved`: patch the matching conflict row to a resolved state.
+
+If an event references missing local state that should already exist, replay stops with a projection error instead of silently inventing rows.
+
+## Rebuild And Recovery
+### Full rebuild
+Full rebuild is deterministic:
+1. Delete or move aside the SQLite file.
+2. Recreate schema.
+3. Mark `projection_status = rebuilding`.
+4. Replay every journal segment in canonical order.
+5. Mark `projection_status = ready`.
+
+Given the same journal bytes, rebuild produces the same projection rows and indexes every time.
+
+### Crash recovery
+Crash recovery relies on SQLite transactions and WAL:
+- a half-applied event rolls back automatically
+- committed events remain durable
+- the replay cursor only advances in the same transaction as the projection updates
+
+If the process dies mid-rebuild, the next startup sees `projection_status = rebuilding` and starts a clean rebuild rather than trusting partial state.
+
+### Corruption recovery
+Recoverable failures:
+- missing SQLite file
+- outdated projection schema
+- WAL or database corruption
+
+Unrecoverable without operator action:
+- malformed JSONL that cannot be parsed
+- duplicate `eventId` with different payload hashes
+- event references to impossible prior state caused by journal corruption
+
+In recoverable cases, automatically rebuild. In unrecoverable cases, surface a hard error with the offending segment and line number.
+
+## Sync And Query Benefits
+The projection specifically accelerates:
+- `tickets list` by reading `tickets` plus indexed filters
+- `tickets show` by reading one ticket and its child tables
+- external sync lookup by `external_system` and `external_id`
+- checkpoint lookup by provider and profile
+- conflict review queries such as open conflicts by provider, project, or ticket
+- repeated daemon or autosync loops that need to ask “what changed since cursor X?”
+
+## Multi-Machine Behavior
+- Multiple machines can append semantically equivalent journals and later merge through git.
+- Normalization merges by `eventId` union, not by trusting file order.
+- Projection replay is safe after repeated fetch, merge, or sync because duplicate events are idempotent.
+- Because SQLite is local-only, machines never need to coordinate projection files. They only need the same journal bytes.
+
+## Implementation Notes
+- Use `bun:sqlite` for the projection layer.
+- Keep journal parsing and replay in one module so rebuild and incremental apply share the same code path.
+- Expose a small health surface later, for example `tickets inspect` or `tickets rebuild`, but keep those commands out of this design’s critical path.
+
+## Validation
+- Rebuilding from the same journal twice yields byte-equivalent query results.
+- Reapplying the same merged journal does not duplicate comments, checkpoints, or conflicts.
+- Deleting the SQLite file does not lose ticket history.
+- Sync-heavy reads stop scanning all JSONL files on each command.
+- Duplicate `eventId` with mismatched payload is detected as corruption.
+
+## Recommendation
+Implement the projection as a local SQLite cache with `journal_events` as the idempotent replay fence and the `tickets` plus child tables as the read model. This gives deterministic rebuilds, fast reads, and safe repeated event application without weakening the current git-portable journal architecture.

From c8e6d9251a73907b0c7a3384165a1658d2d97928 Mon Sep 17 00:00:00 2001
From: Symphony <symphony@hack>
Date: Sat, 14 Mar 2026 04:17:53 +0000
Subject: [PATCH 023/134] docs(tickets): plan sqlite projection implementation

---
 ...-03-14-hack-tickets-sqlite-journal-plan.md | 212 ++++++++++++++++++
 1 file changed, 212 insertions(+)
 create mode 100644 docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md

diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
new file mode 100644
index 000000000..4759c4f55
--- /dev/null
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
@@ -0,0 +1,212 @@
+# Hack Tickets SQLite Projection Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a local SQLite projection for Hack Tickets that accelerates reads and sync queries while preserving the git-backed JSONL journal as the only portable source of truth.
+
+**Architecture:** Build a `bun:sqlite` projection database under `.hack/tickets/state`, store a durable replay index keyed by `eventId`, and derive ticket/read tables from the existing journal event stream. Rebuild and incremental replay must use the same code path so crash recovery and deterministic rebuild behavior stay simple.
+
+**Tech Stack:** Bun, TypeScript, `bun:sqlite`, existing tickets git channel, Bun tests
+
+---
+
+### Task 1: Lock The Projection Contract In Tests
+
+**Files:**
+- Create: `tests/tickets-projection.test.ts`
+- Modify: `tests/tickets-store.test.ts`
+
+**Step 1: Write failing projection tests**
+- Add a test that rebuilds from a fixed journal and asserts ticket, comment, checkpoint, and conflict rows are present in the projection.
+- Add a test that replays the same event stream twice and asserts child rows are not duplicated.
+- Add a test that feeds the same `eventId` with different payloads and asserts replay fails with a corruption error.
+
+**Step 2: Run focused tests to verify failure**
+Run: `bun test tests/tickets-projection.test.ts tests/tickets-store.test.ts`
+Expected: FAIL because no projection module or corruption checks exist yet.
+
+**Step 3: Commit**
+```bash
+git add tests/tickets-projection.test.ts tests/tickets-store.test.ts
+git commit -m "test(tickets): define projection replay contract"
+```
+
+### Task 2: Add SQLite Schema And Projection Metadata
+
+**Files:**
+- Create: `src/control-plane/extensions/tickets/projection.ts`
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Test: `tests/tickets-projection.test.ts`
+
+**Step 1: Write the minimal schema bootstrap**
+- Create schema helpers for:
+  - `projection_meta`
+  - `journal_events`
+  - `tickets`
+  - `ticket_dependencies`
+  - `ticket_blocks`
+  - `ticket_tags`
+  - `ticket_comments`
+  - `ticket_review_notes`
+  - `ticket_sync_checkpoints`
+  - `ticket_sync_conflicts`
+
+**Step 2: Wire projection path resolution**
+- Resolve the database path under `.hack/tickets/state/projection.sqlite`.
+- Ensure the state directory exists without placing the SQLite file inside the synced tickets worktree.
+
+**Step 3: Run focused tests**
+Run: `bun test tests/tickets-projection.test.ts`
+Expected: FAIL only on replay behavior, not missing schema setup.
+
+**Step 4: Commit**
+```bash
+git add src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts
+git commit -m "feat(tickets): add projection schema bootstrap"
+```
+
+### Task 3: Implement Deterministic Replay And Idempotent Apply
+
+**Files:**
+- Modify: `src/control-plane/extensions/tickets/projection.ts`
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Test: `tests/tickets-projection.test.ts`
+
+**Step 1: Write the replay engine**
+- Parse journal files in canonical order by `ts`, `orderKey`, `eventId`.
+- Insert each event into `journal_events` before mutating read tables.
+- Compare payload hashes on duplicate `eventId`.
+
+**Step 2: Implement event appliers**
+- `ticket.created`
+- `ticket.updated`
+- `ticket.status_changed`
+- `ticket.comment_appended`
+- `ticket.comment_linked`
+- `ticket.review_note_appended`
+- `ticket.sync_checkpoint_recorded`
+- `ticket.sync_conflict_recorded`
+- `ticket.sync_conflict_resolved`
+
+**Step 3: Run focused tests**
+Run: `bun test tests/tickets-projection.test.ts`
+Expected: PASS
+
+**Step 4: Commit**
+```bash
+git add src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts tests/tickets-projection.test.ts
+git commit -m "feat(tickets): replay journal into sqlite projection"
+```
+
+### Task 4: Route Reads Through The Projection With Journal Fallback
+
+**Files:**
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Modify: `src/control-plane/extensions/tickets/commands.ts`
+- Test: `tests/tickets-store.test.ts`
+- Test: `tests/tickets-extension.test.ts`
+
+**Step 1: Change store read paths**
+- `listTickets`
+- `getTicket`
+- `listEvents`
+- `getTicketDetail`
+- any sync lookup helpers added during implementation
+
+These reads should prefer SQLite and only trigger replay or rebuild when projection state is missing or stale.
+
+**Step 2: Preserve write path semantics**
+- Keep event append writing to JSONL through the existing git channel.
+- After append success, replay only the new events into SQLite instead of reparsing the entire journal.
+
+**Step 3: Run focused tests**
+Run: `bun test tests/tickets-store.test.ts tests/tickets-extension.test.ts`
+Expected: PASS
+
+**Step 4: Commit**
+```bash
+git add src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/commands.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts
+git commit -m "feat(tickets): serve reads from sqlite projection"
+```
+
+### Task 5: Add Rebuild And Health Recovery Paths
+
+**Files:**
+- Modify: `src/control-plane/extensions/tickets/projection.ts`
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Modify: `src/control-plane/extensions/tickets/commands.ts`
+- Test: `tests/tickets-projection.test.ts`
+
+**Step 1: Add rebuild triggers**
+- missing database
+- schema version mismatch
+- `projection_status = rebuilding`
+- SQLite open failure or corruption
+
+**Step 2: Add an explicit rebuild entry point**
+- internal store method first
+- optional CLI surface only if needed for debugging, for example `hack tickets rebuild`
+
+**Step 3: Run focused tests**
+Run: `bun test tests/tickets-projection.test.ts tests/tickets-store.test.ts`
+Expected: PASS
+
+**Step 4: Commit**
+```bash
+git add src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/commands.ts tests/tickets-projection.test.ts tests/tickets-store.test.ts
+git commit -m "feat(tickets): add projection rebuild recovery"
+```
+
+### Task 6: Verify Git Sync Interop And Repeated Application
+
+**Files:**
+- Modify: `tests/tickets-git-channel.test.ts`
+- Modify: `tests/tickets-extension.test.ts`
+
+**Step 1: Add integration coverage**
+- sync remote journal content into a local clone
+- replay merged logs with duplicate events
+- confirm projection rows remain correct after repeated sync
+
+**Step 2: Run focused tests**
+Run: `bun test tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts`
+Expected: PASS
+
+**Step 3: Commit**
+```bash
+git add tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts
+git commit -m "test(tickets): verify projection sync idempotency"
+```
+
+### Task 7: Run Quality Gates And Final Documentation Pass
+
+**Files:**
+- Modify: `docs/guides/tickets.md`
+- Modify: `docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md` if implementation changed details
+- Modify: `docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md` if execution changed steps
+
+**Step 1: Document the new local state layout**
+- Describe the projection database as local-only and rebuildable.
+- Document any new CLI rebuild or inspect command if added.
+
+**Step 2: Run repo quality gates**
+Run:
+```bash
+bun test tests/tickets-projection.test.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts tests/tickets-git-channel.test.ts
+bun run check
+```
+Expected: PASS
+
+**Step 3: Commit**
+```bash
+git add docs/guides/tickets.md docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md tests/tickets-projection.test.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts tests/tickets-git-channel.test.ts src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/commands.ts
+git commit -m "feat(tickets): finish sqlite projection architecture"
+```
+
+Plan complete and saved to `docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md`. Two execution options:
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+Which approach?

From 57c4e8c63e60b27bf244396fc619700b819ef691 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:18:46 +0000
Subject: [PATCH 024/134] test: relax env backend command timeout

---
 tests/env-backend-command.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/env-backend-command.test.ts b/tests/env-backend-command.test.ts
index 8e09194b5..3753e6400 100644
--- a/tests/env-backend-command.test.ts
+++ b/tests/env-backend-command.test.ts
@@ -392,7 +392,7 @@ test(
 
 test(
   "env list shows storage summary even when no contract exists",
-  { timeout: 20_000 },
+  { timeout: 60_000 },
   async () => {
     if (!tempDir) {
       throw new Error("Missing temp dir");

From c0f6a67ea170f43868d13d053a98c4357a0f2fa8 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:19:56 +0000
Subject: [PATCH 025/134] feat: improve runtime crash recovery guidance

---
 README.md                                     |  10 +-
 docs/cli.md                                   |  16 ++
 ...026-03-14-runtime-crash-recovery-design.md | 131 +++++++++++
 .../2026-03-14-runtime-crash-recovery-plan.md | 215 ++++++++++++++++++
 src/commands/crash-capture.ts                 | 136 ++++++++++-
 src/commands/doctor.ts                        |  66 ++++++
 src/commands/recovery-guidance.ts             |  94 ++++++++
 tests/crash-capture.test.ts                   |  78 +++++++
 tests/doctor-command.test.ts                  |  69 ++++++
 9 files changed, 812 insertions(+), 3 deletions(-)
 create mode 100644 docs/plans/2026-03-14-runtime-crash-recovery-design.md
 create mode 100644 docs/plans/2026-03-14-runtime-crash-recovery-plan.md
 create mode 100644 src/commands/recovery-guidance.ts
 create mode 100644 tests/crash-capture.test.ts
 create mode 100644 tests/doctor-command.test.ts

diff --git a/README.md b/README.md
index 31d64cc93..6c80078b5 100644
--- a/README.md
+++ b/README.md
@@ -817,7 +817,12 @@ See examples:
 
 ## Troubleshooting
 
-- `*.hack` doesn’t resolve: run `hack doctor`, then `hack global install` (macOS: ensure dnsmasq is running).
+- Start with `hack doctor`. It now separates:
+  - temporary breakage that is usually fixed by `hack global up`, `hack restart`, or a daemon restart
+  - deeper DNS/network/CA drift that should go through `hack doctor --fix`
+  - issues that need manual follow-up instead of a guessed repair
+
+- `*.hack` doesn’t resolve: run `hack doctor`, then follow the suggested restart or repair path (macOS may still need dnsmasq running via `hack global install`).
 
 - Stale global setup / CoreDNS issues: run `hack doctor --fix` (refreshes network + CoreDNS + CA).
 
@@ -837,6 +842,9 @@ See examples:
 
 - OAuth redirect errors: use the OAuth alias host (`*.hack.gy`) or `localhost` (providers may reject non-public suffixes like `.hack`).
 
+- If runtime or proxy failures still reproduce after the recovery steps, collect a bundle with
+  `hack crash-capture --path <repo>` and review `summary.json` first.
+
 
 
 ## Development
diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..8b993feb9 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1238,6 +1238,14 @@ Options:
 
 Usage: `hack doctor [options]`
 
+Use this as the first recovery step when runtime or proxy behavior looks wrong. The command now groups failures into:
+
+- temporary breakage you can usually recover with restart commands such as `hack global up`, `hack restart`, or daemon restart
+- deeper configuration drift that should go through `hack doctor --fix`
+- manual follow-up items that are intentionally not auto-classified
+
+If the problem still reproduces after the suggested recovery flow, collect a bundle with `hack crash-capture`.
+
 Options:
 
 | Flag | Type | Default | Description |
@@ -1253,9 +1261,17 @@ Collects a post-failure bundle under `.tmp/crash-capture-<timestamp>/` including
 
 - `metadata.json` with platform/project context
 - `commands.json` with command outcomes
+- `summary.json` with failed commands and recommended next steps
+- `README.txt` with a short triage map for the bundle
 - `docker` / `hack` snapshots
 - macOS unified log slices (OrbStack + kernel container events) when available
 
+Recommended usage:
+
+1. Run `hack doctor` first to try restart or repair guidance.
+2. If the issue persists, run `hack crash-capture --path <repo>`.
+3. Read `summary.json`, then `commands.json`, then the referenced `*.log` files.
+
 Options:
 
 | Flag | Type | Default | Description |
diff --git a/docs/plans/2026-03-14-runtime-crash-recovery-design.md b/docs/plans/2026-03-14-runtime-crash-recovery-design.md
new file mode 100644
index 000000000..dcb9d064a
--- /dev/null
+++ b/docs/plans/2026-03-14-runtime-crash-recovery-design.md
@@ -0,0 +1,131 @@
+# Runtime Crash Recovery Design
+
+## Context
+
+`hack doctor` already detects many runtime and proxy failure modes, and `hack crash-capture` already snapshots some local state. The gap is operator usability: warnings are isolated, restart versus repair paths are not grouped into a repeatable sequence, and crash bundles require too much manual interpretation.
+
+This issue targets runtime and proxy breakage where users need to answer three questions quickly:
+
+1. Is this likely temporary breakage that a restart can fix?
+2. Is this deeper configuration drift that needs repair?
+3. If it still fails, what artifact should be collected for diagnosis?
+
+## Goals
+
+- Make crash bundles immediately useful for diagnosis without requiring source familiarity.
+- Make restart and proxy recovery steps explicit in `hack doctor`.
+- Separate temporary runtime/proxy drift from deeper configuration problems.
+- Keep the recovery flow consistent across CLI output and written docs.
+
+## Non-Goals
+
+- Reworking core runtime startup behavior.
+- Adding background crash daemons or automatic upload/reporting.
+- Expanding `doctor --fix` beyond its current repair scope.
+
+## Approaches Considered
+
+### 1. Add structured recovery guidance plus richer crash bundle summaries (recommended)
+
+Keep the existing commands, but add:
+- recovery classification in `hack doctor`
+- a readable recovery panel with ordered commands
+- structured crash-bundle summaries plus extra diagnostics
+
+Pros:
+- Fits existing operator workflow.
+- Low risk to core runtime behavior.
+- Improves both human UX and diagnostic artifacts.
+
+Cons:
+- Requires keeping diagnosis heuristics conservative.
+
+### 2. Add more raw logs only
+
+Pros:
+- Small code change.
+
+Cons:
+- Does not solve the “what should I do next?” problem.
+- Keeps diagnosis dependent on tribal knowledge.
+
+### 3. Auto-run repair actions from every relevant command
+
+Pros:
+- Fewer manual steps in ideal cases.
+
+Cons:
+- Higher blast radius.
+- Too aggressive for ambiguous failure states.
+
+## Recommended Design
+
+Adopt approach 1.
+
+### Doctor Recovery Workflow
+
+`hack doctor` should classify warnings/errors into operator-facing buckets:
+
+- `temporary breakage`
+  - global proxy/runtime not running
+  - stale project host mapping
+  - daemon not running or starting
+- `configuration repair`
+  - CoreDNS forwarding failure
+  - missing CA
+  - ingress network/subnet drift
+  - dnsmasq/resolver drift
+- `manual follow-up`
+  - anything not safely auto-classified
+
+After the checks complete, `hack doctor` should print one recovery panel that:
+
+1. lists the immediate restart commands first
+2. lists repair commands second
+3. finishes with verification and crash-capture collection
+
+That panel should make the intended sequence obvious:
+
+1. `hack global up` for missing proxy/global runtime
+2. `hack restart` for stale project host mappings
+3. `hack daemon start` or `hack daemon clear && hack daemon start` for daemon drift
+4. `hack doctor --fix` for configuration repair
+5. `hack doctor` to verify
+6. `hack crash-capture --path <repo>` if still broken
+
+### Crash Bundle Improvements
+
+`hack crash-capture` should produce a bundle that is useful before opening individual log files.
+
+New artifacts:
+- `summary.json` with captured command outcomes, detected symptoms, and recommended next steps
+- `README.txt` with a short human-readable bundle map and recovery sequence
+
+Additional captured state:
+- `hack doctor --path <repo>`
+- `hack global status --json`
+- `hack daemon logs --no-follow`
+- global proxy logs where available
+- docker network inspection for ingress/logging networks
+
+The bundle should also avoid avoidable capture failures. The current process snapshot uses `rg`; it should fall back to a more portable filter so process capture still works on machines without ripgrep.
+
+### Diagnostics Heuristics
+
+Both `hack doctor` and `hack crash-capture` should share the same conservative recovery diagnosis rules so the bundle summary and live CLI guidance do not drift.
+
+Rules:
+- Only classify a step as restartable when the associated check directly implies that restart action.
+- Prefer `hack doctor --fix` for DNS/network/CA drift.
+- Preserve unknown issues as explicit follow-up items instead of over-claiming a fix path.
+
+## Testing
+
+- Add unit tests for doctor recovery classification and rendered action groups.
+- Add unit tests for crash bundle summary generation and human-readable README content.
+- Add command-level tests for crash-capture outputs that do not require live Docker access.
+
+## Docs
+
+- Update CLI docs for `hack doctor` and `hack crash-capture`.
+- Update README troubleshooting so it mirrors the exact same recovery sequence as the CLI.
diff --git a/docs/plans/2026-03-14-runtime-crash-recovery-plan.md b/docs/plans/2026-03-14-runtime-crash-recovery-plan.md
new file mode 100644
index 000000000..4c3dac244
--- /dev/null
+++ b/docs/plans/2026-03-14-runtime-crash-recovery-plan.md
@@ -0,0 +1,215 @@
+# Runtime Crash Recovery Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Improve runtime/proxy recovery by adding explicit operator guidance in `hack doctor` and richer, self-explanatory artifacts in `hack crash-capture`.
+
+**Architecture:** Keep the existing diagnostics commands, but add shared recovery diagnosis helpers that classify failures into restart, repair, and follow-up buckets. Use those helpers to render a recovery panel in `hack doctor` and to write `summary.json` and `README.txt` inside crash bundles.
+
+**Tech Stack:** Bun, TypeScript, Bun test, existing CLI display helpers
+
+---
+
+### Task 1: Add failing tests for doctor recovery guidance
+
+**Files:**
+- Create: `tests/doctor-command.test.ts`
+- Modify: `src/commands/doctor.ts`
+
+**Step 1: Write the failing test**
+
+Add focused tests for recovery diagnosis such as:
+- proxy/global runtime down suggests `hack global up`
+- stale host mapping suggests `hack restart`
+- DNS/network drift suggests `hack doctor --fix`
+- stale daemon state suggests the daemon restart path
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+bun test tests/doctor-command.test.ts
+```
+
+Expected: FAIL because the exported diagnosis helpers do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Export the smallest helper surface needed to classify check results and render ordered recovery actions.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+bun test tests/doctor-command.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/commands/doctor.ts tests/doctor-command.test.ts
+git commit -m "test: cover doctor recovery guidance"
+```
+
+### Task 2: Add failing tests for crash bundle summaries
+
+**Files:**
+- Create: `tests/crash-capture.test.ts`
+- Modify: `src/commands/crash-capture.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+- summary generation from command results
+- readable README content
+- recovery recommendations matching doctor heuristics
+- process snapshot command not depending on `rg`
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+bun test tests/crash-capture.test.ts
+```
+
+Expected: FAIL because the new helpers and artifacts do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Export bundle-summary helpers and update the capture command list/artifact writers.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+bun test tests/crash-capture.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/commands/crash-capture.ts tests/crash-capture.test.ts
+git commit -m "test: cover crash bundle summaries"
+```
+
+### Task 3: Implement the doctor recovery panel
+
+**Files:**
+- Modify: `src/commands/doctor.ts`
+- Test: `tests/doctor-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Extend the tests to assert grouped recovery actions and the temporary-vs-configuration distinction.
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+bun test tests/doctor-command.test.ts
+```
+
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+- classify checks into recovery buckets
+- render a single panel with ordered commands
+- keep unknown issues explicit rather than guessing
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+bun test tests/doctor-command.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/commands/doctor.ts tests/doctor-command.test.ts
+git commit -m "feat: add explicit doctor recovery guidance"
+```
+
+### Task 4: Implement richer crash bundle artifacts
+
+**Files:**
+- Modify: `src/commands/crash-capture.ts`
+- Test: `tests/crash-capture.test.ts`
+
+**Step 1: Write the failing test**
+
+Extend the tests to assert:
+- `summary.json` structure
+- `README.txt` guidance text
+- additional capture commands included
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+bun test tests/crash-capture.test.ts
+```
+
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+- capture additional doctor/global/runtime diagnostics
+- write bundle summary/readme artifacts
+- switch the process snapshot command to a portable filter
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+bun test tests/crash-capture.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/commands/crash-capture.ts tests/crash-capture.test.ts
+git commit -m "feat: improve crash capture triage artifacts"
+```
+
+### Task 5: Update docs and verify quality gates
+
+**Files:**
+- Modify: `README.md`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing test**
+
+No automated test. Use doc consistency review against the implementation.
+
+**Step 2: Run verification**
+
+Run:
+```bash
+bun test tests/doctor-command.test.ts tests/crash-capture.test.ts
+bun test
+bun x ultracite fix
+bun x ultracite check
+```
+
+Expected: targeted tests pass; full suite and checks pass or expose any unrelated failures that must be reported.
+
+**Step 3: Write minimal implementation**
+
+Update docs to mirror the same recovery sequence shown by `hack doctor`.
+
+**Step 4: Commit**
+
+```bash
+git add README.md docs/cli.md
+git commit -m "docs: document runtime and proxy recovery workflow"
+```
diff --git a/src/commands/crash-capture.ts b/src/commands/crash-capture.ts
index 5f420bd57..5b10e1476 100644
--- a/src/commands/crash-capture.ts
+++ b/src/commands/crash-capture.ts
@@ -4,6 +4,10 @@ import { basename, resolve } from "node:path";
 import type { CommandHandlerFor } from "../cli/command.ts";
 import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
 import { optPath } from "../cli/options.ts";
+import {
+  DEFAULT_INGRESS_NETWORK,
+  DEFAULT_LOGGING_NETWORK,
+} from "../constants.ts";
 import { findProjectContext, readProjectConfig } from "../lib/project.ts";
 import { exec } from "../lib/shell.ts";
 import { display } from "../ui/display.ts";
@@ -51,6 +55,16 @@ type CaptureCommandResult = {
   readonly bytes: number;
 };
 
+type CrashCaptureSummary = {
+  readonly captureRoot: string;
+  readonly projectRoot: string | null;
+  readonly commandCount: number;
+  readonly failureCount: number;
+  readonly failedCommands: readonly string[];
+  readonly errors: readonly string[];
+  readonly nextSteps: readonly string[];
+};
+
 type CaptureMetadata = {
   readonly capturedAt: string;
   readonly platform: string;
@@ -169,6 +183,26 @@ const handleCrashCapture: CommandHandlerFor<typeof crashCaptureSpec> = async ({
     },
   });
 
+  const summary = buildCrashCaptureSummary({
+    captureRoot,
+    projectRoot: project?.projectRoot ?? null,
+    results,
+    errors,
+  });
+  await writeJsonFile({
+    path: resolve(captureRoot, "summary.json"),
+    value: summary,
+  });
+  await Bun.write(
+    resolve(captureRoot, "README.txt"),
+    renderCrashCaptureReadme({
+      captureRoot,
+      projectRoot: project?.projectRoot ?? null,
+      failedCommands: summary.failedCommands,
+    }),
+    { createPath: true }
+  );
+
   await display.kv({
     title: "Crash capture complete",
     entries: [
@@ -254,12 +288,17 @@ async function resolveComposeProject(input: {
   }
 }
 
-function buildBaseCaptureCommands(input: {
+export function buildBaseCaptureCommands(input: {
   readonly projectRoot: string | null;
   readonly logWindow: string;
 }): readonly CaptureCommandSpec[] {
   const projectCommands: CaptureCommandSpec[] = input.projectRoot
     ? [
+        {
+          name: "hack_doctor_project",
+          cmd: ["hack", "doctor", "--path", input.projectRoot],
+          optional: true,
+        },
         {
           name: "hack_ps_project",
           cmd: ["hack", "ps", "--json", "--path", input.projectRoot],
@@ -329,12 +368,37 @@ function buildBaseCaptureCommands(input: {
       cmd: ["docker", "system", "df"],
       optional: true,
     },
+    {
+      name: "hack_daemon_logs",
+      cmd: ["hack", "daemon", "logs", "--no-follow"],
+      optional: true,
+    },
+    {
+      name: "hack_global_status",
+      cmd: ["hack", "global", "status", "--json"],
+      optional: true,
+    },
+    {
+      name: "hack_global_logs_caddy",
+      cmd: ["hack", "global", "logs", "caddy", "--no-follow", "--tail", "200"],
+      optional: true,
+    },
+    {
+      name: `docker_network_inspect_${DEFAULT_INGRESS_NETWORK}`,
+      cmd: ["docker", "network", "inspect", DEFAULT_INGRESS_NETWORK],
+      optional: true,
+    },
+    {
+      name: `docker_network_inspect_${DEFAULT_LOGGING_NETWORK}`,
+      cmd: ["docker", "network", "inspect", DEFAULT_LOGGING_NETWORK],
+      optional: true,
+    },
     {
       name: "ps_orbstack_processes",
       cmd: [
         "/bin/sh",
         "-lc",
-        "ps -Ao pid,ppid,etime,command | rg -i 'orbstack|vz|docker'",
+        "ps -Ao pid,ppid,etime,command | grep -iE 'orbstack|vz|docker' || true",
       ],
       optional: true,
     },
@@ -474,3 +538,71 @@ async function writeJsonFile(input: {
     createPath: true,
   });
 }
+
+export function buildCrashCaptureSummary(input: {
+  readonly captureRoot: string;
+  readonly projectRoot: string | null;
+  readonly results: readonly CaptureCommandResult[];
+  readonly errors: readonly string[];
+}): CrashCaptureSummary {
+  const failedCommands = input.results
+    .filter((result) => result.exitCode !== 0)
+    .map((result) => result.name);
+
+  return {
+    captureRoot: input.captureRoot,
+    projectRoot: input.projectRoot,
+    commandCount: input.results.length,
+    failureCount: failedCommands.length,
+    failedCommands,
+    errors: input.errors,
+    nextSteps: buildCrashCaptureNextSteps({
+      projectRoot: input.projectRoot,
+    }),
+  };
+}
+
+function buildCrashCaptureNextSteps(input: {
+  readonly projectRoot: string | null;
+}): readonly string[] {
+  const projectRoot = input.projectRoot ?? "<repo>";
+  return [
+    `Run \`hack doctor --path ${projectRoot}\` to classify restart versus repair work.`,
+    "If global proxy/runtime is down, run `hack global up`.",
+    `If project host mappings are stale, run \`hack restart --path ${projectRoot}\`.`,
+    `If doctor reports DNS/network/CA drift, run \`hack doctor --fix --path ${projectRoot}\`.`,
+  ];
+}
+
+export function renderCrashCaptureReadme(input: {
+  readonly captureRoot: string;
+  readonly projectRoot: string | null;
+  readonly failedCommands: readonly string[];
+}): string {
+  const projectRoot = input.projectRoot ?? "<repo>";
+  const failedCommands =
+    input.failedCommands.length > 0
+      ? input.failedCommands.map((command) => `- ${command}`)
+      : ["- none"];
+
+  return [
+    "Crash capture bundle",
+    "",
+    `Location: ${input.captureRoot}`,
+    `Project root: ${projectRoot}`,
+    "",
+    "Read in this order:",
+    "- summary.json",
+    "- commands.json",
+    "- *.log command captures",
+    "",
+    "Failed commands:",
+    ...failedCommands,
+    "",
+    "Suggested recovery flow:",
+    `1. hack doctor --path ${projectRoot}`,
+    "2. hack global up",
+    `3. hack restart --path ${projectRoot}`,
+    `4. hack doctor --fix --path ${projectRoot}`,
+  ].join("\n");
+}
diff --git a/src/commands/doctor.ts b/src/commands/doctor.ts
index a50897dc8..c5bce2e5f 100644
--- a/src/commands/doctor.ts
+++ b/src/commands/doctor.ts
@@ -60,6 +60,7 @@ import {
   renderGlobalCaddyCompose,
   renderGlobalCoreDnsConfig,
 } from "../templates.ts";
+import { display } from "../ui/display.ts";
 import { getFzfPath } from "../ui/fzf.ts";
 import { getGumPath } from "../ui/gum.ts";
 import { isColorEnabled } from "../ui/terminal.ts";
@@ -69,6 +70,7 @@ import {
   resolvePreferredHostDnsTarget,
   resolverHasNameserver,
 } from "./doctor-utils.ts";
+import { buildDoctorRecoveryGuidance } from "./recovery-guidance.ts";
 
 type CheckStatus = "ok" | "warn" | "error";
 
@@ -378,6 +380,9 @@ const handleDoctor: CommandHandlerFor<typeof doctorSpec> = async ({
 
   emitSlowChecksNote(results);
   renderMacNote();
+  if (!args.options.fix) {
+    await renderRecoveryGuidance(results);
+  }
 
   if (args.options.fix) {
     await runDoctorFix({ startDir });
@@ -2171,6 +2176,67 @@ function emitSlowChecksNote(results: readonly TimedCheckResult[]): void {
   note(slow.join("\n"), "Slow checks");
 }
 
+async function renderRecoveryGuidance(
+  results: readonly TimedCheckResult[]
+): Promise<void> {
+  const guidance = buildDoctorRecoveryGuidance({ results });
+  const hasActions =
+    guidance.temporaryBreakage.length > 0 ||
+    guidance.configurationRepair.length > 0 ||
+    guidance.followUp.length > 0;
+
+  if (!hasActions) {
+    return;
+  }
+
+  const lines: string[] = [];
+
+  if (guidance.temporaryBreakage.length > 0) {
+    lines.push("Temporary breakage:");
+    for (const command of guidance.temporaryBreakage) {
+      lines.push(`- ${command}`);
+    }
+  }
+
+  if (guidance.configurationRepair.length > 0) {
+    if (lines.length > 0) {
+      lines.push("");
+    }
+    lines.push("Configuration repair:");
+    for (const command of guidance.configurationRepair) {
+      lines.push(`- ${command}`);
+    }
+  }
+
+  if (guidance.followUp.length > 0) {
+    if (lines.length > 0) {
+      lines.push("");
+    }
+    lines.push("Manual follow-up:");
+    for (const item of guidance.followUp) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("Verify:");
+  for (const command of guidance.verify) {
+    lines.push(`- ${command}`);
+  }
+
+  lines.push("");
+  lines.push("If it still fails:");
+  for (const command of guidance.capture) {
+    lines.push(`- ${command}`);
+  }
+
+  await display.panel({
+    title: "Recovery workflow",
+    tone: "info",
+    lines,
+  });
+}
+
 function formatTimedResult(opts: {
   readonly result: CheckResult;
   readonly durationMs: number;
diff --git a/src/commands/recovery-guidance.ts b/src/commands/recovery-guidance.ts
new file mode 100644
index 000000000..8d31f9315
--- /dev/null
+++ b/src/commands/recovery-guidance.ts
@@ -0,0 +1,94 @@
+export type RecoveryCheckStatus = "ok" | "warn" | "error";
+
+export type RecoveryCheckResult = {
+  readonly name: string;
+  readonly status: RecoveryCheckStatus;
+  readonly message: string;
+};
+
+export type DoctorRecoveryGuidance = {
+  readonly temporaryBreakage: readonly string[];
+  readonly configurationRepair: readonly string[];
+  readonly followUp: readonly string[];
+  readonly verify: readonly string[];
+  readonly capture: readonly string[];
+};
+
+const FIX_CHECKS = new Set([
+  "caddy local ca",
+  "coredns forwarding",
+  "dns:hack",
+  "dns:hack.gy",
+  "dnsmasq:53",
+]);
+
+function pushUnique(target: string[], value: string): void {
+  if (!target.includes(value)) {
+    target.push(value);
+  }
+}
+
+export function buildDoctorRecoveryGuidance(input: {
+  readonly results: readonly RecoveryCheckResult[];
+}): DoctorRecoveryGuidance {
+  const temporaryBreakage: string[] = [];
+  const configurationRepair: string[] = [];
+  const followUp: string[] = [];
+
+  for (const result of input.results) {
+    if (result.status === "ok") {
+      continue;
+    }
+
+    if (
+      result.name === "proxy ports" &&
+      result.message.includes("hack global up")
+    ) {
+      pushUnique(temporaryBreakage, "hack global up");
+      continue;
+    }
+
+    if (
+      result.name === "caddy hosts" &&
+      result.message.includes("hack restart")
+    ) {
+      pushUnique(temporaryBreakage, "hack restart");
+      continue;
+    }
+
+    if (
+      result.name === "daemon" &&
+      result.message.includes("hack daemon clear")
+    ) {
+      pushUnique(temporaryBreakage, "hack daemon clear");
+      pushUnique(temporaryBreakage, "hack daemon start");
+      continue;
+    }
+
+    if (
+      result.name === "daemon" &&
+      result.message.includes("hack daemon start")
+    ) {
+      pushUnique(temporaryBreakage, "hack daemon start");
+      continue;
+    }
+
+    if (
+      FIX_CHECKS.has(result.name) ||
+      result.message.includes("hack doctor --fix")
+    ) {
+      pushUnique(configurationRepair, "hack doctor --fix");
+      continue;
+    }
+
+    followUp.push(`${result.name}: ${result.message}`);
+  }
+
+  return {
+    temporaryBreakage,
+    configurationRepair,
+    followUp,
+    verify: ["hack doctor"],
+    capture: ["hack crash-capture --path <repo>"],
+  };
+}
diff --git a/tests/crash-capture.test.ts b/tests/crash-capture.test.ts
new file mode 100644
index 000000000..2f0a0b3b1
--- /dev/null
+++ b/tests/crash-capture.test.ts
@@ -0,0 +1,78 @@
+import { expect, test } from "bun:test";
+
+import {
+  buildBaseCaptureCommands,
+  buildCrashCaptureSummary,
+  renderCrashCaptureReadme,
+} from "../src/commands/crash-capture.ts";
+
+test("crash capture includes doctor and proxy-relevant diagnostics", () => {
+  const commands = buildBaseCaptureCommands({
+    projectRoot: "/tmp/demo",
+    logWindow: "45m",
+  });
+
+  expect(commands.map((command) => command.name)).toEqual(
+    expect.arrayContaining([
+      "hack_doctor_project",
+      "hack_global_status",
+      "hack_daemon_logs",
+      "docker_network_inspect_hack-dev",
+      "docker_network_inspect_hack-logging",
+    ])
+  );
+
+  const processSnapshot = commands.find(
+    (command) => command.name === "ps_orbstack_processes"
+  );
+  expect(processSnapshot?.cmd.join(" ")).not.toContain("rg ");
+});
+
+test("crash capture summary reports failures and ordered next steps", () => {
+  const summary = buildCrashCaptureSummary({
+    captureRoot: "/tmp/demo/.tmp/crash-capture-1",
+    projectRoot: "/tmp/demo",
+    results: [
+      {
+        name: "hack_doctor_project",
+        cmd: ["hack", "doctor", "--path", "/tmp/demo"],
+        exitCode: 1,
+        file: "/tmp/demo/.tmp/crash-capture-1/hack_doctor_project.log",
+        bytes: 120,
+      },
+      {
+        name: "hack_global_status",
+        cmd: ["hack", "global", "status", "--json"],
+        exitCode: 0,
+        file: "/tmp/demo/.tmp/crash-capture-1/hack_global_status.log",
+        bytes: 80,
+      },
+    ],
+    errors: ["hack_doctor_project failed (1)"],
+  });
+
+  expect(summary.commandCount).toBe(2);
+  expect(summary.failureCount).toBe(1);
+  expect(summary.failedCommands).toEqual(["hack_doctor_project"]);
+  expect(summary.nextSteps).toEqual([
+    "Run `hack doctor --path /tmp/demo` to classify restart versus repair work.",
+    "If global proxy/runtime is down, run `hack global up`.",
+    "If project host mappings are stale, run `hack restart --path /tmp/demo`.",
+    "If doctor reports DNS/network/CA drift, run `hack doctor --fix --path /tmp/demo`.",
+  ]);
+});
+
+test("crash capture readme points operators to the summary and raw logs", () => {
+  const text = renderCrashCaptureReadme({
+    captureRoot: "/tmp/demo/.tmp/crash-capture-1",
+    projectRoot: "/tmp/demo",
+    failedCommands: ["hack_doctor_project", "hack_daemon_logs"],
+  });
+
+  expect(text).toContain("Crash capture bundle");
+  expect(text).toContain("summary.json");
+  expect(text).toContain("commands.json");
+  expect(text).toContain("hack_doctor_project");
+  expect(text).toContain("hack_daemon_logs");
+  expect(text).toContain("hack doctor --path /tmp/demo");
+});
diff --git a/tests/doctor-command.test.ts b/tests/doctor-command.test.ts
new file mode 100644
index 000000000..bc9d8aa66
--- /dev/null
+++ b/tests/doctor-command.test.ts
@@ -0,0 +1,69 @@
+import { expect, test } from "bun:test";
+
+import { buildDoctorRecoveryGuidance } from "../src/commands/recovery-guidance.ts";
+
+test("doctor guidance distinguishes restartable proxy drift from deeper repair", () => {
+  const guidance = buildDoctorRecoveryGuidance({
+    results: [
+      {
+        name: "proxy ports",
+        status: "warn",
+        message: "Caddy not reachable (run: hack global up)",
+      },
+      {
+        name: "caddy hosts",
+        status: "warn",
+        message: "No internal extra_hosts mapping found (run: hack restart)",
+      },
+      {
+        name: "coredns forwarding",
+        status: "warn",
+        message: "SERVFAIL (run: hack doctor --fix)",
+      },
+    ],
+  });
+
+  expect(guidance.temporaryBreakage).toEqual([
+    "hack global up",
+    "hack restart",
+  ]);
+  expect(guidance.configurationRepair).toEqual(["hack doctor --fix"]);
+  expect(guidance.verify).toEqual(["hack doctor"]);
+  expect(guidance.capture).toEqual(["hack crash-capture --path <repo>"]);
+});
+
+test("doctor guidance includes daemon recovery for stale local api state", () => {
+  const guidance = buildDoctorRecoveryGuidance({
+    results: [
+      {
+        name: "daemon",
+        status: "warn",
+        message: "hackd not running (stale pid/socket; run: hack daemon clear)",
+      },
+    ],
+  });
+
+  expect(guidance.temporaryBreakage).toEqual([
+    "hack daemon clear",
+    "hack daemon start",
+  ]);
+  expect(guidance.configurationRepair).toEqual([]);
+});
+
+test("doctor guidance keeps unmatched failures as follow-up instead of guessing", () => {
+  const guidance = buildDoctorRecoveryGuidance({
+    results: [
+      {
+        name: "gateway tokens",
+        status: "warn",
+        message: "No active tokens (run: hack x gateway token-create)",
+      },
+    ],
+  });
+
+  expect(guidance.temporaryBreakage).toEqual([]);
+  expect(guidance.configurationRepair).toEqual([]);
+  expect(guidance.followUp).toEqual([
+    "gateway tokens: No active tokens (run: hack x gateway token-create)",
+  ]);
+});

From a0f4e4aed71f0571c4dc607a32ab3be7b8107573 Mon Sep 17 00:00:00 2001
From: Symphony <symphony@hack>
Date: Sat, 14 Mar 2026 04:21:19 +0000
Subject: [PATCH 026/134] docs(tickets): format projection docs

---
 ...3-14-hack-tickets-sqlite-journal-design.md | 64 +++++++++++++++++++
 ...-03-14-hack-tickets-sqlite-journal-plan.md | 54 ++++++++++------
 2 files changed, 98 insertions(+), 20 deletions(-)

diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
index 0aadc0891..3602288ce 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
@@ -1,15 +1,18 @@
 # Hack Tickets SQLite Projection And Journal Design
 
 ## Goal
+
 Define a durable local storage architecture for Hack Tickets that keeps the git-backed JSONL journal as the canonical, portable source of truth while adding a deterministic SQLite projection for fast reads, sync queries, and repeated replay.
 
 ## Current Foundation
+
 - Ticket history is stored as append-only monthly JSONL segments in `.hack/tickets/events/events-YYYY-MM.jsonl`.
 - The tickets ref is transported through git, so the system already has good offline and multi-machine portability.
 - Reads currently parse the full journal and materialize ticket state in memory on demand.
 - Sync-oriented reads such as external id lookup, conflict lookup, and checkpoint lookup are derived by replaying every event.
 
 ## Design Summary
+
 - Keep the JSONL journal in the tickets git ref as the only portable source of truth.
 - Add a local SQLite database as a projection and replay index, not as a second authority.
 - Make replay idempotent by event identity first and deterministic by a total ordering key second.
@@ -17,27 +20,36 @@ Define a durable local storage architecture for Hack Tickets that keeps the git-
 - Treat recovery as a normal path: if the projection is missing, stale, corrupted, or on an old schema, rebuild it from the journal.
 
 ## Non-Goals
+
 - Do not replace the git-backed journal with SQLite.
 - Do not require SQLite files to sync through git.
 - Do not introduce mutable event updates, event compaction that changes meaning, or snapshot files that become a new source of truth.
 - Do not redesign ticket semantics beyond what is needed for deterministic replay and indexed reads.
 
 ## Alternatives Considered
+
 ### Recommended: journal as source of truth, SQLite as local projection
+
 This keeps portability and inspectability in git while solving the current replay cost for reads and sync. It also gives a clean recovery story because the projection is disposable.
 
 ### Rejected: SQLite as the primary store with git export/import
+
 This would improve local read performance, but it would weaken the current portability model and create a second system boundary around export timing, merge semantics, and operational recovery.
 
 ### Rejected: keep pure JSONL replay and optimize the in-memory materializer
+
 This avoids a new storage layer, but it does not materially improve cold-start reads, repeated sync scans, or future richer queries such as open conflicts by provider or external id lookup.
 
 ## Storage Layout
+
 ### Canonical journal
+
 Keep the existing git-backed journal layout inside the tickets ref worktree:
+
 - `.hack/tickets/events/events-YYYY-MM.jsonl`
 
 Each line remains one immutable event envelope:
+
 - `eventId`
 - `ts`
 - `tsIso`
@@ -50,32 +62,42 @@ Each line remains one immutable event envelope:
 - `payload`
 
 ### Local-only projection
+
 Add a local SQLite file outside the synced tickets worktree:
+
 - `.hack/tickets/state/projection.sqlite`
 
 Companion files that are safe to delete:
+
 - `.hack/tickets/state/projection.sqlite-shm`
 - `.hack/tickets/state/projection.sqlite-wal`
 
 This directory should stay local-only and be ignored by both the main repo and the tickets ref.
 
 ## Journal Semantics
+
 ### Source of truth
+
 The journal is authoritative. SQLite is derived state. If the two disagree, the journal wins and the projection must be rebuilt or repaired.
 
 ### Append-only rule
+
 Published events are immutable. The only allowed rewrite is semantic-preserving normalization during sync:
+
 - remove duplicate lines with the same `eventId`
 - keep exactly one payload for a given `eventId`
 - rewrite segment ordering into the canonical replay order
 
 ### Event identity
+
 `eventId` is the logical identity of an event across machines. Reapplying the same `eventId` is a no-op if the payload hash matches.
 
 If the same `eventId` appears with different content, that is corruption, not conflict. Replay must stop and report the bad event ids instead of guessing.
 
 ### Canonical replay order
+
 Replay uses this total order:
+
 1. `ts` ascending
 2. `orderKey` ascending when present
 3. `eventId` ascending
@@ -83,19 +105,25 @@ Replay uses this total order:
 This order is deterministic across machines and rebuilds, even when segment files were merged from multiple writers. Segment filename and line number are recorded for diagnostics and incremental scanning, but they are not part of domain ordering.
 
 ### Idempotency rule
+
 Applying an event more than once must have the same effect as applying it once.
 
 The projection enforces this by inserting the event envelope into `journal_events` first. If the insert conflicts on `event_id`, replay compares the stored payload hash:
+
 - same hash: skip as already applied
 - different hash: stop replay and mark the projection unhealthy
 
 ## SQLite Projection Schema
+
 ### Projection metadata
+
 `projection_meta`
+
 - `key TEXT PRIMARY KEY`
 - `value TEXT NOT NULL`
 
 Required keys:
+
 - `schema_version`
 - `journal_format_version`
 - `projection_status` with values `ready` or `rebuilding`
@@ -105,7 +133,9 @@ Required keys:
 - `last_replayed_at`
 
 ### Replay index
+
 `journal_events`
+
 - `event_id TEXT PRIMARY KEY`
 - `ticket_id TEXT NOT NULL`
 - `ts INTEGER NOT NULL`
@@ -122,6 +152,7 @@ Required keys:
 - `applied_at TEXT NOT NULL`
 
 Indexes:
+
 - `journal_events_ticket_order_idx (ticket_id, ts, order_key, event_id)`
 - `journal_events_type_idx (type, ts, event_id)`
 - `journal_events_project_idx (project_id, ts, event_id)`
@@ -129,7 +160,9 @@ Indexes:
 This table is the durable idempotency fence and powers fast `show` queries without reparsing JSONL.
 
 ### Ticket projection
+
 `tickets`
+
 - `ticket_id TEXT PRIMARY KEY`
 - `title TEXT NOT NULL`
 - `body TEXT`
@@ -151,34 +184,42 @@ This table is the durable idempotency fence and powers fast `show` queries witho
 - `last_event_id TEXT NOT NULL`
 
 Indexes:
+
 - `tickets_status_updated_idx (status, updated_at DESC)`
 - `tickets_project_updated_idx (project_id, updated_at DESC)`
 - `tickets_external_lookup_idx (external_system, external_id)`
 - `tickets_source_status_idx (source, status, updated_at DESC)`
 
 ### Multi-value projections
+
 `ticket_dependencies`
+
 - `ticket_id TEXT NOT NULL`
 - `depends_on_ticket_id TEXT NOT NULL`
 - `PRIMARY KEY (ticket_id, depends_on_ticket_id)`
 
 `ticket_blocks`
+
 - `ticket_id TEXT NOT NULL`
 - `blocks_ticket_id TEXT NOT NULL`
 - `PRIMARY KEY (ticket_id, blocks_ticket_id)`
 
 `ticket_tags`
+
 - `ticket_id TEXT NOT NULL`
 - `tag TEXT NOT NULL`
 - `PRIMARY KEY (ticket_id, tag)`
 
 Indexes:
+
 - `ticket_dependencies_depends_idx (depends_on_ticket_id, ticket_id)`
 - `ticket_blocks_blocks_idx (blocks_ticket_id, ticket_id)`
 - `ticket_tags_tag_idx (tag, ticket_id)`
 
 ### Append-only child entities
+
 `ticket_comments`
+
 - `comment_id TEXT PRIMARY KEY`
 - `ticket_id TEXT NOT NULL`
 - `body TEXT NOT NULL`
@@ -190,6 +231,7 @@ Indexes:
 - `last_event_id TEXT NOT NULL`
 
 `ticket_review_notes`
+
 - `note_id TEXT PRIMARY KEY`
 - `ticket_id TEXT NOT NULL`
 - `body TEXT NOT NULL`
@@ -199,6 +241,7 @@ Indexes:
 - `last_event_id TEXT NOT NULL`
 
 `ticket_sync_checkpoints`
+
 - `checkpoint_id TEXT PRIMARY KEY`
 - `ticket_id TEXT NOT NULL`
 - `provider TEXT NOT NULL`
@@ -212,6 +255,7 @@ Indexes:
 - `last_event_id TEXT NOT NULL`
 
 `ticket_sync_conflicts`
+
 - `conflict_id TEXT PRIMARY KEY`
 - `ticket_id TEXT NOT NULL`
 - `provider TEXT NOT NULL`
@@ -230,6 +274,7 @@ Indexes:
 - `last_event_id TEXT NOT NULL`
 
 Indexes:
+
 - `ticket_comments_ticket_created_idx (ticket_id, created_at, comment_id)`
 - `ticket_review_notes_ticket_created_idx (ticket_id, created_at, note_id)`
 - `ticket_sync_checkpoints_lookup_idx (ticket_id, provider, profile_id, created_at DESC)`
@@ -237,14 +282,18 @@ Indexes:
 - `ticket_sync_conflicts_ticket_idx (ticket_id, updated_at DESC)`
 
 ## Replay Rules
+
 ### Startup path
+
 1. Open SQLite in WAL mode.
 2. Read `projection_meta`.
 3. If the file is missing, schema version is wrong, status is `rebuilding`, or SQLite reports corruption, delete and rebuild.
 4. Otherwise scan journal segments for new or changed lines after the last applied sort key.
 
 ### Incremental replay
+
 For each journal line in canonical order:
+
 1. Parse and validate the event envelope.
 2. Start a transaction.
 3. Insert into `journal_events`.
@@ -256,6 +305,7 @@ For each journal line in canonical order:
 This keeps replay crash-safe and allows progress to resume from the last committed event.
 
 ### Event application rules
+
 - `ticket.created`: insert a row into `tickets`, replace dependency/block/tag sets from payload, set `created_at` and `updated_at` from the event timestamp.
 - `ticket.updated`: patch only provided fields, replace dependency/block/tag sets only when they appear in payload, set `updated_at`.
 - `ticket.status_changed`: update `status` and `updated_at`.
@@ -269,8 +319,11 @@ This keeps replay crash-safe and allows progress to resume from the last committ
 If an event references missing local state that should already exist, replay stops with a projection error instead of silently inventing rows.
 
 ## Rebuild And Recovery
+
 ### Full rebuild
+
 Full rebuild is deterministic:
+
 1. Delete or move aside the SQLite file.
 2. Recreate schema.
 3. Mark `projection_status = rebuilding`.
@@ -280,7 +333,9 @@ Full rebuild is deterministic:
 Given the same journal bytes, rebuild produces the same projection rows and indexes every time.
 
 ### Crash recovery
+
 Crash recovery relies on SQLite transactions and WAL:
+
 - a half-applied event rolls back automatically
 - committed events remain durable
 - the replay cursor only advances in the same transaction as the projection updates
@@ -288,12 +343,15 @@ Crash recovery relies on SQLite transactions and WAL:
 If the process dies mid-rebuild, the next startup sees `projection_status = rebuilding` and starts a clean rebuild rather than trusting partial state.
 
 ### Corruption recovery
+
 Recoverable failures:
+
 - missing SQLite file
 - outdated projection schema
 - WAL or database corruption
 
 Unrecoverable without operator action:
+
 - malformed JSONL that cannot be parsed
 - duplicate `eventId` with different payload hashes
 - event references to impossible prior state caused by journal corruption
@@ -301,7 +359,9 @@ Unrecoverable without operator action:
 In recoverable cases, automatically rebuild. In unrecoverable cases, surface a hard error with the offending segment and line number.
 
 ## Sync And Query Benefits
+
 The projection specifically accelerates:
+
 - `tickets list` by reading `tickets` plus indexed filters
 - `tickets show` by reading one ticket and its child tables
 - external sync lookup by `external_system` and `external_id`
@@ -310,17 +370,20 @@ The projection specifically accelerates:
 - repeated daemon or autosync loops that need to ask “what changed since cursor X?”
 
 ## Multi-Machine Behavior
+
 - Multiple machines can append semantically equivalent journals and later merge through git.
 - Normalization merges by `eventId` union, not by trusting file order.
 - Projection replay is safe after repeated fetch, merge, or sync because duplicate events are idempotent.
 - Because SQLite is local-only, machines never need to coordinate projection files. They only need the same journal bytes.
 
 ## Implementation Notes
+
 - Use `bun:sqlite` for the projection layer.
 - Keep journal parsing and replay in one module so rebuild and incremental apply share the same code path.
 - Expose a small health surface later, for example `tickets inspect` or `tickets rebuild`, but keep those commands out of this design’s critical path.
 
 ## Validation
+
 - Rebuilding from the same journal twice yields byte-equivalent query results.
 - Reapplying the same merged journal does not duplicate comments, checkpoints, or conflicts.
 - Deleting the SQLite file does not lose ticket history.
@@ -328,4 +391,5 @@ The projection specifically accelerates:
 - Duplicate `eventId` with mismatched payload is detected as corruption.
 
 ## Recommendation
+
 Implement the projection as a local SQLite cache with `journal_events` as the idempotent replay fence and the `tickets` plus child tables as the read model. This gives deterministic rebuilds, fast reads, and safe repeated event application without weakening the current git-portable journal architecture.
diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
index 4759c4f55..356f9efbb 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
@@ -13,19 +13,20 @@
 ### Task 1: Lock The Projection Contract In Tests
 
 **Files:**
+
 - Create: `tests/tickets-projection.test.ts`
 - Modify: `tests/tickets-store.test.ts`
 
 **Step 1: Write failing projection tests**
+
 - Add a test that rebuilds from a fixed journal and asserts ticket, comment, checkpoint, and conflict rows are present in the projection.
 - Add a test that replays the same event stream twice and asserts child rows are not duplicated.
 - Add a test that feeds the same `eventId` with different payloads and asserts replay fails with a corruption error.
 
-**Step 2: Run focused tests to verify failure**
-Run: `bun test tests/tickets-projection.test.ts tests/tickets-store.test.ts`
-Expected: FAIL because no projection module or corruption checks exist yet.
+**Step 2: Run focused tests to verify failure** Run: `bun test tests/tickets-projection.test.ts tests/tickets-store.test.ts` Expected: FAIL because no projection module or corruption checks exist yet.
 
 **Step 3: Commit**
+
 ```bash
 git add tests/tickets-projection.test.ts tests/tickets-store.test.ts
 git commit -m "test(tickets): define projection replay contract"
@@ -34,11 +35,13 @@ git commit -m "test(tickets): define projection replay contract"
 ### Task 2: Add SQLite Schema And Projection Metadata
 
 **Files:**
+
 - Create: `src/control-plane/extensions/tickets/projection.ts`
 - Modify: `src/control-plane/extensions/tickets/store.ts`
 - Test: `tests/tickets-projection.test.ts`
 
 **Step 1: Write the minimal schema bootstrap**
+
 - Create schema helpers for:
   - `projection_meta`
   - `journal_events`
@@ -52,14 +55,14 @@ git commit -m "test(tickets): define projection replay contract"
   - `ticket_sync_conflicts`
 
 **Step 2: Wire projection path resolution**
+
 - Resolve the database path under `.hack/tickets/state/projection.sqlite`.
 - Ensure the state directory exists without placing the SQLite file inside the synced tickets worktree.
 
-**Step 3: Run focused tests**
-Run: `bun test tests/tickets-projection.test.ts`
-Expected: FAIL only on replay behavior, not missing schema setup.
+**Step 3: Run focused tests** Run: `bun test tests/tickets-projection.test.ts` Expected: FAIL only on replay behavior, not missing schema setup.
 
 **Step 4: Commit**
+
 ```bash
 git add src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts
 git commit -m "feat(tickets): add projection schema bootstrap"
@@ -68,16 +71,19 @@ git commit -m "feat(tickets): add projection schema bootstrap"
 ### Task 3: Implement Deterministic Replay And Idempotent Apply
 
 **Files:**
+
 - Modify: `src/control-plane/extensions/tickets/projection.ts`
 - Modify: `src/control-plane/extensions/tickets/store.ts`
 - Test: `tests/tickets-projection.test.ts`
 
 **Step 1: Write the replay engine**
+
 - Parse journal files in canonical order by `ts`, `orderKey`, `eventId`.
 - Insert each event into `journal_events` before mutating read tables.
 - Compare payload hashes on duplicate `eventId`.
 
 **Step 2: Implement event appliers**
+
 - `ticket.created`
 - `ticket.updated`
 - `ticket.status_changed`
@@ -88,11 +94,10 @@ git commit -m "feat(tickets): add projection schema bootstrap"
 - `ticket.sync_conflict_recorded`
 - `ticket.sync_conflict_resolved`
 
-**Step 3: Run focused tests**
-Run: `bun test tests/tickets-projection.test.ts`
-Expected: PASS
+**Step 3: Run focused tests** Run: `bun test tests/tickets-projection.test.ts` Expected: PASS
 
 **Step 4: Commit**
+
 ```bash
 git add src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts tests/tickets-projection.test.ts
 git commit -m "feat(tickets): replay journal into sqlite projection"
@@ -101,12 +106,14 @@ git commit -m "feat(tickets): replay journal into sqlite projection"
 ### Task 4: Route Reads Through The Projection With Journal Fallback
 
 **Files:**
+
 - Modify: `src/control-plane/extensions/tickets/store.ts`
 - Modify: `src/control-plane/extensions/tickets/commands.ts`
 - Test: `tests/tickets-store.test.ts`
 - Test: `tests/tickets-extension.test.ts`
 
 **Step 1: Change store read paths**
+
 - `listTickets`
 - `getTicket`
 - `listEvents`
@@ -116,14 +123,14 @@ git commit -m "feat(tickets): replay journal into sqlite projection"
 These reads should prefer SQLite and only trigger replay or rebuild when projection state is missing or stale.
 
 **Step 2: Preserve write path semantics**
+
 - Keep event append writing to JSONL through the existing git channel.
 - After append success, replay only the new events into SQLite instead of reparsing the entire journal.
 
-**Step 3: Run focused tests**
-Run: `bun test tests/tickets-store.test.ts tests/tickets-extension.test.ts`
-Expected: PASS
+**Step 3: Run focused tests** Run: `bun test tests/tickets-store.test.ts tests/tickets-extension.test.ts` Expected: PASS
 
 **Step 4: Commit**
+
 ```bash
 git add src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/commands.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts
 git commit -m "feat(tickets): serve reads from sqlite projection"
@@ -132,26 +139,28 @@ git commit -m "feat(tickets): serve reads from sqlite projection"
 ### Task 5: Add Rebuild And Health Recovery Paths
 
 **Files:**
+
 - Modify: `src/control-plane/extensions/tickets/projection.ts`
 - Modify: `src/control-plane/extensions/tickets/store.ts`
 - Modify: `src/control-plane/extensions/tickets/commands.ts`
 - Test: `tests/tickets-projection.test.ts`
 
 **Step 1: Add rebuild triggers**
+
 - missing database
 - schema version mismatch
 - `projection_status = rebuilding`
 - SQLite open failure or corruption
 
 **Step 2: Add an explicit rebuild entry point**
+
 - internal store method first
 - optional CLI surface only if needed for debugging, for example `hack tickets rebuild`
 
-**Step 3: Run focused tests**
-Run: `bun test tests/tickets-projection.test.ts tests/tickets-store.test.ts`
-Expected: PASS
+**Step 3: Run focused tests** Run: `bun test tests/tickets-projection.test.ts tests/tickets-store.test.ts` Expected: PASS
 
 **Step 4: Commit**
+
 ```bash
 git add src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/commands.ts tests/tickets-projection.test.ts tests/tickets-store.test.ts
 git commit -m "feat(tickets): add projection rebuild recovery"
@@ -160,19 +169,20 @@ git commit -m "feat(tickets): add projection rebuild recovery"
 ### Task 6: Verify Git Sync Interop And Repeated Application
 
 **Files:**
+
 - Modify: `tests/tickets-git-channel.test.ts`
 - Modify: `tests/tickets-extension.test.ts`
 
 **Step 1: Add integration coverage**
+
 - sync remote journal content into a local clone
 - replay merged logs with duplicate events
 - confirm projection rows remain correct after repeated sync
 
-**Step 2: Run focused tests**
-Run: `bun test tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts`
-Expected: PASS
+**Step 2: Run focused tests** Run: `bun test tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts` Expected: PASS
 
 **Step 3: Commit**
+
 ```bash
 git add tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts
 git commit -m "test(tickets): verify projection sync idempotency"
@@ -181,23 +191,27 @@ git commit -m "test(tickets): verify projection sync idempotency"
 ### Task 7: Run Quality Gates And Final Documentation Pass
 
 **Files:**
+
 - Modify: `docs/guides/tickets.md`
 - Modify: `docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md` if implementation changed details
 - Modify: `docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md` if execution changed steps
 
 **Step 1: Document the new local state layout**
+
 - Describe the projection database as local-only and rebuildable.
 - Document any new CLI rebuild or inspect command if added.
 
-**Step 2: Run repo quality gates**
-Run:
+**Step 2: Run repo quality gates** Run:
+
 ```bash
 bun test tests/tickets-projection.test.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts tests/tickets-git-channel.test.ts
 bun run check
 ```
+
 Expected: PASS
 
 **Step 3: Commit**
+
 ```bash
 git add docs/guides/tickets.md docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md tests/tickets-projection.test.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts tests/tickets-git-channel.test.ts src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/commands.ts
 git commit -m "feat(tickets): finish sqlite projection architecture"

From cc8a606288d46d9706f512f97e34bc846b240fb8 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:22:16 +0000
Subject: [PATCH 027/134] feat(session): clarify workspace semantics and tmux
 onboarding

---
 AGENTS.md                     |  14 +-
 CLAUDE.md                     |  14 +-
 docs/README.md                |   2 +-
 docs/cli.md                   |  62 ++-
 docs/gateway-api.md           |  12 +-
 docs/sessions.md              | 142 ++++---
 src/agents/codex-skill.ts     |  16 +-
 src/commands/session.ts       | 737 ++++++++++++++++++++++------------
 src/commands/setup.ts         |   8 +-
 src/commands/ssh.ts           |  40 +-
 src/lib/project-views.ts      |  13 +-
 src/mcp/agent-docs.ts         |  14 +-
 tests/project-views.test.ts   |   8 +-
 tests/session-command.test.ts |  63 +++
 tests/session-help.test.ts    |  48 +++
 tests/session-names.test.ts   |  26 ++
 16 files changed, 829 insertions(+), 390 deletions(-)
 create mode 100644 tests/session-command.test.ts
 create mode 100644 tests/session-help.test.ts
 create mode 100644 tests/session-names.test.ts

diff --git a/AGENTS.md b/AGENTS.md
index 141a51dc5..2865c3736 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -202,7 +202,7 @@ Most formatting and common issues are automatically fixed by Biome. Run `bun x u
 <!-- hack:agent-docs:start -->
 ## hack CLI (local dev + MCP)
 
-Use `hack` as the single interface for local runtime orchestration (compose, DNS/TLS, logs, sessions).
+Use `hack` as the single interface for local runtime orchestration (compose, DNS/TLS, logs, persistent project workspaces).
 
 Operating rules:
 - Prefer `hack` over raw `docker` / `docker compose` for project workflows.
@@ -270,12 +270,12 @@ Lifecycle + startup:
 - Use `lifecycle.up.before` for pre-start hooks and `lifecycle.processes` for long-running host tasks.
 - Inspect lifecycle status via `hack projects --details` and stream via `hack logs <service-or-process>`.
 
-Sessions (mux-managed):
-- Picker: `hack session`
-- Start/attach: `hack session start <project>`
-- Force isolated agent session: `hack session start <project> --new --name agent-1`
-- Execute in session: `hack session exec <session> "<command>"`
-- Stop session: `hack session stop <session>`
+Workspaces (mux-managed):
+- Picker: `hack session` for persistent project workspaces.
+- Reuse/create: `hack session start <project>`
+- Force isolated agent workspace: `hack session start <project> --new --name agent-1` (`<project>--agent-1`).
+- Execute in workspace: `hack session exec <workspace> "<command>"`
+- Stop workspace: `hack session stop <workspace>`
 
 Tickets (git-backed):
 - Create: `hack tickets create --title "..." --body-stdin`
diff --git a/CLAUDE.md b/CLAUDE.md
index 5387e89bc..dc08202fa 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -97,7 +97,7 @@ This project uses Obsidian for project context, specs, research, and progress tr
 <!-- hack:agent-docs:start -->
 ## hack CLI (local dev + MCP)
 
-Use `hack` as the single interface for local runtime orchestration (compose, DNS/TLS, logs, sessions).
+Use `hack` as the single interface for local runtime orchestration (compose, DNS/TLS, logs, persistent project workspaces).
 
 Operating rules:
 - Prefer `hack` over raw `docker` / `docker compose` for project workflows.
@@ -165,12 +165,12 @@ Lifecycle + startup:
 - Use `lifecycle.up.before` for pre-start hooks and `lifecycle.processes` for long-running host tasks.
 - Inspect lifecycle status via `hack projects --details` and stream via `hack logs <service-or-process>`.
 
-Sessions (mux-managed):
-- Picker: `hack session`
-- Start/attach: `hack session start <project>`
-- Force isolated agent session: `hack session start <project> --new --name agent-1`
-- Execute in session: `hack session exec <session> "<command>"`
-- Stop session: `hack session stop <session>`
+Workspaces (mux-managed):
+- Picker: `hack session` for persistent project workspaces.
+- Reuse/create: `hack session start <project>`
+- Force isolated agent workspace: `hack session start <project> --new --name agent-1` (`<project>--agent-1`).
+- Execute in workspace: `hack session exec <workspace> "<command>"`
+- Stop workspace: `hack session stop <workspace>`
 
 Tickets (git-backed):
 - Create: `hack tickets create --title "..." --body-stdin`
diff --git a/docs/README.md b/docs/README.md
index e493be242..3cccbb46c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -6,7 +6,7 @@ This directory contains the public documentation for hack. Specs remain in `SPEC
 
 - [CLI reference](cli.md)
 - [Architecture](architecture.md)
-- [Sessions](sessions.md) - mux session management (tmux or zellij) + API
+- [Sessions](sessions.md) - persistent project workspaces with tmux-first onboarding + API
 - [Env & secrets](env.md) - env contract + `.hack/.env` + OS keychain secrets
 - [Lifecycle](lifecycle.md) - project startup hooks + managed host processes
 - [Gateway overview](gateway.md)
diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..294260e40 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -31,7 +31,7 @@ Run `hack help` or `hack help <command>` for interactive help.
 | `hack linear` | Linear account connection and ticket sync | Project |
 | `hack config` | Read/write hack.config.json values | Project |
 | `hack env` | Manage project environment variables and secrets | Project |
-| `hack session` | Manage terminal sessions for hack projects | Project |
+| `hack session` | Manage persistent project workspaces with tmux-first onboarding | Project |
 | `hack ssh` | Show SSH connection info for remote access | Project |
 | `hack tickets` | Git-backed ticket management | Project |
 | `hack internal` | Manage hack-managed internal overrides | Internal |
@@ -563,35 +563,53 @@ Options:
 Usage: `hack session [subcommand]`
 
 With no subcommand, opens an interactive picker of active sessions and available projects.
+Sessions keep a project workspace alive across terminal restarts, SSH reconnects, and long-running agent work.
+The guided default is tmux, including `hack setup tmux` for a popup picker. Other mux backends such as zellij remain configurable through `sessions.mux`, but the interactive session flow is tmux-first today.
 
 Subcommands:
 
 | Subcommand | Summary |
 | --- | --- |
-| `list` | List active sessions |
-| `start` | Start or attach to a session for a project |
-| `stop` | Stop (kill) a session |
-| `attach` | Attach to an existing session |
-| `exec` | Execute a command in a session |
-| `panes` | List panes in a tmux session |
-| `capture` | Capture recent output from a tmux session |
-| `tail` | Tail output from a tmux session |
+| `list` | List active tmux workspaces |
+| `start` | Reuse the default project workspace or create an isolated one |
+| `stop` | Stop a tmux-backed workspace |
+| `attach` | Attach to an existing workspace |
+| `exec` | Send a command to a running workspace |
+| `panes` | List panes in a tmux workspace |
+| `capture` | Capture recent output from a tmux workspace |
+| `tail` | Tail output from a tmux workspace |
 
 #### hack session start
 
 Usage: `hack session start [project] [options]`
 
+Reuse the default project workspace when it already exists, or create an isolated long-running workspace with `--new` or `--name`.
+Use `--detach` when another tool should keep the workspace alive without attaching your terminal.
+
 Options:
 
 | Flag | Type | Default | Description |
 | --- | --- | --- | --- |
-| `--up` | boolean | false | Run hack up -d before attaching |
-| `--new` | boolean | false | Force create new session even if one exists |
-| `--name <suffix>` | string | - | Custom suffix for new session (e.g., agent-1) |
+| `--up` | boolean | false | Run hack up -d before creating or attaching |
+| `--new` | boolean | false | Create an isolated workspace instead of reusing the default project workspace |
+| `--name <suffix>` | string | - | Suffix for an isolated workspace name (for example: agent-1 -> project--agent-1) |
+| `--detach`, `-d` | boolean | false | Create or reuse the workspace without attaching (for GUI/non-TTY use) |
+
+#### hack session attach
+
+Usage: `hack session attach <workspace>`
+
+Attach to a running tmux workspace by name. When you are already inside tmux, hack switches clients instead of nesting tmux inside tmux.
+
+#### hack session exec
+
+Usage: `hack session exec <workspace> <command>`
+
+Queue a command in the workspace's active pane without opening a new shell. This is useful for long-running agents, background checks, or remote follow-up work.
 
 #### hack session panes
 
-Usage: `hack session panes <session> [options]`
+Usage: `hack session panes <workspace> [options]`
 
 Options:
 
@@ -602,7 +620,7 @@ Options:
 
 #### hack session capture
 
-Usage: `hack session capture <session> [options]`
+Usage: `hack session capture <workspace> [options]`
 
 Options:
 
@@ -615,7 +633,7 @@ Options:
 
 #### hack session tail
 
-Usage: `hack session tail <session> [options]`
+Usage: `hack session tail <workspace> [options]`
 
 Options:
 
@@ -630,7 +648,7 @@ Options:
 
 ### hack ssh
 
-Usage: `hack ssh [session] [options]`
+Usage: `hack ssh [workspace] [options]`
 
 Options:
 
@@ -1061,6 +1079,7 @@ Subcommands:
 
 | Subcommand | Summary |
 | --- | --- |
+| `tmux` | Install the recommended tmux binding for hack workspaces |
 | `cursor` | Install Cursor rules for hack CLI usage |
 | `claude` | Install Claude Code hooks for hack CLI usage |
 | `codex` | Install Codex skill for hack CLI usage |
@@ -1069,6 +1088,17 @@ Subcommands:
 | `sync` | Refresh agent docs, skills, and MCP configs |
 | `mcp` | Install MCP configs for hack CLI usage (no-shell only) |
 
+#### hack setup tmux
+
+Usage: `hack setup tmux [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
+
 #### hack setup cursor
 
 Usage: `hack setup cursor [options]`
diff --git a/docs/gateway-api.md b/docs/gateway-api.md
index bbe4cd563..0e626e9d6 100644
--- a/docs/gateway-api.md
+++ b/docs/gateway-api.md
@@ -204,11 +204,11 @@ Base URL: `http://127.0.0.1:7788` (or your tunnel URL)
 | GET | `/v1/metrics` | no | Cache + stream metrics |
 | GET | `/v1/projects` | no | Gateway-enabled projects + runtime snapshot |
 | GET | `/v1/ps` | no | Compose project container list |
-| GET | `/v1/sessions` | no | List mux sessions (tmux/zellij) |
-| POST | `/v1/sessions` | yes | Create mux session |
-| GET | `/v1/sessions/:id` | no | Get session details |
-| POST | `/v1/sessions/:id/stop` | yes | Stop (kill) session |
-| POST | `/v1/sessions/:id/exec` | yes | Execute command in session |
+| GET | `/v1/sessions` | no | List persistent tmux-backed workspaces |
+| POST | `/v1/sessions` | yes | Create persistent tmux-backed workspace |
+| GET | `/v1/sessions/:id` | no | Get workspace details |
+| POST | `/v1/sessions/:id/stop` | yes | Stop (kill) workspace |
+| POST | `/v1/sessions/:id/exec` | yes | Execute command in workspace |
 | POST | `/v1/sessions/:id/input` | yes | Send raw keystrokes |
 | GET | `/v1/env` | no | Env contract + resolution state (values redacted) |
 | POST | `/v1/env/set` | yes | Set env (.hack/.env) or secret (keychain) |
@@ -222,7 +222,7 @@ Base URL: `http://127.0.0.1:7788` (or your tunnel URL)
 | GET | `/control-plane/projects/:projectId/shells/:shellId` | no | Fetch shell |
 | WS | `/control-plane/projects/:projectId/shells/:shellId/stream` | yes | Stream shell PTY |
 
-> **Sessions API**: For detailed sessions endpoint documentation, see [Sessions](sessions.md#daemon-sessions-api).
+> **Sessions API**: For detailed persistent workspace endpoint documentation, see [Sessions](sessions.md#daemon-sessions-api).
 >
 > **Env API**: For contract format and env endpoints, see [Env & secrets](env.md#daemongateway-api-ui-integration).
 
diff --git a/docs/sessions.md b/docs/sessions.md
index 0166be16f..852463298 100644
--- a/docs/sessions.md
+++ b/docs/sessions.md
@@ -1,93 +1,109 @@
 # Sessions
 
-Sessions provide a way to manage persistent terminal workspaces using **tmux** or **zellij**. They're designed for:
-- **Remote access**: SSH into your machine and attach to an existing workspace
-- **Agent execution**: Run long-running agents in isolated sessions
-- **Multi-terminal workflows**: Keep multiple project contexts alive across sessions
+Sessions are **persistent project workspaces**. They keep a repo-root shell alive across terminal restarts, SSH reconnects, and long-running agent work so you can return to the same context instead of rebuilding it each time.
+
+The guided default is **tmux**:
+- `hack session` opens a tmux-first interactive picker
+- `hack session start <project>` reuses the default project workspace unless you ask for an isolated one
+- `hack setup tmux` installs the recommended popup binding so the picker is easy to reach from tmux
+
+Other mux backends still exist. `sessions.mux=auto` prefers tmux and falls back to zellij when tmux is unavailable, and you can explicitly set `sessions.mux=zellij` if that is your preferred backend. The interactive onboarding and pane tooling are tmux-first today.
 
 ## Quick start
 
 ```bash
-# Interactive session picker (shows sessions + projects)
+# Interactive picker for existing workspaces and new project workspaces
 hack session
 
-# Start a session for a project
+# Reuse the default workspace for a project, or create it if needed
 hack session start <project>
 
-# List all sessions
+# List active tmux workspaces
 hack session list
 
-# Attach to an existing session
-hack session attach <session>
+# Attach to an existing workspace by name
+hack session attach <workspace>
 
-# Run a command in a session
-hack session exec <session> "bun test"
+# Queue a command in a running workspace
+hack session exec <workspace> "bun test"
 
-# Stop a session
-hack session stop <session>
+# Stop a workspace
+hack session stop <workspace>
 
 # Capture recent output (defaults to active pane)
-hack session capture <session>
+hack session capture <workspace>
 
-# Tail session output for a short window (defaults to active pane)
-hack session tail <session>
+# Tail workspace output for a short window (defaults to active pane)
+hack session tail <workspace>
 
-# List panes in a session
-hack session panes <session>
+# List panes in a workspace
+hack session panes <workspace>
 ```
 
-## Session management
+## Core flows
 
 ### Interactive picker
 
 Running `hack session` without arguments opens an interactive picker showing:
-- **Active sessions**: tmux and zellij sessions (tmux shows attached/detached; zellij attach state is unknown)
-- **Available projects**: Registered projects without active sessions
+- **Active workspaces**: running tmux workspaces, with attached/detached status
+- **Available projects**: registered projects that do not currently have a default workspace
 
 When selecting an attached session, you can choose to:
-- **Attach**: Detach other clients and take over the session
-- **Create new**: Start a new numbered session (e.g., `project--2`)
+- **Attach**: detach other clients and take over the workspace
+- **Create isolated**: start a separate long-running workspace such as `project--2`
+
+This is the recommended entry point when you want to resume a project context but do not remember the exact workspace name.
 
-### Creating sessions
+### Start and create
 
 ```bash
-# Start session for a project (creates or attaches)
+# Reuse the default project workspace (creates it if needed)
 hack session start my-project
 
-# Force create a new numbered session
+# Force creation of an isolated numbered workspace
 hack session start my-project --new
 
-# Create with custom name suffix
+# Create an isolated workspace with a custom suffix
 hack session start my-project --name agent-1
 # Creates: my-project--agent-1
 
-# Run `hack up -d` before attaching
+# Prepare services before creating or attaching
 hack session start my-project --up
+
+# Create or reuse without attaching the current terminal
+hack session start my-project --detach
 ```
 
-Sessions are created at the project's repo root, not the `.hack/` directory.
+Default behavior is deliberate:
+- The first workspace for a project is just the project name, for example `my-project`
+- `--new` or `--name` creates an isolated workspace for a second agent, experiment, or review lane
+- `--detach` keeps the workspace alive for another tool or terminal to attach later
+
+Workspaces are created at the project's repo root, not the `.hack/` directory.
 
-### Attaching to sessions
+### Attach
 
 ```bash
-# Attach to an existing session
+# Attach to an existing workspace
 hack session attach my-project
 
-# From inside tmux, this switches to the session instead of nesting
+# From inside tmux, this switches clients instead of nesting tmux
 ```
 
-When attaching, the `-d` flag detaches other clients to avoid terminal size conflicts when multiple devices are connected.
+Use `attach` when you already know which workspace you want. If you are already inside tmux, hack switches clients instead of nesting tmux inside tmux. When attaching, tmux detaches other clients to avoid terminal size conflicts across multiple devices.
 
-### Executing commands
+### Exec
 
 ```bash
-# Send a command to a running session
+# Send a command to a running workspace
 hack session exec my-project "bun test"
 
-# tmux: sends the command + Enter to the session's active pane
-# zellij: opens a new pane and runs the command (no "active pane" concept)
+# tmux: sends the command + Enter to the active pane
+# zellij: opens a new pane and runs the command because there is no active-pane equivalent
 ```
 
+Use `exec` when you want to drive a persistent workspace from another terminal, script, or agent without attaching interactively first.
+
 ### Listing panes (tmux only)
 
 Use `hack session panes` to list panes with useful metadata (target, active flag, window/pane indices, command, path).
@@ -147,7 +163,7 @@ hack ssh --direct --host 192.168.1.100
 # Specify user and port
 hack ssh --host example.com --user dev --port 2222
 
-# Connect directly to a session
+# Connect directly to a workspace
 hack ssh my-session
 ```
 
@@ -155,8 +171,8 @@ hack ssh my-session
 
 1. **SSH command**: Copy-paste command to connect
 2. **QR code**: Scan with mobile SSH apps (Blink, Termius)
-3. **Active sessions**: List of active tmux sessions on this machine (currently tmux-only)
-4. **Action picker**: Done or connect to a session
+3. **Active workspaces**: List of active tmux workspaces on this machine (currently tmux-only)
+4. **Action picker**: Done or connect to a workspace
 
 ### Tailscale setup
 
@@ -171,9 +187,9 @@ Tailscale connected!
 
 ### Terminal size conflicts
 
-When multiple clients attach to the same tmux session, terminal size can get messed up. The session commands use `tmux attach -d` to detach other clients, avoiding this issue.
+When multiple clients attach to the same tmux workspace, terminal size can get messed up. The session commands use `tmux attach -d` to detach other clients, avoiding this issue.
 
-If you're already in tmux and want to switch sessions without detaching:
+If you're already in tmux and want to switch workspaces without detaching:
 
 ```bash
 # Inside tmux: prefix + s to open session switcher
@@ -207,10 +223,20 @@ Global default:
 hack config set --global sessions.mux zellij
 ```
 
+Recommended onboarding:
+
+```bash
+# Install the tmux popup binding that launches the picker
+hack setup tmux
+
+# Keep tmux as the guided default, but switch globally if your team prefers zellij
+hack config set --global sessions.mux zellij
+```
+
 ## Daemon sessions API
 
-The hack daemon exposes a REST API for managing mux sessions programmatically (tmux and zellij). This is useful for:
-- Remote session control via the gateway
+The hack daemon exposes a REST API for managing mux-backed workspaces programmatically (tmux and zellij). This is useful for:
+- Remote workspace control via the gateway
 - Building automation tools
 - Agent orchestration
 
@@ -223,14 +249,14 @@ See the [Gateway API](gateway-api.md) for authentication and endpoint details.
 
 | Method | Path | Description |
 | --- | --- | --- |
-| GET | `/v1/sessions` | List all sessions |
-| POST | `/v1/sessions` | Create a new session |
-| GET | `/v1/sessions/:id` | Get session details |
-| POST | `/v1/sessions/:id/stop` | Stop (kill) a session |
-| POST | `/v1/sessions/:id/exec` | Execute command in session |
+| GET | `/v1/sessions` | List all workspaces |
+| POST | `/v1/sessions` | Create a new workspace |
+| GET | `/v1/sessions/:id` | Get workspace details |
+| POST | `/v1/sessions/:id/stop` | Stop (kill) a workspace |
+| POST | `/v1/sessions/:id/exec` | Execute command in a workspace |
 | POST | `/v1/sessions/:id/input` | Send raw keystrokes |
 
-### List sessions
+### List workspaces
 
 ```bash
 curl -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" \
@@ -259,7 +285,7 @@ Response:
 }
 ```
 
-### Create session
+### Create workspace
 
 ```bash
 curl -X POST http://127.0.0.1:7788/v1/sessions \
@@ -271,7 +297,7 @@ curl -X POST http://127.0.0.1:7788/v1/sessions \
 Request body:
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
-| `name` | string | yes | Session name (alphanumeric, dash, underscore) |
+| `name` | string | yes | Workspace name (alphanumeric, dash, underscore) |
 | `cwd` | string | no | Working directory |
 | `backend` | string | no | Override backend (`tmux` or `zellij`) |
 
@@ -289,14 +315,14 @@ Response (201):
 }
 ```
 
-### Get session
+### Get workspace
 
 ```bash
 curl -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" \
   http://127.0.0.1:7788/v1/sessions/agent-1
 ```
 
-Response includes connection info for SSH access:
+Response includes connection info for SSH access to the workspace:
 ```json
 {
   "session": { ... },
@@ -356,7 +382,7 @@ Response:
 }
 ```
 
-### Stop session
+### Stop workspace
 
 ```bash
 curl -X POST -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" \
@@ -376,8 +402,8 @@ Response:
 | Status | Error | Description |
 | --- | --- | --- |
 | 400 | `invalid_json` | Request body is not valid JSON |
-| 400 | `missing_name` | Session name not provided |
-| 400 | `invalid_name` | Session name contains invalid characters |
+| 400 | `missing_name` | Workspace name not provided |
+| 400 | `invalid_name` | Workspace name contains invalid characters |
 | 400 | `missing_command` | Command not provided for exec |
 | 400 | `missing_keys` | Keys not provided for input |
 | 400 | `missing_session_id` | Session ID not in URL |
@@ -390,7 +416,7 @@ Response:
 
 ## Example: Remote agent workflow
 
-1. **Create a session from your remote client**:
+1. **Create a workspace from your remote client**:
    ```bash
    curl -X POST http://gateway.example.com/v1/sessions \
      -H "Authorization: Bearer $TOKEN" \
diff --git a/src/agents/codex-skill.ts b/src/agents/codex-skill.ts
index fdf6424b6..718179590 100644
--- a/src/agents/codex-skill.ts
+++ b/src/agents/codex-skill.ts
@@ -117,8 +117,8 @@ export function renderCodexSkill(): string {
     "---",
     "name: hack-cli",
     "description: >",
-    "  Use the hack CLI for local runtime orchestration (compose, DNS/TLS, logs, sessions, tickets) and agent setup.",
-    "  Trigger when asked to run/start/stop services, inspect logs, manage lifecycle/session workflows, or update",
+    "  Use the hack CLI for local runtime orchestration (compose, DNS/TLS, logs, persistent project workspaces, tickets) and agent setup.",
+    "  Trigger when asked to run/start/stop services, inspect logs, manage lifecycle/workspace workflows, or update",
     "  agent integrations. Prefer CLI over MCP when shell access is available.",
     "---",
     "",
@@ -216,13 +216,13 @@ export function renderCodexSkill(): string {
     "- `hack logs --branch <name>`",
     "- `hack down --branch <name>`",
     "",
-    "## Sessions",
+    "## Workspaces",
     "",
-    "- Picker: `hack session`",
-    "- Start/attach: `hack session start <project>`",
-    "- Isolated agent session: `hack session start <project> --new --name agent-1`",
-    '- Exec: `hack session exec <session> "<command>"`',
-    "- Stop: `hack session stop <session>`",
+    "- Picker: `hack session` for persistent project workspaces.",
+    "- Reuse/create: `hack session start <project>`",
+    "- Isolated agent workspace: `hack session start <project> --new --name agent-1` (`<project>--agent-1`).",
+    '- Exec in workspace: `hack session exec <workspace> "<command>"`',
+    "- Stop workspace: `hack session stop <workspace>`",
     "",
     "## Tickets",
     "",
diff --git a/src/commands/session.ts b/src/commands/session.ts
index 5d1a7a717..b4a8aacbf 100644
--- a/src/commands/session.ts
+++ b/src/commands/session.ts
@@ -10,6 +10,11 @@ import { optJson, optPretty } from "../cli/options.ts";
 import type { RegisteredProject } from "../lib/projects-registry.ts";
 import { readProjectsRegistry } from "../lib/projects-registry.ts";
 import { exec, run } from "../lib/shell.ts";
+import {
+  buildSessionName,
+  getNextNumericSessionSuffix,
+  parseSessionBase,
+} from "../mux/session-names.ts";
 import { logger } from "../ui/logger.ts";
 import {
   buildSessionPanesEndEvent,
@@ -39,21 +44,23 @@ const optUp = defineOption({
   name: "up",
   type: "boolean",
   long: "--up",
-  description: "Run hack up -d before attaching",
+  description: "Run hack up -d before creating or attaching",
 } as const);
 
 const optNew = defineOption({
   name: "new",
   type: "boolean",
   long: "--new",
-  description: "Force create new session even if one exists",
+  description:
+    "Create an isolated workspace instead of reusing the default project workspace",
 } as const);
 
 const optName = defineOption({
   name: "name",
   type: "string",
   long: "--name",
-  description: "Custom suffix for new session (e.g., agent-1)",
+  description:
+    "Suffix for an isolated workspace name (for example: agent-1 -> project--agent-1)",
 } as const);
 
 const optDetach = defineOption({
@@ -61,7 +68,8 @@ const optDetach = defineOption({
   type: "boolean",
   long: "--detach",
   short: "-d",
-  description: "Create/switch session without attaching (for GUI/non-TTY use)",
+  description:
+    "Create or reuse the workspace without attaching (for GUI/non-TTY use)",
 } as const);
 
 const optTarget = defineOption({
@@ -102,7 +110,7 @@ const optMaxMs = defineOption({
 // Subcommand specs
 const listSpec = defineCommand({
   name: "list",
-  summary: "List active tmux sessions",
+  summary: "List active tmux workspaces",
   group: "Project",
   options: [],
   positionals: [],
@@ -111,8 +119,10 @@ const listSpec = defineCommand({
 
 const startSpec = defineCommand({
   name: "start",
-  summary: "Start or attach to a session for a project",
+  summary: "Reuse the default project workspace or create an isolated one",
   group: "Project",
+  description:
+    "Reuse the default project workspace when it already exists, or create an isolated long-running workspace with --new or --name. Use --detach when another tool should keep the workspace alive without attaching your terminal.",
   options: [optUp, optNew, optName, optDetach],
   positionals: [
     { name: "project", description: "Project name or path", required: false },
@@ -122,36 +132,40 @@ const startSpec = defineCommand({
 
 const stopSpec = defineCommand({
   name: "stop",
-  summary: "Stop (kill) a tmux session",
+  summary: "Stop a tmux-backed workspace",
   group: "Project",
   options: [],
   positionals: [
-    { name: "session", description: "Session name", required: true },
+    { name: "workspace", description: "Workspace name", required: true },
   ],
   subcommands: [],
 } as const);
 
 const attachSpec = defineCommand({
   name: "attach",
-  summary: "Attach to an existing tmux session",
+  summary: "Attach to an existing workspace",
   group: "Project",
+  description:
+    "Attach to a running tmux workspace by name. When you are already inside tmux, hack switches clients instead of nesting tmux inside tmux.",
   options: [],
   positionals: [
-    { name: "session", description: "Session name", required: true },
+    { name: "workspace", description: "Workspace name", required: true },
   ],
   subcommands: [],
 } as const);
 
 const execSpec = defineCommand({
   name: "exec",
-  summary: "Execute a command in a tmux session",
+  summary: "Send a command to a running workspace",
   group: "Project",
+  description:
+    "Queue a command in the workspace's active pane without opening a new shell. This is useful for long-running agents, background checks, or remote follow-up work.",
   options: [],
   positionals: [
-    { name: "session", description: "Session name", required: true },
+    { name: "workspace", description: "Workspace name", required: true },
     {
       name: "command",
-      description: "Command to execute in session",
+      description: "Command to execute in workspace",
       required: true,
     },
   ],
@@ -160,33 +174,33 @@ const execSpec = defineCommand({
 
 const panesSpec = defineCommand({
   name: "panes",
-  summary: "List panes in a tmux session",
+  summary: "List panes in a tmux workspace",
   group: "Project",
   options: [optJson, optPretty],
   positionals: [
-    { name: "session", description: "Session name", required: true },
+    { name: "workspace", description: "Workspace name", required: true },
   ],
   subcommands: [],
 } as const);
 
 const captureSpec = defineCommand({
   name: "capture",
-  summary: "Capture recent output from a tmux session",
+  summary: "Capture recent output from a tmux workspace",
   group: "Project",
   options: [optTarget, optLines, optJson, optPretty],
   positionals: [
-    { name: "session", description: "Session name", required: true },
+    { name: "workspace", description: "Workspace name", required: true },
   ],
   subcommands: [],
 } as const);
 
 const tailSpec = defineCommand({
   name: "tail",
-  summary: "Tail output from a tmux session",
+  summary: "Tail output from a tmux workspace",
   group: "Project",
   options: [optTarget, optLines, optIntervalMs, optMaxMs, optJson, optPretty],
   positionals: [
-    { name: "session", description: "Session name", required: true },
+    { name: "workspace", description: "Workspace name", required: true },
   ],
   subcommands: [],
 } as const);
@@ -220,81 +234,385 @@ type TailArgs = CommandArgs<
   typeof tailSpec.positionals
 >;
 
-/**
- * Interactive session picker (default when no subcommand).
- *
- * Uses clack prompts with grouped options for sessions and projects.
- */
-async function handleSessionPicker(): Promise<number> {
-  const sessions = await listTmuxSessions();
-  const registry = await readProjectsRegistry();
-  const projects = registry.projects;
-
-  p.intro("Sessions");
-
-  const sessionNames = new Set(sessions.map((s) => s.name));
-  const home = process.env.HOME ?? "";
-
-  // Helper to shorten paths with ~/
-  const shortenPath = (path: string): string => {
-    if (home && path.startsWith(home)) {
-      return `~${path.slice(home.length)}`;
-    }
-    return path;
-  };
+type SessionPickerOption = {
+  readonly value: string;
+  readonly label: string;
+  readonly hint?: string;
+};
 
-  // Build options for clack select
-  type SessionOption = {
-    value: string;
-    label: string;
-    hint?: string;
-  };
+type SessionStreamContext = {
+  readonly session: string;
+  readonly target: string;
+  readonly lines: number;
+  readonly follow: boolean;
+  readonly intervalMs?: number;
+  readonly maxMs?: number;
+};
 
-  const options: SessionOption[] = [];
+function shortenPathForDisplay(opts: {
+  readonly path: string;
+  readonly home: string;
+}): string {
+  if (opts.home && opts.path.startsWith(opts.home)) {
+    return `~${opts.path.slice(opts.home.length)}`;
+  }
+  return opts.path;
+}
 
-  // Active sessions
-  const attachedSessions = sessions.filter((s) => s.attached);
-  const detachedSessions = sessions.filter((s) => !s.attached);
+function buildSessionPickerOptions(opts: {
+  readonly sessions: readonly TmuxSession[];
+  readonly projects: readonly RegisteredProject[];
+  readonly home: string;
+}): SessionPickerOption[] {
+  const options: SessionPickerOption[] = [];
 
-  for (const session of attachedSessions) {
+  for (const session of opts.sessions.filter((s) => s.attached)) {
     options.push({
       value: `session:${session.name}`,
       label: session.name,
-      hint: `attached${session.path ? ` • ${shortenPath(session.path)}` : ""}`,
+      hint: `attached${
+        session.path
+          ? ` • ${shortenPathForDisplay({ path: session.path, home: opts.home })}`
+          : ""
+      }`,
     });
   }
 
-  for (const session of detachedSessions) {
+  for (const session of opts.sessions.filter((s) => !s.attached)) {
     options.push({
       value: `session:${session.name}`,
       label: session.name,
-      hint: session.path ? shortenPath(session.path) : "detached",
+      hint: session.path
+        ? shortenPathForDisplay({ path: session.path, home: opts.home })
+        : "detached",
     });
   }
 
-  // Projects without active sessions
-  const availableProjects = projects.filter(
+  const sessionNames = new Set(opts.sessions.map((s) => s.name));
+  for (const project of opts.projects.filter(
     (proj: RegisteredProject) => !sessionNames.has(proj.name)
-  );
-
-  for (const project of availableProjects) {
+  )) {
     options.push({
       value: `project:${project.name}`,
       label: project.name,
-      hint: `new • ${shortenPath(project.repoRoot)}`,
+      hint: `new • ${shortenPathForDisplay({
+        path: project.repoRoot,
+        home: opts.home,
+      })}`,
+    });
+  }
+
+  return options;
+}
+
+async function promptAttachedWorkspaceAction(opts: {
+  readonly attachedWorkspaceName: string;
+  readonly nextWorkspaceName: string;
+}): Promise<"attach" | "new" | null> {
+  const action = await p.select({
+    message: `Workspace '${opts.attachedWorkspaceName}' is attached elsewhere`,
+    options: [
+      { value: "attach", label: "Attach", hint: "detaches other clients" },
+      {
+        value: "new",
+        label: "Create isolated",
+        hint: opts.nextWorkspaceName,
+      },
+    ],
+  });
+
+  if (p.isCancel(action)) {
+    p.outro("Cancelled");
+    return null;
+  }
+
+  return action;
+}
+
+async function handleSelectedSession(opts: {
+  readonly name: string;
+  readonly sessions: readonly TmuxSession[];
+  readonly projects: readonly RegisteredProject[];
+}): Promise<number> {
+  const session = opts.sessions.find((s) => s.name === opts.name);
+  if (!session?.attached) {
+    return await attachToSession(opts.name);
+  }
+
+  const baseName = resolveWorkspaceBaseName({ workspaceName: opts.name });
+  const nextWorkspaceName = resolveNextIsolatedWorkspaceName({
+    workspaceName: opts.name,
+    sessions: opts.sessions,
+  });
+  const action = await promptAttachedWorkspaceAction({
+    attachedWorkspaceName: opts.name,
+    nextWorkspaceName,
+  });
+  if (!action) {
+    return 0;
+  }
+  if (action !== "new") {
+    return await attachToSession(opts.name);
+  }
+
+  const project = opts.projects.find(
+    (proj: RegisteredProject) => proj.name === baseName
+  );
+  return await createAndAttachSession({
+    name: nextWorkspaceName,
+    cwd: project?.repoRoot ?? session.path ?? process.cwd(),
+  });
+}
+
+async function handleSelectedProject(opts: {
+  readonly name: string;
+  readonly projects: readonly RegisteredProject[];
+}): Promise<number> {
+  const project = opts.projects.find(
+    (proj: RegisteredProject) => proj.name === opts.name
+  );
+  if (!project) {
+    p.log.error(`Project not found: ${opts.name}`);
+    return 1;
+  }
+
+  return await createAndAttachSession({
+    name: project.name,
+    cwd: project.repoRoot,
+  });
+}
+
+async function resolveProjectForSessionStart(opts: {
+  readonly projectNameOrPath: string | undefined;
+}): Promise<RegisteredProject | null> {
+  const registry = await readProjectsRegistry();
+  const projects = registry.projects;
+  const projectNameOrPath = opts.projectNameOrPath;
+
+  const directMatch = projectNameOrPath
+    ? projects.find(
+        (project: RegisteredProject) =>
+          project.name === projectNameOrPath ||
+          project.projectDir === resolve(projectNameOrPath)
+      )
+    : null;
+  if (directMatch) {
+    return directMatch;
+  }
+
+  if (!projectNameOrPath) {
+    return null;
+  }
+
+  const resolvedPath = resolve(projectNameOrPath);
+  return (
+    projects.find(
+      (project: RegisteredProject) => project.projectDir === resolvedPath
+    ) ?? null
+  );
+}
+
+async function resolveSessionNameForStart(opts: {
+  readonly baseName: string;
+  readonly forceNew: boolean;
+  readonly customName: string | undefined;
+}): Promise<string> {
+  if (opts.customName) {
+    return buildSessionName({ base: opts.baseName, suffix: opts.customName });
+  }
+
+  if (!opts.forceNew) {
+    return opts.baseName;
+  }
+
+  const sessions = await listTmuxSessions();
+  const nextSuffix = getNextNumericSessionSuffix({
+    sessions,
+    base: opts.baseName,
+  });
+  return buildSessionName({
+    base: opts.baseName,
+    suffix: String(nextSuffix),
+  });
+}
+
+async function maybeReuseExistingWorkspace(opts: {
+  readonly baseName: string;
+  readonly project: RegisteredProject;
+  readonly detach: boolean;
+  readonly runUp: boolean;
+  readonly forceNew: boolean;
+  readonly customName: string | undefined;
+}): Promise<number | null> {
+  if (opts.forceNew || opts.customName) {
+    return null;
+  }
+
+  const sessions = await listTmuxSessions();
+  const existing = sessions.find((s) => s.name === opts.baseName);
+  if (!existing) {
+    return null;
+  }
+
+  if (opts.detach) {
+    logger.info({ message: `Workspace ready: ${opts.baseName}` });
+  } else {
+    logger.info({
+      message: `Attaching to existing workspace: ${opts.baseName}`,
+    });
+  }
+
+  if (opts.runUp) {
+    await runHackUp(resolveRunUpCwd({ project: opts.project }));
+  }
+
+  if (opts.detach) {
+    return 0;
+  }
+
+  return await attachToSession(opts.baseName);
+}
+
+function ensureStreamOutputMode(opts: {
+  readonly json: boolean;
+  readonly pretty: boolean;
+}): boolean {
+  if (!(opts.json && opts.pretty)) {
+    return true;
+  }
+
+  process.stderr.write("Cannot combine --json with --pretty.\n");
+  return false;
+}
+
+function writeSessionStreamError(opts: {
+  readonly json: boolean;
+  readonly context: SessionStreamContext;
+  readonly message: string;
+}): void {
+  if (opts.json) {
+    writeSessionStreamEvent({
+      event: buildSessionStreamErrorEvent({
+        context: opts.context,
+        message: opts.message,
+      }),
+    });
+    writeSessionStreamEvent({
+      event: buildSessionStreamEndEvent({
+        context: opts.context,
+        reason: "error",
+      }),
+    });
+    return;
+  }
+
+  console.error(opts.message);
+}
+
+function emitSessionOutputLines(opts: {
+  readonly json: boolean;
+  readonly context: SessionStreamContext;
+  readonly output: string;
+}): void {
+  if (opts.json) {
+    for (const line of splitLines(opts.output)) {
+      writeSessionStreamEvent({
+        event: buildSessionStreamLogEvent({ context: opts.context, line }),
+      });
+    }
+    return;
+  }
+
+  process.stdout.write(opts.output);
+}
+
+async function captureTailOutput(opts: {
+  readonly target: string;
+  readonly lines: number;
+  readonly sessionName: string;
+  readonly json: boolean;
+  readonly context: SessionStreamContext;
+}): Promise<string | null> {
+  const result = await capturePane({ target: opts.target, lines: opts.lines });
+  if (result.exitCode === 0) {
+    return result.stdout;
+  }
+
+  writeSessionStreamError({
+    json: opts.json,
+    context: opts.context,
+    message: result.stderr || `Failed to capture ${opts.sessionName}`,
+  });
+  return null;
+}
+
+async function streamTailOutput(opts: {
+  readonly target: string;
+  readonly lines: number;
+  readonly intervalMs: number;
+  readonly maxMs: number;
+  readonly sessionName: string;
+  readonly json: boolean;
+  readonly context: SessionStreamContext;
+  readonly initialOutput: string;
+}): Promise<number> {
+  let lastOutput = opts.initialOutput;
+  const start = Date.now();
+
+  while (Date.now() - start < opts.maxMs) {
+    await delay(opts.intervalMs);
+
+    const nextOutput = await captureTailOutput({
+      target: opts.target,
+      lines: opts.lines,
+      sessionName: opts.sessionName,
+      json: opts.json,
+      context: opts.context,
     });
+    if (nextOutput === null) {
+      return 1;
+    }
+
+    const suffix = diffNewLines({ previous: lastOutput, next: nextOutput });
+    if (suffix) {
+      emitSessionOutputLines({
+        json: opts.json,
+        context: opts.context,
+        output: suffix,
+      });
+    }
+
+    lastOutput = nextOutput;
   }
 
+  return 0;
+}
+
+/**
+ * Interactive session picker (default when no subcommand).
+ *
+ * Uses clack prompts with grouped options for sessions and projects.
+ */
+async function handleSessionPicker(): Promise<number> {
+  const sessions = await listTmuxSessions();
+  p.intro("Workspaces");
+  const projects = (await readProjectsRegistry()).projects;
+  const options = buildSessionPickerOptions({
+    sessions,
+    projects,
+    home: process.env.HOME ?? "",
+  });
+
   if (options.length === 0) {
     p.log.warn(
-      "No sessions or projects found. Run 'hack init' in a project first."
+      "No workspaces or projects found. Run 'hack init' in a project first."
     );
     p.outro("");
     return 1;
   }
 
   const selection = await p.select({
-    message: "Select session or project",
+    message: "Select workspace or project",
     options,
   });
 
@@ -313,70 +631,49 @@ async function handleSessionPicker(): Promise<number> {
   }
 
   if (type === "session") {
-    const session = sessions.find((s) => s.name === name);
-
-    // If session is attached elsewhere, offer choice
-    if (session?.attached) {
-      const nextNum = getNextSessionNumber(sessions, name);
-
-      const action = await p.select({
-        message: `Session '${name}' is attached elsewhere`,
-        options: [
-          { value: "attach", label: "Attach", hint: "detaches other clients" },
-          { value: "new", label: "Create new", hint: `${name}:${nextNum}` },
-        ],
-      });
+    return await handleSelectedSession({ name, sessions, projects });
+  }
 
-      if (p.isCancel(action)) {
-        p.outro("Cancelled");
-        return 0;
-      }
-
-      if (action === "new") {
-        const project = projects.find(
-          (proj: RegisteredProject) => proj.name === name
-        );
-        const cwd = project?.repoRoot ?? session.path ?? process.cwd();
-        return await createAndAttachSession({
-          name: `${name}:${nextNum}`,
-          cwd,
-        });
-      }
-    }
+  return await handleSelectedProject({ name, projects });
+}
 
-    return await attachToSession(name);
-  }
+function resolveWorkspaceBaseName(opts: {
+  readonly workspaceName: string;
+}): string {
+  return parseSessionBase({ name: opts.workspaceName });
+}
 
-  // Create new session for project
-  const project = projects.find(
-    (proj: RegisteredProject) => proj.name === name
-  );
-  if (!project) {
-    p.log.error(`Project not found: ${name}`);
-    return 1;
-  }
+function resolveNextIsolatedWorkspaceName(opts: {
+  readonly workspaceName: string;
+  readonly sessions: readonly TmuxSession[];
+}): string {
+  const baseName = resolveWorkspaceBaseName({
+    workspaceName: opts.workspaceName,
+  });
+  const nextSuffix = getNextNumericSessionSuffix({
+    sessions: opts.sessions,
+    base: baseName,
+  });
+  return buildSessionName({ base: baseName, suffix: String(nextSuffix) });
+}
 
-  return await createAndAttachSession({
-    name: project.name,
-    cwd: project.repoRoot,
+function resolveWorkspaceProjectName(opts: {
+  readonly workspaceName: string;
+  readonly projects: readonly RegisteredProject[];
+}): string {
+  const workspaceBase = resolveWorkspaceBaseName({
+    workspaceName: opts.workspaceName,
   });
+  const project =
+    opts.projects.find((candidate) => candidate.name === opts.workspaceName) ??
+    opts.projects.find((candidate) => candidate.name === workspaceBase);
+  return project?.name ?? "-";
 }
 
-/**
- * Get the next available session number for a base name.
- */
-function getNextSessionNumber(
-  sessions: TmuxSession[],
-  baseName: string
-): number {
-  const existing = sessions.filter(
-    (s) => s.name === baseName || s.name.startsWith(`${baseName}:`)
-  );
-  let n = 2;
-  while (existing.some((s) => s.name === `${baseName}:${n}`)) {
-    n++;
-  }
-  return n;
+function resolveRunUpCwd(opts: {
+  readonly project: RegisteredProject;
+}): string {
+  return opts.project.repoRoot;
 }
 
 const handleList: CommandHandlerFor<
@@ -387,20 +684,20 @@ const handleList: CommandHandlerFor<
   const projects = registry.projects;
 
   if (sessions.length === 0) {
-    logger.info({ message: "No active tmux sessions" });
+    logger.info({ message: "No active tmux workspaces" });
     return 0;
   }
 
   console.log(
-    `${"Session".padEnd(20) + "Project".padEnd(20) + "Node".padEnd(10)}Status`
+    `${"Workspace".padEnd(20) + "Project".padEnd(20) + "Node".padEnd(10)}Status`
   );
   console.log("-".repeat(60));
 
   for (const session of sessions) {
-    const project = projects.find(
-      (p: RegisteredProject) => p.name === session.name
-    );
-    const projectName = project?.name ?? "-";
+    const projectName = resolveWorkspaceProjectName({
+      workspaceName: session.name,
+      projects,
+    });
     const status = session.attached ? "attached" : "detached";
     console.log(
       session.name.padEnd(20) +
@@ -424,25 +721,7 @@ const handleStart = async ({
   const runUp = args.options.up === true;
   const customName = args.options.name;
   const detach = args.options.detach === true;
-
-  // Find project
-  const registry = await readProjectsRegistry();
-  const projects = registry.projects;
-  let project = projectNameOrPath
-    ? projects.find(
-        (p: RegisteredProject) =>
-          p.name === projectNameOrPath ||
-          p.projectDir === resolve(projectNameOrPath)
-      )
-    : null;
-
-  if (!project && projectNameOrPath) {
-    // Try as path
-    const resolvedPath = resolve(projectNameOrPath);
-    project = projects.find(
-      (p: RegisteredProject) => p.projectDir === resolvedPath
-    );
-  }
+  const project = await resolveProjectForSessionStart({ projectNameOrPath });
 
   if (!project) {
     if (projectNameOrPath) {
@@ -456,48 +735,27 @@ const handleStart = async ({
   }
 
   const baseName = project.name;
-  let sessionName = baseName;
-
-  if (forceNew || customName) {
-    if (customName) {
-      sessionName = `${baseName}:${customName}`;
-    } else {
-      // Find next available number
-      const sessions = await listTmuxSessions();
-      const existing = sessions.filter(
-        (s) => s.name === baseName || s.name.startsWith(`${baseName}:`)
-      );
-      if (existing.length > 0) {
-        let n = 2;
-        while (existing.some((s) => s.name === `${baseName}:${n}`)) {
-          n++;
-        }
-        sessionName = `${baseName}:${n}`;
-      }
-    }
-  } else {
-    // Check if session exists
-    const sessions = await listTmuxSessions();
-    const existing = sessions.find((s) => s.name === baseName);
-    if (existing) {
-      if (detach) {
-        logger.info({ message: `Session ready: ${baseName}` });
-      } else {
-        logger.info({ message: `Attaching to existing session: ${baseName}` });
-      }
-      if (runUp) {
-        await runHackUp(project.projectDir);
-      }
-      if (detach) {
-        return 0;
-      }
-      return await attachToSession(baseName);
-    }
+  const reused = await maybeReuseExistingWorkspace({
+    baseName,
+    project,
+    detach,
+    runUp,
+    forceNew,
+    customName,
+  });
+  if (reused !== null) {
+    return reused;
   }
 
+  const sessionName = await resolveSessionNameForStart({
+    baseName,
+    forceNew,
+    customName,
+  });
+
   // Run hack up if requested
   if (runUp) {
-    await runHackUp(project.repoRoot);
+    await runHackUp(resolveRunUpCwd({ project }));
   }
 
   // Use repoRoot (project root), not projectDir (.hack/)
@@ -519,17 +777,17 @@ const handleStop = async ({
   readonly ctx: CliContext;
   readonly args: StopArgs;
 }): Promise<number> => {
-  const sessionName = args.positionals.session;
+  const workspaceName = args.positionals.workspace;
 
-  const result = await exec(["tmux", "kill-session", "-t", sessionName], {
+  const result = await exec(["tmux", "kill-session", "-t", workspaceName], {
     stdin: "ignore",
   });
   if (result.exitCode !== 0) {
-    logger.error({ message: `Failed to stop session: ${sessionName}` });
+    logger.error({ message: `Failed to stop workspace: ${workspaceName}` });
     return 1;
   }
 
-  logger.success({ message: `Stopped session: ${sessionName}` });
+  logger.success({ message: `Stopped workspace: ${workspaceName}` });
   return 0;
 };
 
@@ -539,8 +797,8 @@ const handleAttach = async ({
   readonly ctx: CliContext;
   readonly args: AttachArgs;
 }): Promise<number> => {
-  const sessionName = args.positionals.session;
-  return await attachToSession(sessionName);
+  const workspaceName = args.positionals.workspace;
+  return await attachToSession(workspaceName);
 };
 
 const handleExec = async ({
@@ -549,11 +807,11 @@ const handleExec = async ({
   readonly ctx: CliContext;
   readonly args: ExecArgs;
 }): Promise<number> => {
-  const sessionName = args.positionals.session;
+  const workspaceName = args.positionals.workspace;
   const command = args.positionals.command;
 
   const result = await exec(
-    ["tmux", "send-keys", "-t", sessionName, command, "Enter"],
+    ["tmux", "send-keys", "-t", workspaceName, command, "Enter"],
     {
       stdin: "ignore",
     }
@@ -561,12 +819,12 @@ const handleExec = async ({
 
   if (result.exitCode !== 0) {
     logger.error({
-      message: `Failed to send command to session: ${sessionName}`,
+      message: `Failed to send command to workspace: ${workspaceName}`,
     });
     return 1;
   }
 
-  logger.success({ message: `Sent command to ${sessionName}: ${command}` });
+  logger.success({ message: `Sent command to ${workspaceName}: ${command}` });
   return 0;
 };
 
@@ -576,7 +834,7 @@ const handlePanes = async ({
   readonly ctx: CliContext;
   readonly args: PanesArgs;
 }): Promise<number> => {
-  const sessionName = args.positionals.session;
+  const sessionName = args.positionals.workspace;
   const pretty = args.options.pretty === true;
   const json = args.options.json === true || !pretty;
 
@@ -635,15 +893,14 @@ const handleCapture = async ({
   readonly ctx: CliContext;
   readonly args: CaptureArgs;
 }): Promise<number> => {
-  const sessionName = args.positionals.session;
+  const sessionName = args.positionals.workspace;
   const target =
     args.options.target ?? (await resolveActiveTarget(sessionName));
   const lines = args.options.lines ?? 200;
   const pretty = args.options.pretty === true;
   const json = args.options.json === true || !pretty;
 
-  if (json && pretty) {
-    process.stderr.write("Cannot combine --json with --pretty.\n");
+  if (!ensureStreamOutputMode({ json, pretty })) {
     return 1;
   }
 
@@ -698,7 +955,7 @@ const handleTail = async ({
   readonly ctx: CliContext;
   readonly args: TailArgs;
 }): Promise<number> => {
-  const sessionName = args.positionals.session;
+  const sessionName = args.positionals.workspace;
   const target =
     args.options.target ?? (await resolveActiveTarget(sessionName));
   const lines = args.options.lines ?? 200;
@@ -727,59 +984,29 @@ const handleTail = async ({
     });
   }
 
-  const initial = await capturePane({ target, lines });
-  if (initial.exitCode !== 0) {
-    const message = initial.stderr || `Failed to capture ${sessionName}`;
-    if (json) {
-      writeSessionStreamEvent({
-        event: buildSessionStreamErrorEvent({ context, message }),
-      });
-      writeSessionStreamEvent({
-        event: buildSessionStreamEndEvent({ context, reason: "error" }),
-      });
-    } else {
-      console.error(message);
-    }
+  const initialOutput = await captureTailOutput({
+    target,
+    lines,
+    sessionName,
+    json,
+    context,
+  });
+  if (initialOutput === null) {
     return 1;
   }
 
-  let lastOutput = initial.stdout;
-  const start = Date.now();
-
-  while (Date.now() - start < maxMs) {
-    await delay(intervalMs);
-
-    const result = await capturePane({ target, lines });
-    if (result.exitCode !== 0) {
-      const message = result.stderr || `Failed to capture ${sessionName}`;
-      if (json) {
-        writeSessionStreamEvent({
-          event: buildSessionStreamErrorEvent({ context, message }),
-        });
-        writeSessionStreamEvent({
-          event: buildSessionStreamEndEvent({ context, reason: "error" }),
-        });
-      } else {
-        console.error(message);
-      }
-      return 1;
-    }
-
-    const nextOutput = result.stdout;
-    const suffix = diffNewLines({ previous: lastOutput, next: nextOutput });
-    if (suffix) {
-      if (json) {
-        for (const line of splitLines(suffix)) {
-          writeSessionStreamEvent({
-            event: buildSessionStreamLogEvent({ context, line }),
-          });
-        }
-      } else {
-        process.stdout.write(suffix);
-      }
-    }
-
-    lastOutput = nextOutput;
+  const tailExitCode = await streamTailOutput({
+    target,
+    lines,
+    intervalMs,
+    maxMs,
+    sessionName,
+    json,
+    context,
+    initialOutput,
+  });
+  if (tailExitCode !== 0) {
+    return tailExitCode;
   }
 
   if (json) {
@@ -793,8 +1020,10 @@ const handleTail = async ({
 
 export const sessionCommand = defineCommand({
   name: "session",
-  summary: "Manage tmux sessions for hack projects",
+  summary: "Manage persistent project workspaces with tmux-first onboarding",
   group: "Project",
+  description:
+    "Sessions keep a project workspace alive across terminal restarts, SSH reconnects, and long-running agent work. The guided default is tmux, including `hack setup tmux` for a popup picker. Other mux backends such as zellij still exist through `sessions.mux`, but the interactive session tooling is tmux-first today.",
   options: [],
   positionals: [],
   handler: handleSessionPicker,
@@ -986,11 +1215,11 @@ async function createSessionDetached(opts: {
   );
 
   if (createResult.exitCode !== 0) {
-    logger.error({ message: `Failed to create session: ${opts.name}` });
+    logger.error({ message: `Failed to create workspace: ${opts.name}` });
     return 1;
   }
 
-  logger.info({ message: `Created session: ${opts.name}` });
+  logger.info({ message: `Created workspace: ${opts.name}` });
   return 0;
 }
 
@@ -1001,3 +1230,9 @@ async function runHackUp(projectPath: string): Promise<void> {
   logger.info({ message: `Running hack up -d in ${projectPath}...` });
   await run(["hack", "up", "-d"], { cwd: projectPath, stdin: "inherit" });
 }
+
+export const __testOnlySessionCommand = {
+  resolveNextIsolatedWorkspaceName,
+  resolveRunUpCwd,
+  resolveWorkspaceProjectName,
+};
diff --git a/src/commands/setup.ts b/src/commands/setup.ts
index cfd04d063..19a09b1dd 100644
--- a/src/commands/setup.ts
+++ b/src/commands/setup.ts
@@ -169,7 +169,7 @@ type SetupMultiLogResult = {
 
 const tmuxSpec = defineCommand({
   name: "tmux",
-  summary: "Configure tmux keybinding for hack session picker",
+  summary: "Install the recommended tmux binding for hack workspaces",
   group: "Agents",
   options: setupTmuxOptions,
   positionals: [],
@@ -372,7 +372,9 @@ async function removeTmuxIntegration(): Promise<number> {
 }
 
 async function installTmuxIntegration(): Promise<number> {
-  logger.info({ message: "Setting up tmux integration for hack sessions..." });
+  logger.info({
+    message: "Setting up the recommended tmux integration for hack sessions...",
+  });
 
   const paths = await resolveTmuxConfigPaths();
   const selectedConfig = await resolveTmuxConfigToEdit({
@@ -396,7 +398,7 @@ async function installTmuxIntegration(): Promise<number> {
 
   // Ask about keybinding
   const keyChoice = await select({
-    message: "Add keybinding for hack session picker?",
+    message: "Add the recommended tmux binding for `hack session`?",
     options: [
       { value: "s", label: "Yes, use prefix + s (recommended)" },
       { value: "S", label: "Yes, use prefix + S (capital S)" },
diff --git a/src/commands/ssh.ts b/src/commands/ssh.ts
index 83dcb64d8..9bf364c2f 100644
--- a/src/commands/ssh.ts
+++ b/src/commands/ssh.ts
@@ -69,7 +69,11 @@ const sshSpec = defineCommand({
   group: "Project",
   options: [optHost, optUser, optTailscale, optDirect, optPort],
   positionals: [
-    { name: "session", description: "Session to connect to", required: false },
+    {
+      name: "workspace",
+      description: "Workspace to connect to",
+      required: false,
+    },
   ],
   subcommands: [],
 } as const);
@@ -130,34 +134,34 @@ async function handleSsh(opts: {
   qrcode.generate(sshUri, { small: true });
   console.log("");
 
-  // Step 4: Show active sessions
+  // Step 4: Show active workspaces
   const sessions = await listTmuxSessions();
 
   if (sessions.length > 0) {
     const sessionList = sessions
       .map((s) => `  • ${s.name}${s.attached ? " (attached)" : ""}`)
       .join("\n");
-    p.log.info(`Active tmux sessions:\n${sessionList}`);
+    p.log.info(`Active tmux workspaces:\n${sessionList}`);
   } else {
-    p.log.info("No active tmux sessions");
+    p.log.info("No active tmux workspaces");
   }
 
   // Step 5: Ask what to do
-  const sessionArg = args.positionals.session;
+  const workspaceArg = args.positionals.workspace;
 
-  if (sessionArg) {
-    if (!SESSION_NAME_PATTERN.test(sessionArg)) {
+  if (workspaceArg) {
+    if (!SESSION_NAME_PATTERN.test(workspaceArg)) {
       p.log.error(
-        "Invalid session name (only letters, numbers, dashes, underscores, or dots)"
+        "Invalid workspace name (only letters, numbers, dashes, underscores, or dots)"
       );
       return 1;
     }
-    // Direct connect to specified session
+    // Direct connect to specified workspace
     return await connectToSession({
       hostname,
       user,
       port,
-      sessionName: sessionArg,
+      sessionName: workspaceArg,
     });
   }
 
@@ -285,8 +289,8 @@ async function resolveSessionNameToConnect(opts: {
       },
       {
         value: "connect" as const,
-        label: "Connect to session",
-        hint: "SSH into a tmux session",
+        label: "Connect to workspace",
+        hint: "SSH into a tmux workspace",
       },
     ],
   });
@@ -301,11 +305,11 @@ async function resolveSessionNameToConnect(opts: {
       label: s.name,
       hint: s.attached ? "attached" : undefined,
     })),
-    { value: "__new__", label: "Create new session" },
+    { value: "__new__", label: "Create new workspace" },
   ];
 
   const selectedSession = await p.select({
-    message: "Select session",
+    message: "Select workspace",
     options: sessionOptions,
   });
 
@@ -318,7 +322,7 @@ async function resolveSessionNameToConnect(opts: {
   }
 
   const name = await p.text({
-    message: "Session name",
+    message: "Workspace name",
     placeholder: "main",
     defaultValue: "main",
     validate: (value) => {
@@ -403,7 +407,7 @@ async function setupTailscale(): Promise<
 }
 
 /**
- * Connect to a tmux session via SSH.
+ * Connect to a tmux workspace via SSH.
  */
 async function connectToSession(opts: {
   readonly hostname: string;
@@ -414,12 +418,12 @@ async function connectToSession(opts: {
   const sessionName = opts.sessionName.trim();
   if (!SESSION_NAME_PATTERN.test(sessionName)) {
     p.log.error(
-      "Invalid session name (only letters, numbers, dashes, underscores, or dots)"
+      "Invalid workspace name (only letters, numbers, dashes, underscores, or dots)"
     );
     return 1;
   }
 
-  p.log.step(`Connecting to ${sessionName}...`);
+  p.log.step(`Connecting to workspace ${sessionName}...`);
   console.log("");
 
   // Use login shell to ensure PATH includes homebrew etc.
diff --git a/src/lib/project-views.ts b/src/lib/project-views.ts
index d134753c9..b3c29908e 100644
--- a/src/lib/project-views.ts
+++ b/src/lib/project-views.ts
@@ -8,6 +8,7 @@ import {
   PROJECT_ENV_FILENAME,
 } from "../constants.ts";
 import { readControlPlaneConfig } from "../control-plane/sdk/config.ts";
+import { parseSessionBase } from "../mux/session-names.ts";
 import { pathExists, readTextFile } from "./fs.ts";
 import { isRecord } from "./guards.ts";
 import {
@@ -581,16 +582,20 @@ function matchesHackSessionName(opts: {
   readonly sessionName: string;
   readonly projectName: string;
 }): boolean {
-  const [sessionBase] = opts.sessionName.split(":");
   const normalizedProject = normalizeSessionToken(opts.projectName);
-  const normalizedSessionBase = normalizeSessionToken(sessionBase ?? "");
-  if (normalizedProject.length === 0 || normalizedSessionBase.length === 0) {
+  const primaryBase = parseSessionBase({ name: opts.sessionName });
+  const legacyBase = opts.sessionName.split(":")[0] ?? "";
+  const normalizedBases = [primaryBase, legacyBase]
+    .map((value) => normalizeSessionToken(value))
+    .filter((value) => value.length > 0);
+  if (normalizedProject.length === 0 || normalizedBases.length === 0) {
     return false;
   }
   return (
     opts.sessionName === opts.projectName ||
+    opts.sessionName.startsWith(`${opts.projectName}--`) ||
     opts.sessionName.startsWith(`${opts.projectName}:`) ||
-    normalizedSessionBase === normalizedProject
+    normalizedBases.includes(normalizedProject)
   );
 }
 
diff --git a/src/mcp/agent-docs.ts b/src/mcp/agent-docs.ts
index 11c2e4174..d7b15104a 100644
--- a/src/mcp/agent-docs.ts
+++ b/src/mcp/agent-docs.ts
@@ -166,7 +166,7 @@ export function renderAgentDocsSnippet(): string {
     DOC_MARKER_START,
     "## hack CLI (local dev + MCP)",
     "",
-    "Use `hack` as the single interface for local runtime orchestration (compose, DNS/TLS, logs, sessions).",
+    "Use `hack` as the single interface for local runtime orchestration (compose, DNS/TLS, logs, persistent project workspaces).",
     "",
     "Operating rules:",
     "- Prefer `hack` over raw `docker` / `docker compose` for project workflows.",
@@ -234,12 +234,12 @@ export function renderAgentDocsSnippet(): string {
     "- Use `lifecycle.up.before` for pre-start hooks and `lifecycle.processes` for long-running host tasks.",
     "- Inspect lifecycle status via `hack projects --details` and stream via `hack logs <service-or-process>`.",
     "",
-    "Sessions (mux-managed):",
-    "- Picker: `hack session`",
-    "- Start/attach: `hack session start <project>`",
-    "- Force isolated agent session: `hack session start <project> --new --name agent-1`",
-    '- Execute in session: `hack session exec <session> "<command>"`',
-    "- Stop session: `hack session stop <session>`",
+    "Workspaces (mux-managed):",
+    "- Picker: `hack session` for persistent project workspaces.",
+    "- Reuse/create: `hack session start <project>`",
+    "- Force isolated agent workspace: `hack session start <project> --new --name agent-1` (`<project>--agent-1`).",
+    '- Execute in workspace: `hack session exec <workspace> "<command>"`',
+    "- Stop workspace: `hack session stop <workspace>`",
     "",
     "Tickets (git-backed):",
     '- Create: `hack tickets create --title "..." --body-stdin`',
diff --git a/tests/project-views.test.ts b/tests/project-views.test.ts
index f0782c351..bc69cbbf2 100644
--- a/tests/project-views.test.ts
+++ b/tests/project-views.test.ts
@@ -308,7 +308,7 @@ test("buildProjectViews includes matching project sessions from tmux", async ()
         createdAt: 1_735_000_000,
       },
       {
-        name: "alpha:agent-1",
+        name: "alpha--agent-1",
         backend: "tmux",
         attached: false,
         path: join(alpha.repoRoot, "apps"),
@@ -337,7 +337,7 @@ test("buildProjectViews includes matching project sessions from tmux", async ()
   const alphaView = views.find((view) => view.name === "alpha");
   expect(alphaView?.sessions.map((session) => session.name)).toEqual([
     "alpha",
-    "alpha:agent-1",
+    "alpha--agent-1",
     "manual-scratch",
   ]);
   expect(alphaView?.sessions.map((session) => session.source)).toEqual([
@@ -400,7 +400,7 @@ test("buildProjectViews includes zellij sessions when session name matches proje
     includeUnregistered: false,
     muxSessions: [
       {
-        name: "alpha:research",
+        name: "alpha--research",
         backend: "zellij",
         attached: false,
         path: null,
@@ -412,7 +412,7 @@ test("buildProjectViews includes zellij sessions when session name matches proje
 
   const alphaView = views.find((view) => view.name === "alpha");
   expect(alphaView?.sessions.map((session) => session.name)).toEqual([
-    "alpha:research",
+    "alpha--research",
   ]);
   expect(alphaView?.sessions.map((session) => session.backend)).toEqual([
     "zellij",
diff --git a/tests/session-command.test.ts b/tests/session-command.test.ts
new file mode 100644
index 000000000..cdba2e6f8
--- /dev/null
+++ b/tests/session-command.test.ts
@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+
+import { __testOnlySessionCommand } from "../src/commands/session.ts";
+
+test("resolveWorkspaceProjectName maps isolated workspace names to the base project", () => {
+  expect(
+    __testOnlySessionCommand.resolveWorkspaceProjectName({
+      workspaceName: "alpha--agent-1",
+      projects: [
+        {
+          id: "project-1",
+          name: "alpha",
+          repoRoot: "/tmp/alpha",
+          projectDirName: ".hack",
+          projectDir: "/tmp/alpha/.hack",
+          createdAt: "2025-01-01T00:00:00.000Z",
+        },
+      ],
+    })
+  ).toBe("alpha");
+});
+
+test("resolveWorkspaceProjectName preserves direct workspace-to-project matches", () => {
+  expect(
+    __testOnlySessionCommand.resolveWorkspaceProjectName({
+      workspaceName: "alpha",
+      projects: [
+        {
+          id: "project-1",
+          name: "alpha",
+          repoRoot: "/tmp/alpha",
+          projectDirName: ".hack",
+          projectDir: "/tmp/alpha/.hack",
+          createdAt: "2025-01-01T00:00:00.000Z",
+        },
+      ],
+    })
+  ).toBe("alpha");
+});
+
+test("resolveNextIsolatedWorkspaceName creates siblings from the project base", () => {
+  expect(
+    __testOnlySessionCommand.resolveNextIsolatedWorkspaceName({
+      workspaceName: "alpha--agent-1",
+      sessions: [{ name: "alpha" }, { name: "alpha--2" }, { name: "alpha--3" }],
+    })
+  ).toBe("alpha--4");
+});
+
+test("resolveRunUpCwd uses the repo root instead of the .hack directory", () => {
+  expect(
+    __testOnlySessionCommand.resolveRunUpCwd({
+      project: {
+        id: "project-1",
+        name: "alpha",
+        repoRoot: "/tmp/alpha",
+        projectDirName: ".hack",
+        projectDir: "/tmp/alpha/.hack",
+        createdAt: "2025-01-01T00:00:00.000Z",
+      },
+    })
+  ).toBe("/tmp/alpha");
+});
diff --git a/tests/session-help.test.ts b/tests/session-help.test.ts
new file mode 100644
index 000000000..d7a520b25
--- /dev/null
+++ b/tests/session-help.test.ts
@@ -0,0 +1,48 @@
+import { expect, test } from "bun:test";
+
+import { renderHelpMarkdownForPath } from "../src/cli/help.ts";
+import { CLI_SPEC } from "../src/cli/spec.ts";
+
+test("hack session help explains persistent workspaces and tmux-first fallback", () => {
+  const help = renderHelpMarkdownForPath(CLI_SPEC, ["session"]);
+
+  expect(help).toContain("persistent project workspaces");
+  expect(help).toContain("tmux-first");
+  expect(help).toContain("zellij");
+  expect(help).toContain("`hack setup tmux`");
+});
+
+test("hack session start help explains reuse and isolated workspace creation", () => {
+  const help = renderHelpMarkdownForPath(CLI_SPEC, ["session", "start"]);
+
+  expect(help).toContain("Reuse the default project workspace");
+  expect(help).toContain("create an isolated long-running workspace");
+  expect(help).toContain("project--agent-1");
+  expect(help).toContain("--detach");
+});
+
+test("hack session attach and exec help explain workspace-oriented flows", () => {
+  const attachHelp = renderHelpMarkdownForPath(CLI_SPEC, ["session", "attach"]);
+  const execHelp = renderHelpMarkdownForPath(CLI_SPEC, ["session", "exec"]);
+
+  expect(attachHelp).toContain("Attach to a running tmux workspace by name");
+  expect(attachHelp).toContain("switches clients instead of nesting");
+  expect(execHelp).toContain("Queue a command in the workspace's active pane");
+  expect(execHelp).toContain("long-running agents");
+});
+
+test("hack setup tmux help documents tmux-first onboarding", () => {
+  const help = renderHelpMarkdownForPath(CLI_SPEC, ["setup", "tmux"]);
+
+  expect(help).toContain("recommended tmux binding");
+  expect(help).toContain("hack workspaces");
+  expect(help).toContain("--check");
+  expect(help).toContain("--remove");
+});
+
+test("hack ssh help uses workspace terminology", () => {
+  const help = renderHelpMarkdownForPath(CLI_SPEC, ["ssh"]);
+
+  expect(help).toContain("hack ssh [workspace]");
+  expect(help).toContain("Workspace to connect to");
+});
diff --git a/tests/session-names.test.ts b/tests/session-names.test.ts
new file mode 100644
index 000000000..d1cb46ca5
--- /dev/null
+++ b/tests/session-names.test.ts
@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+
+import {
+  buildSessionName,
+  getNextNumericSessionSuffix,
+  parseSessionBase,
+} from "../src/mux/session-names.ts";
+
+test("buildSessionName joins base and suffix with double dash", () => {
+  expect(buildSessionName({ base: "alpha", suffix: "agent-1" })).toBe(
+    "alpha--agent-1"
+  );
+});
+
+test("parseSessionBase strips double dash suffix", () => {
+  expect(parseSessionBase({ name: "alpha--agent-1" })).toBe("alpha");
+});
+
+test("getNextNumericSessionSuffix skips existing double dash names", () => {
+  expect(
+    getNextNumericSessionSuffix({
+      base: "alpha",
+      sessions: [{ name: "alpha" }, { name: "alpha--2" }, { name: "alpha--3" }],
+    })
+  ).toBe(4);
+});

From 6fa9c28cd7466a1b031863fc0c1762f8426fccb5 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:23:05 +0000
Subject: [PATCH 028/134] feat(auth): define org and team membership semantics

---
 docs/cli.md                                   | 442 ++++++++++++
 ...nd-organizations-admin-semantics-design.md | 356 ++++++++++
 ...-and-organizations-admin-semantics-plan.md | 330 +++++++++
 services/auth-broker/src/app.ts               |  18 +
 .../auth-broker/src/modules/orgs/plugin.ts    | 637 ++++++++++++++++++
 .../auth-broker/src/modules/orgs/service.ts   | 623 +++++++++++++++++
 .../tests/org-team-membership.test.ts         | 401 +++++++++++
 src/cli/help.ts                               |  14 +-
 src/cli/spec.ts                               |   4 +
 src/commands/auth.ts                          | 147 ++++
 src/commands/org.ts                           | 396 +++++++++++
 src/commands/team.ts                          | 404 +++++++++++
 src/lib/auth-broker-client.ts                 | 123 ++++
 tests/auth-command.test.ts                    | 128 ++++
 tests/cli-command.test.ts                     | 100 ++-
 tests/org-team-command.test.ts                | 375 +++++++++++
 16 files changed, 4495 insertions(+), 3 deletions(-)
 create mode 100644 docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md
 create mode 100644 docs/plans/2026-03-13-teams-and-organizations-admin-semantics-plan.md
 create mode 100644 services/auth-broker/src/modules/orgs/plugin.ts
 create mode 100644 services/auth-broker/src/modules/orgs/service.ts
 create mode 100644 services/auth-broker/tests/org-team-membership.test.ts
 create mode 100644 src/commands/org.ts
 create mode 100644 src/commands/team.ts
 create mode 100644 src/lib/auth-broker-client.ts
 create mode 100644 tests/org-team-command.test.ts

diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..f88d07d30 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -15,6 +15,9 @@ Run `hack help` or `hack help <command>` for interactive help.
 | Command | Summary | Group |
 | --- | --- | --- |
 | `hack global` | Manage machine-wide infra (DNS/TLS, Caddy proxy, logs) | Global |
+| `hack auth` | Manage Hack auth sessions and recipient-side invitations | Global |
+| `hack org` | Manage organizations and org-scoped membership lifecycle | Global |
+| `hack team` | Manage teams and team-scoped membership lifecycle | Global |
 | `hack projects` | Show all projects (registry + running docker compose) | Global |
 | `hack status` | Show project status (shortcut for `hack projects --details`) | Global |
 | `hack usage` | Show resource usage across running projects | Global |
@@ -119,6 +122,445 @@ Options:
 | `--install` | boolean | false | Run mkcert -install before generating certs |
 | `--out <dir>` | string | `~/.hack/certs` | Directory for generated cert/key |
 
+### hack auth
+
+Usage: `hack auth <subcommand>`
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `login` | Open a browser and sign in to Hack auth |
+| `logout` | Clear the locally stored Hack auth session |
+| `status` | Show whether Hack auth is configured locally |
+| `whoami` | Resolve the current Hack auth identity via the broker |
+| `invites` | List pending invitations for the authenticated user |
+| `invite` | Act on a specific invitation |
+
+#### hack auth login
+
+Usage: `hack auth login [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--no-open` | boolean | false | Print the browser URL instead of opening it automatically |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+| `--redirect <url>` | string | - | Return to this URL after browser sign-in finishes |
+
+#### hack auth logout
+
+Usage: `hack auth logout [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack auth status
+
+Usage: `hack auth status [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+#### hack auth whoami
+
+Usage: `hack auth whoami [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+#### hack auth invites
+
+Usage: `hack auth invites [options]`
+
+Recipient-side lifecycle command. Lists pending org and team invites that the authenticated user can accept or decline explicitly.
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+#### hack auth invite
+
+Usage: `hack auth invite <subcommand>`
+
+Recipient-side invitation actions. Acceptance and decline stay under `hack auth` so admins cannot implicitly activate access for someone else.
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `accept` | Accept a pending invitation and activate membership |
+| `decline` | Decline a pending invitation and mark it removed |
+
+#### hack auth invite accept
+
+Usage: `hack auth invite accept <invite-id> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `invite-id` | string | yes | Pending invite identifier |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+#### hack auth invite decline
+
+Usage: `hack auth invite decline <invite-id> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `invite-id` | string | yes | Pending invite identifier |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+### hack org
+
+Usage: `hack org <subcommand>`
+
+Admin-side organization surface. Org membership is the parent grant for team access.
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `create` | Create an organization without creating any teams implicitly |
+| `list` | List organizations visible to the authenticated user |
+| `show` | Show one organization and its current membership context |
+| `member` | Manage org memberships and invitation lifecycle |
+
+#### hack org create
+
+Usage: `hack org create <slug> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `slug` | string | yes | Organization slug |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--name <display-name>` | string | - | Human-friendly name to store alongside the slug |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack org list
+
+Usage: `hack org list [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack org show
+
+Usage: `hack org show <org> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `org` | string | yes | Organization slug or id |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack org member
+
+Usage: `hack org member <subcommand>`
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List org members and pending invites |
+| `invite` | Create pending org membership for an email address |
+| `add` | Grant active org membership immediately to an existing user |
+| `remove` | Remove org membership or cancel a pending org invite |
+
+Lifecycle semantics:
+
+- `invite` creates `pending`
+- `add` creates `active`
+- `remove` transitions `pending` or `active` membership to `removed`
+- Removing org access is expected to preview and cascade affected team memberships in the same org
+
+#### hack org member list
+
+Usage: `hack org member list <org> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `org` | string | yes | Organization slug or id |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--state <pending|active|removed|all>` | string | - | Filter membership rows by lifecycle state |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+Notes:
+
+- Default output should focus on actionable memberships rather than removed audit history.
+- Use `--state removed` or `--state all` to inspect audit-visible removals.
+
+#### hack org member invite
+
+Usage: `hack org member invite <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `org` | string | yes | Organization slug or id |
+| `target` | string | yes | Invitee email address |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--team <team>` | string | - | Seed one or more team-scoped invites alongside the org invite |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack org member add
+
+Usage: `hack org member add <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `org` | string | yes | Organization slug or id |
+| `target` | string | yes | Existing Hack user id, slug, or email |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+Notes:
+
+- `add` is immediate-access semantics and should fail when the target cannot be resolved to an existing Hack user.
+- Use `invite` instead when the person does not already have a Hack account.
+
+#### hack org member remove
+
+Usage: `hack org member remove <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `org` | string | yes | Organization slug or id |
+| `target` | string | yes | Membership target to revoke or cancel |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+### hack team
+
+Usage: `hack team <subcommand>`
+
+Admin-side team surface. Team membership is always nested under one organization.
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `create` | Create a team inside an existing organization |
+| `list` | List teams for one organization |
+| `show` | Show one team and its parent org context |
+| `member` | Manage team memberships and invitation lifecycle |
+
+#### hack team create
+
+Usage: `hack team create <slug> --org <org> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `slug` | string | yes | Team slug |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--name <display-name>` | string | - | Human-friendly name to store alongside the slug |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+Notes:
+
+- Team creation requires explicit org targeting and does not add members implicitly.
+
+#### hack team list
+
+Usage: `hack team list --org <org> [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack team show
+
+Usage: `hack team show <team> --org <org> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `team` | string | yes | Team slug or id |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack team member
+
+Usage: `hack team member <subcommand>`
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List team members and pending invites |
+| `invite` | Create pending team membership for an email address |
+| `add` | Grant active team membership immediately to an existing user |
+| `remove` | Remove team membership or cancel a pending team invite |
+
+Lifecycle semantics:
+
+- Team membership depends on active org membership in the same organization
+- `invite` creates `pending`
+- `add` creates `active`
+- `remove` transitions `pending` or `active` membership to `removed`
+- Removing team access does not change the parent org membership
+
+#### hack team member list
+
+Usage: `hack team member list <team> --org <org> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `team` | string | yes | Team slug or id |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--state <pending|active|removed|all>` | string | - | Filter membership rows by lifecycle state |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack team member invite
+
+Usage: `hack team member invite <team> --org <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `team` | string | yes | Team slug or id |
+| `target` | string | yes | Invitee email address |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+Notes:
+
+- Final implementation should pair this with an org invite when the recipient is not already an org member.
+
+#### hack team member add
+
+Usage: `hack team member add <team> --org <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `team` | string | yes | Team slug or id |
+| `target` | string | yes | Existing Hack user id, slug, or email |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack team member remove
+
+Usage: `hack team member remove <team> --org <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `team` | string | yes | Team slug or id |
+| `target` | string | yes | Membership target to revoke or cancel |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
 ### hack projects
 
 Usage: `hack projects [options]`
diff --git a/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md b/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md
new file mode 100644
index 000000000..b2dd7b596
--- /dev/null
+++ b/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md
@@ -0,0 +1,356 @@
+# Teams And Organizations Admin Semantics Design
+
+## Context
+
+Hack already has a real Hack-account model in flight:
+
+- `hack auth` establishes the local Hack session
+- broker-owned resources can already be scoped to `userId`, `organizationId`, and `teamId`
+- the auth broker already exposes active org/team metadata to CLI consumers
+
+What is still missing is the user-facing admin contract for:
+
+- creating organizations and teams
+- inviting or directly adding members
+- accepting, declining, and removing membership
+- explaining what happens when org and team access overlap
+
+Without that contract, implementation work will drift into hidden admin behavior, especially around team onboarding and org removal cascades.
+
+## Goals
+
+- Define a command surface that is explicit enough to implement directly.
+- Make pending, active, and removed membership states predictable.
+- Remove hidden privilege escalation and hidden access inheritance.
+- Keep the common onboarding path concise without making team access implicit.
+- Define UX rules for confirmations, audit visibility, and safe defaults.
+
+## Non-Goals
+
+- Full role and permission matrix design beyond minimal creator/admin defaults.
+- Billing, seat management, or SCIM-style bulk provisioning.
+- Team rename/archive or organization deletion flows.
+- Browser UI design for an admin console.
+
+## Approaches Considered
+
+### 1. Put everything under `hack auth`
+
+Examples:
+
+- `hack auth org create`
+- `hack auth team create`
+- `hack auth member invite`
+
+Pros:
+
+- Keeps account and admin flows under one top-level area.
+- Matches the fact that org/team data is tied to Hack auth.
+
+Cons:
+
+- Makes durable resources look like session subcommands.
+- Hurts discoverability for day-to-day admin work.
+- Becomes awkward once `org` and `team` have multiple sub-areas.
+
+### 2. Top-level `hack org` and `hack team` commands with invite acceptance under `hack auth` (recommended)
+
+Examples:
+
+- `hack org create`
+- `hack org member invite`
+- `hack team member remove`
+- `hack auth invite accept`
+
+Pros:
+
+- Keeps durable resources discoverable at the top level.
+- Keeps personal invitation acceptance under the existing identity/session area.
+- Maps cleanly to resource-local help and future growth.
+
+Cons:
+
+- Adds two new top-level command groups.
+- Requires clear docs for where invite acceptance lives.
+
+### 3. One generic `hack membership` surface
+
+Examples:
+
+- `hack membership invite --scope org:hack`
+- `hack membership remove --scope team:hack/cli`
+
+Pros:
+
+- Uniform implementation surface.
+- Easy to script mechanically.
+
+Cons:
+
+- Harder for humans to learn.
+- Pushes core semantics into flags instead of verbs.
+- Makes `hack help` less readable.
+
+## Recommended Design
+
+Adopt approach 2:
+
+- `hack org` owns organization resource management and org-scoped membership
+- `hack team` owns team resource management and team-scoped membership
+- `hack auth invite ...` owns recipient-side invite acceptance and decline
+
+This keeps resource management explicit while preserving a clear boundary:
+
+- admins act on orgs and teams
+- invited users act on their own invitations through `auth`
+
+## Resource Model
+
+### Organization
+
+An organization is the parent scope for one or more teams.
+
+Creating an organization:
+
+- creates the org record
+- makes the creator the initial active org owner/admin
+- does not create any teams implicitly
+
+### Team
+
+A team always belongs to exactly one organization.
+
+Creating a team:
+
+- requires an explicit `--org <org>`
+- creates the team record inside that organization
+- makes the creator an active team admin/manager for that team
+- does not invite or add any other members implicitly
+
+### Membership
+
+Membership is always scoped to exactly one resource:
+
+- organization membership
+- team membership
+
+Team membership depends on organization membership.
+
+That dependency is explicit:
+
+- an active team member must also be an active org member
+- a pending team invite for a non-org member must be created together with an org invite
+- removing org membership removes access to all teams in that org
+
+## Command Surface
+
+### Organization commands
+
+- `hack org create <slug> --name <display-name>`
+- `hack org list`
+- `hack org show <org>`
+- `hack org member list <org> [--state pending|active|removed|all]`
+- `hack org member invite <org> <email> [--team <team>...]`
+- `hack org member add <org> <user>`
+- `hack org member remove <org> <member>`
+
+### Team commands
+
+- `hack team create <slug> --org <org> --name <display-name>`
+- `hack team list --org <org>`
+- `hack team show <team> --org <org>`
+- `hack team member list <team> --org <org> [--state pending|active|removed|all]`
+- `hack team member invite <team> --org <org> <email>`
+- `hack team member add <team> --org <org> <user>`
+- `hack team member remove <team> --org <org> <member>`
+
+### Invite-recipient commands
+
+- `hack auth invites`
+- `hack auth invite accept <invite-id>`
+- `hack auth invite decline <invite-id>`
+
+## Command Semantics
+
+### `invite` means pending access
+
+`invite` is for an email-address target that may or may not already have a Hack account.
+
+Effects:
+
+- creates a membership in `pending`
+- does not grant access yet
+- sends or reissues an invitation link
+
+Safe default:
+
+- inviting an already-active member fails with an explicit `already_active` result
+- inviting an already-pending member fails with `already_pending` unless the user runs a future dedicated resend/reinvite command
+
+### `add` means immediate active access
+
+`add` is for a target that already resolves to an existing Hack user.
+
+Effects:
+
+- creates or reactivates the membership in `active`
+- grants access immediately
+- does not send an invite email
+
+Safe default:
+
+- `add` fails if the target cannot be resolved to an existing Hack user
+- the fallback guidance is to use `invite`
+
+### `remove` means access revoked or invite canceled
+
+`remove` is the admin-side verb for both pending and active memberships.
+
+Effects:
+
+- `pending -> removed`: cancels the invite before acceptance
+- `active -> removed`: revokes access immediately
+
+The CLI should say which path happened in plain language:
+
+- `Invite revoked`
+- `Access removed`
+
+### Recipient acceptance is explicit
+
+Only the invited user can move their own invite from `pending` to `active` through:
+
+- `hack auth invite accept <invite-id>`
+
+Decline is also explicit:
+
+- `hack auth invite decline <invite-id>`
+
+That transition results in:
+
+- `pending -> active` on accept
+- `pending -> removed` on decline
+
+## Membership Lifecycle Model
+
+### States
+
+- `pending`: membership has been proposed but does not grant access
+- `active`: membership grants access to the scope
+- `removed`: membership no longer grants access and remains visible in audit history
+
+### State transitions
+
+- `invite` creates `pending`
+- `add` creates `active`
+- `accept` moves `pending -> active`
+- `decline` moves `pending -> removed`
+- `remove` moves `pending -> removed`
+- `remove` moves `active -> removed`
+- `invite` on a previously removed membership creates a new pending invite attempt
+- `add` on a previously removed membership reactivates access immediately
+
+### Org and team coupling
+
+The rules for parent and child scopes are:
+
+- org membership is the parent grant
+- team membership is invalid without org membership
+- removing org membership cascades all pending and active team memberships in that org to `removed`
+- removing a team membership does not affect org membership
+
+### Recommended onboarding path
+
+The common case should be:
+
+- use `hack org member invite <org> <email> --team <team>...` for a new person
+- use `hack team member add <team> --org <org> <user>` only when the user is already an active org member
+
+That gives one explicit onboarding command for new people without requiring team commands to invent implicit org access.
+
+## Output And Audit Contract
+
+Every membership mutation should return the same core fields in human and JSON output:
+
+- `scopeType`: `organization` or `team`
+- `scopeId`
+- `memberUserId` when known
+- `memberEmail`
+- `state`
+- `previousState`
+- `changedBy`
+- `changedAt`
+- `reason`
+- `cascade` details when other memberships were affected
+
+### Audit visibility rules
+
+- default member lists show `pending` and `active`
+- `--state removed` or `--state all` exposes removed membership history
+- org member removal must show the team memberships removed by cascade
+- member detail views should show when a membership was invited, accepted, declined, or removed and by whom
+
+## Confirmation And Safety Rules
+
+### Confirmation
+
+Interactive destructive commands must show a preview before execution.
+
+Required confirmation cases:
+
+- removing an active org member
+- removing any org member when team memberships will cascade
+- removing multiple members in a future bulk flow
+
+Non-interactive automation must require `--yes` for destructive operations.
+
+### Safe defaults
+
+- no command may silently grant org access as a side effect of a team command
+- no command may silently delete audit history
+- no duplicate invite should be silently resent
+- no active member should be silently downgraded or re-added as part of another operation
+
+### Error guidance
+
+Errors should explain the next correct command, for example:
+
+- `user_not_found`: "Use \`hack org member invite\` for new users."
+- `org_membership_required`: "Add the user to the organization first, or use \`hack org member invite --team ...\`."
+- `already_pending`: "Use a future resend command or remove the pending invite first."
+
+## Minimal JSON Contract
+
+The machine-readable mutation payload should include:
+
+```json
+{
+  "ok": true,
+  "action": "invite",
+  "scopeType": "organization",
+  "scopeId": "hack",
+  "member": {
+    "userId": "user_123",
+    "email": "dev@example.com"
+  },
+  "membership": {
+    "state": "pending",
+    "previousState": null,
+    "changedAt": "2026-03-13T12:00:00.000Z",
+    "changedBy": "user_admin"
+  },
+  "cascade": {
+    "removedTeamMemberships": []
+  }
+}
+```
+
+The exact payload can grow, but these fields should remain stable enough for CLI, desktop, and MCP consumers.
+
+## Follow-On Work
+
+The next implementation slices should cover:
+
+1. broker persistence and APIs for org/team membership lifecycle
+2. CLI command registration and JSON output for `org`, `team`, and invite flows
+3. desktop/admin UX that uses the same lifecycle terms and confirmation rules
diff --git a/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-plan.md b/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-plan.md
new file mode 100644
index 000000000..34edb7550
--- /dev/null
+++ b/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-plan.md
@@ -0,0 +1,330 @@
+# Teams And Organizations Admin Semantics Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Turn the approved org/team admin semantics into explicit broker APIs, CLI commands, and shared lifecycle outputs that make membership changes trustworthy.
+
+**Architecture:** Add first-class organization, team, and membership lifecycle records to `auth-broker`, then expose them through top-level `hack org` and `hack team` command groups plus recipient-side `hack auth invite` actions. Keep invite acceptance separate from admin mutations, keep team membership dependent on org membership, and make destructive operations preview their cascades before execution.
+
+**Tech Stack:** Bun, TypeScript, Elysia, Better Auth, Drizzle, Hack CLI command framework, JSON CLI output, future macOS consumer surfaces.
+
+---
+
+### Task 1: Lock the semantics into docs and command expectations
+
+**Files:**
+
+- Modify: `docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md`
+- Modify: `docs/cli.md`
+- Test: `tests/cli-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add command-spec coverage that expects the future top-level command groups and their immediate subcommands to appear in CLI help metadata:
+
+- `hack org`
+- `hack team`
+- `hack auth invite`
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts
+```
+
+Expected: FAIL because the command groups do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Update help/spec plumbing and docs so the command surface is visible even before all mutation handlers are implemented.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md docs/cli.md tests/cli-command.test.ts src/cli/spec.ts src/commands/auth.ts src/commands/org.ts src/commands/team.ts
+git commit -m "feat: scaffold org and team command groups"
+```
+
+### Task 2: Add broker data model for org, team, and membership lifecycle
+
+**Files:**
+
+- Modify: `services/auth-broker/src/db/schema.ts`
+- Modify: `services/auth-broker/src/db/ensure-columns.ts`
+- Modify: `services/auth-broker/src/types.ts`
+- Test: `services/auth-broker/tests/better-auth-schema.test.ts`
+- Test: `services/auth-broker/tests/index.test.ts`
+
+**Step 1: Write the failing test**
+
+Add schema/store tests that expect first-class records for:
+
+- organizations
+- teams
+- memberships with `pending`, `active`, and `removed` states
+- invite metadata and removal audit fields
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test --cwd services/auth-broker tests/better-auth-schema.test.ts tests/index.test.ts
+```
+
+Expected: FAIL because the lifecycle tables/columns do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Add the smallest schema and types that can persist:
+
+- org records
+- team records with parent org id
+- membership records with state and audit timestamps
+- optional invite linkage for pending memberships
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test --cwd services/auth-broker tests/better-auth-schema.test.ts tests/index.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add services/auth-broker/src/db/schema.ts services/auth-broker/src/db/ensure-columns.ts services/auth-broker/src/types.ts services/auth-broker/tests/better-auth-schema.test.ts services/auth-broker/tests/index.test.ts
+git commit -m "feat(auth-broker): add org and membership lifecycle schema"
+```
+
+### Task 3: Add broker lifecycle services and route authorization
+
+**Files:**
+
+- Modify: `services/auth-broker/src/app.ts`
+- Create: `services/auth-broker/src/modules/orgs/plugin.ts`
+- Create: `services/auth-broker/src/modules/orgs/service.ts`
+- Create: `services/auth-broker/src/modules/teams/plugin.ts`
+- Create: `services/auth-broker/src/modules/teams/service.ts`
+- Create: `services/auth-broker/src/modules/memberships/plugin.ts`
+- Create: `services/auth-broker/src/modules/memberships/service.ts`
+- Test: `services/auth-broker/tests/index.test.ts`
+- Test: `services/auth-broker/tests/session-auth.test.ts`
+
+**Step 1: Write the failing test**
+
+Add route tests for:
+
+- org create
+- team create under an org
+- org member invite/add/remove
+- team member invite/add/remove
+- invite accept/decline
+- org removal cascade preview for child team memberships
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test --cwd services/auth-broker tests/index.test.ts tests/session-auth.test.ts
+```
+
+Expected: FAIL because these routes do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Implement the service layer and protected routes with the approved semantics:
+
+- `invite` creates `pending`
+- `add` creates `active`
+- `accept` moves `pending -> active`
+- `decline` and `remove` move membership to `removed`
+- org removal previews and then applies team cascades
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test --cwd services/auth-broker tests/index.test.ts tests/session-auth.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add services/auth-broker/src/app.ts services/auth-broker/src/modules/orgs/plugin.ts services/auth-broker/src/modules/orgs/service.ts services/auth-broker/src/modules/teams/plugin.ts services/auth-broker/src/modules/teams/service.ts services/auth-broker/src/modules/memberships/plugin.ts services/auth-broker/src/modules/memberships/service.ts services/auth-broker/tests/index.test.ts services/auth-broker/tests/session-auth.test.ts
+git commit -m "feat(auth-broker): add org team and membership lifecycle routes"
+```
+
+### Task 4: Add CLI command groups and shared mutation rendering
+
+**Files:**
+
+- Modify: `src/cli/spec.ts`
+- Modify: `src/commands/auth.ts`
+- Create: `src/commands/org.ts`
+- Create: `src/commands/team.ts`
+- Create: `src/lib/membership-output.ts`
+- Test: `tests/cli-command.test.ts`
+- Test: `tests/auth-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add CLI tests for:
+
+- `hack org create`
+- `hack org member invite`
+- `hack org member add`
+- `hack org member remove`
+- `hack team create`
+- `hack team member invite`
+- `hack team member add`
+- `hack team member remove`
+- `hack auth invites`
+- `hack auth invite accept`
+- `hack auth invite decline`
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts tests/auth-command.test.ts
+```
+
+Expected: FAIL because the command handlers do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Add CLI groups and formatters that:
+
+- call the broker lifecycle routes
+- print clear human summaries
+- emit stable JSON payloads with membership state transitions and cascade details
+- require `--yes` for destructive non-interactive removals
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts tests/auth-command.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/cli/spec.ts src/commands/auth.ts src/commands/org.ts src/commands/team.ts src/lib/membership-output.ts tests/cli-command.test.ts tests/auth-command.test.ts
+git commit -m "feat(cli): add org and team admin commands"
+```
+
+### Task 5: Add confirmation, cascade preview, and audit list behavior
+
+**Files:**
+
+- Modify: `src/commands/org.ts`
+- Modify: `src/commands/team.ts`
+- Modify: `services/auth-broker/src/modules/memberships/service.ts`
+- Test: `tests/cli-command.test.ts`
+- Test: `services/auth-broker/tests/index.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests that verify:
+
+- removing an org member previews affected team memberships
+- `--yes` bypasses interactive confirmation cleanly
+- member listing defaults to pending and active
+- `--state all` includes removed memberships with audit metadata
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts && bun test --cwd services/auth-broker tests/index.test.ts
+```
+
+Expected: FAIL until preview and audit behaviors are implemented.
+
+**Step 3: Write minimal implementation**
+
+Implement preview-first destructive behavior and consistent list filters without adding bulk operations or advanced role editing.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts && bun test --cwd services/auth-broker tests/index.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/commands/org.ts src/commands/team.ts services/auth-broker/src/modules/memberships/service.ts tests/cli-command.test.ts services/auth-broker/tests/index.test.ts
+git commit -m "feat: add membership confirmation and audit views"
+```
+
+### Task 6: Final verification and docs cleanup
+
+**Files:**
+
+- Modify: `docs/cli.md`
+- Verify only
+
+**Step 1: Run focused verification**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts tests/auth-command.test.ts
+bun test --cwd services/auth-broker tests/better-auth-schema.test.ts tests/index.test.ts tests/session-auth.test.ts
+```
+
+Expected: PASS
+
+**Step 2: Run repo quality gates**
+
+Run:
+
+```bash
+bun x ultracite fix
+bun x ultracite check
+bun test
+```
+
+Expected: PASS
+
+**Step 3: Sync follow-up docs**
+
+Make sure `docs/cli.md` and command help text match the shipped CLI behavior.
+
+**Step 4: Commit**
+
+```bash
+git add docs/cli.md
+git commit -m "docs: finalize org and team admin CLI semantics"
+```
diff --git a/services/auth-broker/src/app.ts b/services/auth-broker/src/app.ts
index 4a24fc68b..27bfcbbc4 100644
--- a/services/auth-broker/src/app.ts
+++ b/services/auth-broker/src/app.ts
@@ -30,6 +30,11 @@ import {
   InMemoryLinearSyncStore,
   type LinearSyncStore,
 } from "./modules/linear-sync-store/service.ts";
+import { createOrgsPlugin } from "./modules/orgs/plugin.ts";
+import {
+  InMemoryOrgTeamsStore,
+  type OrgTeamsStore,
+} from "./modules/orgs/service.ts";
 import { createProvidersPlugin } from "./modules/providers/plugin.ts";
 import { createSharedMiddlewarePlugin } from "./plugins/shared-middleware.ts";
 
@@ -40,6 +45,7 @@ export type CreateAuthBrokerAppOptions = {
   readonly linearSyncStore?: LinearSyncStore;
   readonly linearConnectionStore?: LinearConnectionStore;
   readonly linearAutosyncStore?: LinearAutosyncStore;
+  readonly orgTeamsStore?: OrgTeamsStore;
 };
 
 /**
@@ -52,6 +58,7 @@ export function createAuthBrokerApp({
   linearSyncStore: externalLinearSyncStore,
   linearConnectionStore: externalLinearConnectionStore,
   linearAutosyncStore: externalLinearAutosyncStore,
+  orgTeamsStore: externalOrgTeamsStore,
 }: CreateAuthBrokerAppOptions) {
   const flowStore =
     externalStore ?? new FlowStore({ filePath: config.flowStorePath });
@@ -63,6 +70,7 @@ export function createAuthBrokerApp({
     externalLinearConnectionStore ?? createDefaultLinearConnectionStore();
   const linearAutosyncStore =
     externalLinearAutosyncStore ?? createDefaultLinearAutosyncStore();
+  const orgTeamsStore = externalOrgTeamsStore ?? createDefaultOrgTeamsStore();
   let flowSweepTimer: ReturnType<typeof setInterval> | null = null;
 
   return new Elysia({
@@ -133,6 +141,12 @@ export function createAuthBrokerApp({
         betterAuthRuntime,
       })
     )
+    .use(
+      createOrgsPlugin({
+        store: orgTeamsStore,
+        betterAuthRuntime,
+      })
+    )
     .use(
       createLinearSyncStorePlugin({
         syncStore: linearSyncStore,
@@ -203,6 +217,10 @@ function createDefaultLinearAutosyncStore(): LinearAutosyncStore {
   }
 }
 
+function createDefaultOrgTeamsStore(): OrgTeamsStore {
+  return new InMemoryOrgTeamsStore();
+}
+
 /**
  * Identify route paths that are intentionally GET-only in broker v1.
  */
diff --git a/services/auth-broker/src/modules/orgs/plugin.ts b/services/auth-broker/src/modules/orgs/plugin.ts
new file mode 100644
index 000000000..35e16af87
--- /dev/null
+++ b/services/auth-broker/src/modules/orgs/plugin.ts
@@ -0,0 +1,637 @@
+import { Elysia, t } from "elysia";
+
+import type { BetterAuthRuntime } from "../../better-auth.ts";
+import { resolveBetterAuthSession } from "../better-auth/session.ts";
+import type { MembershipState, OrgTeamsStore } from "./service.ts";
+
+export function createOrgsPlugin(input: {
+  readonly store: OrgTeamsStore;
+  readonly betterAuthRuntime: BetterAuthRuntime;
+}) {
+  return new Elysia({
+    name: "hack-auth-broker.orgs",
+  })
+    .get("/v1/auth/orgs", async ({ request, set }) => {
+      const session = await requireSession({
+        runtime: input.betterAuthRuntime,
+        request,
+        set,
+      });
+      if (!session) {
+        return;
+      }
+      const organizations = await input.store.listOrganizations({
+        actorUserId: session.userId,
+      });
+      return { ok: true, organizations } as const;
+    })
+    .post(
+      "/v1/auth/orgs",
+      async ({ body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const created = await input.store.createOrganization({
+          slug: body.slug,
+          name: body.name ?? body.slug,
+          actorUserId: session.userId,
+          actorEmail: session.email,
+        });
+        return {
+          ok: true,
+          organization: created.organization,
+          membership: created.membership,
+        } as const;
+      },
+      {
+        body: t.Object({
+          slug: t.String(),
+          name: t.Optional(t.String()),
+        }),
+      }
+    )
+    .get(
+      "/v1/auth/orgs/:org",
+      async ({ params, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: params.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        return { ok: true, organization } as const;
+      },
+      { params: t.Object({ org: t.String() }) }
+    )
+    .get(
+      "/v1/auth/orgs/:org/members",
+      async ({ params, query, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: params.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        const memberships = await input.store.listMembers({
+          scope: "organization",
+          orgKey: params.org,
+          state: normalizeState({ value: query.state }),
+        });
+        return { ok: true, memberships } as const;
+      },
+      {
+        params: t.Object({ org: t.String() }),
+        query: t.Object({ state: t.Optional(t.String()) }),
+      }
+    )
+    .post(
+      "/v1/auth/orgs/:org/members/invite",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: params.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        const invited = await input.store.inviteMember({
+          scope: "organization",
+          orgKey: params.org,
+          target: body.target,
+          teamTargets: body.teams ?? [],
+        });
+        if (!invited) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        return {
+          ok: true,
+          invitation: invited.invitation,
+          membership: invited.membership,
+        } as const;
+      },
+      {
+        params: t.Object({ org: t.String() }),
+        body: t.Object({
+          target: t.String(),
+          teams: t.Optional(t.Array(t.String())),
+        }),
+      }
+    )
+    .post(
+      "/v1/auth/orgs/:org/members/add",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: params.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        const membership = await input.store.addMember({
+          scope: "organization",
+          orgKey: params.org,
+          target: body.target,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      {
+        params: t.Object({ org: t.String() }),
+        body: t.Object({ target: t.String() }),
+      }
+    )
+    .post(
+      "/v1/auth/orgs/:org/members/remove",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: params.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        const membership = await input.store.removeMember({
+          scope: "organization",
+          orgKey: params.org,
+          target: body.target,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "org_membership_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      {
+        params: t.Object({ org: t.String() }),
+        body: t.Object({ target: t.String() }),
+      }
+    )
+    .get(
+      "/v1/auth/teams",
+      async ({ query, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const teams = await input.store.listTeams({
+          orgKey: normalizeOptionalString(query.org),
+          actorUserId: session.userId,
+        });
+        return { ok: true, teams } as const;
+      },
+      { query: t.Object({ org: t.Optional(t.String()) }) }
+    )
+    .post(
+      "/v1/auth/teams",
+      async ({ body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: body.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        const created = await input.store.createTeam({
+          slug: body.slug,
+          name: body.name ?? body.slug,
+          orgKey: body.org,
+          actorUserId: session.userId,
+          actorEmail: session.email,
+        });
+        if (!created) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        return {
+          ok: true,
+          team: created.team,
+          membership: created.membership,
+        } as const;
+      },
+      {
+        body: t.Object({
+          slug: t.String(),
+          org: t.String(),
+          name: t.Optional(t.String()),
+        }),
+      }
+    )
+    .get(
+      "/v1/auth/teams/:team",
+      async ({ params, query, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const team = await input.store.getTeam({
+          teamKey: params.team,
+          orgKey: normalizeOptionalString(query.org),
+          actorUserId: session.userId,
+        });
+        if (!team) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        return { ok: true, team } as const;
+      },
+      {
+        params: t.Object({ team: t.String() }),
+        query: t.Object({ org: t.Optional(t.String()) }),
+      }
+    )
+    .get(
+      "/v1/auth/teams/:team/members",
+      async ({ params, query, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const orgKey = normalizeOptionalString(query.org);
+        if (!orgKey) {
+          set.status = 400;
+          return { ok: false, error: "org_required" } as const;
+        }
+        const team = await input.store.getTeam({
+          teamKey: params.team,
+          orgKey,
+          actorUserId: session.userId,
+        });
+        if (!team) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        const memberships = await input.store.listMembers({
+          scope: "team",
+          orgKey,
+          teamKey: params.team,
+          state: normalizeState({ value: query.state }),
+        });
+        return { ok: true, memberships } as const;
+      },
+      {
+        params: t.Object({ team: t.String() }),
+        query: t.Object({
+          org: t.Optional(t.String()),
+          state: t.Optional(t.String()),
+        }),
+      }
+    )
+    .post(
+      "/v1/auth/teams/:team/members/invite",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const team = await input.store.getTeam({
+          teamKey: params.team,
+          orgKey: body.org,
+          actorUserId: session.userId,
+        });
+        if (!team) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        const hasParentOrgMembership = await hasActiveParentOrgMembership({
+          store: input.store,
+          orgKey: body.org,
+          target: body.target,
+        });
+        if (!hasParentOrgMembership) {
+          set.status = 409;
+          return {
+            ok: false,
+            error: "team_member_requires_active_org_membership",
+          } as const;
+        }
+        const invited = await input.store.inviteMember({
+          scope: "team",
+          orgKey: body.org,
+          teamKey: params.team,
+          target: body.target,
+        });
+        if (!invited) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        return {
+          ok: true,
+          invitation: invited.invitation,
+          membership: invited.membership,
+        } as const;
+      },
+      {
+        params: t.Object({ team: t.String() }),
+        body: t.Object({
+          org: t.String(),
+          target: t.String(),
+        }),
+      }
+    )
+    .post(
+      "/v1/auth/teams/:team/members/add",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const team = await input.store.getTeam({
+          teamKey: params.team,
+          orgKey: body.org,
+          actorUserId: session.userId,
+        });
+        if (!team) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        const hasParentOrgMembership = await hasActiveParentOrgMembership({
+          store: input.store,
+          orgKey: body.org,
+          target: body.target,
+        });
+        if (!hasParentOrgMembership) {
+          set.status = 409;
+          return {
+            ok: false,
+            error: "team_member_requires_active_org_membership",
+          } as const;
+        }
+        const membership = await input.store.addMember({
+          scope: "team",
+          orgKey: body.org,
+          teamKey: params.team,
+          target: body.target,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      {
+        params: t.Object({ team: t.String() }),
+        body: t.Object({
+          org: t.String(),
+          target: t.String(),
+        }),
+      }
+    )
+    .post(
+      "/v1/auth/teams/:team/members/remove",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const team = await input.store.getTeam({
+          teamKey: params.team,
+          orgKey: body.org,
+          actorUserId: session.userId,
+        });
+        if (!team) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        const membership = await input.store.removeMember({
+          scope: "team",
+          orgKey: body.org,
+          teamKey: params.team,
+          target: body.target,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "team_membership_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      {
+        params: t.Object({ team: t.String() }),
+        body: t.Object({
+          org: t.String(),
+          target: t.String(),
+        }),
+      }
+    )
+    .get("/v1/auth/invitations", async ({ request, set }) => {
+      const session = await requireSession({
+        runtime: input.betterAuthRuntime,
+        request,
+        set,
+      });
+      if (!session) {
+        return;
+      }
+      if (!session.email) {
+        set.status = 400;
+        return { ok: false, error: "better_auth_email_required" } as const;
+      }
+      const invitations = await input.store.listInvitationsForEmail({
+        email: session.email,
+      });
+      return { ok: true, invitations } as const;
+    })
+    .post(
+      "/v1/auth/invitations/:inviteId/accept",
+      async ({ params, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        if (!session.email) {
+          set.status = 400;
+          return { ok: false, error: "better_auth_email_required" } as const;
+        }
+        const membership = await input.store.acceptInvitation({
+          inviteId: params.inviteId,
+          userId: session.userId,
+          email: session.email,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "invitation_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      { params: t.Object({ inviteId: t.String() }) }
+    )
+    .post(
+      "/v1/auth/invitations/:inviteId/decline",
+      async ({ params, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        if (!session.email) {
+          set.status = 400;
+          return { ok: false, error: "better_auth_email_required" } as const;
+        }
+        const membership = await input.store.declineInvitation({
+          inviteId: params.inviteId,
+          email: session.email,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "invitation_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      { params: t.Object({ inviteId: t.String() }) }
+    );
+}
+
+async function requireSession(input: {
+  readonly runtime: BetterAuthRuntime;
+  readonly request: Request;
+  readonly set: { status?: number };
+}) {
+  const session = await resolveBetterAuthSession({
+    runtime: input.runtime,
+    request: input.request,
+  });
+  if (session.enabled && !session.session) {
+    input.set.status = 401;
+    return null;
+  }
+  return session.session;
+}
+
+function normalizeOptionalString(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizeState(input: {
+  readonly value: string | undefined;
+}): MembershipState | "all" {
+  const normalized = normalizeOptionalString(input.value);
+  if (
+    normalized === "pending" ||
+    normalized === "active" ||
+    normalized === "removed" ||
+    normalized === "all"
+  ) {
+    return normalized;
+  }
+  return "all";
+}
+
+async function hasActiveParentOrgMembership(input: {
+  readonly store: OrgTeamsStore;
+  readonly orgKey: string;
+  readonly target: string;
+}): Promise<boolean> {
+  const memberships = await input.store.listMembers({
+    scope: "organization",
+    orgKey: input.orgKey,
+    state: "active",
+  });
+  const normalizedTarget = input.target.trim();
+  return memberships.some((membership) => {
+    const membershipTarget = membership.target.trim();
+    const membershipEmail = membership.email?.trim() ?? "";
+    return (
+      membershipTarget === normalizedTarget ||
+      membershipEmail === normalizedTarget
+    );
+  });
+}
diff --git a/services/auth-broker/src/modules/orgs/service.ts b/services/auth-broker/src/modules/orgs/service.ts
new file mode 100644
index 000000000..5993cd250
--- /dev/null
+++ b/services/auth-broker/src/modules/orgs/service.ts
@@ -0,0 +1,623 @@
+import { randomUUID } from "node:crypto";
+
+export type MembershipState = "pending" | "active" | "removed";
+
+export type OrganizationRecord = {
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+export type TeamRecord = {
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+  readonly organizationId: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+export type MembershipRecord = {
+  readonly id: string;
+  readonly scope: "organization" | "team";
+  readonly state: MembershipState;
+  readonly organizationId: string;
+  readonly teamId: string | null;
+  readonly userId: string | null;
+  readonly email: string | null;
+  readonly target: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+export type InvitationRecord = {
+  readonly id: string;
+  readonly scope: "organization" | "team";
+  readonly organizationId: string;
+  readonly teamId: string | null;
+  readonly email: string;
+  readonly status: "pending" | "accepted" | "removed";
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly teamTargets: readonly string[];
+};
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type OrgTeamsStore = {
+  readonly createOrganization: (input: {
+    readonly slug: string;
+    readonly name: string;
+    readonly actorUserId: string;
+    readonly actorEmail: string | null;
+  }) => MaybePromise<{
+    readonly organization: OrganizationRecord;
+    readonly membership: MembershipRecord;
+  }>;
+  readonly listOrganizations: (input: {
+    readonly actorUserId: string;
+  }) => MaybePromise<readonly OrganizationRecord[]>;
+  readonly getOrganization: (input: {
+    readonly orgKey: string;
+    readonly actorUserId: string;
+  }) => MaybePromise<OrganizationRecord | null>;
+  readonly createTeam: (input: {
+    readonly slug: string;
+    readonly name: string;
+    readonly orgKey: string;
+    readonly actorUserId: string;
+    readonly actorEmail: string | null;
+  }) => MaybePromise<{
+    readonly team: TeamRecord;
+    readonly membership: MembershipRecord;
+  } | null>;
+  readonly listTeams: (input: {
+    readonly orgKey: string | null;
+    readonly actorUserId: string;
+  }) => MaybePromise<readonly TeamRecord[]>;
+  readonly getTeam: (input: {
+    readonly teamKey: string;
+    readonly orgKey: string | null;
+    readonly actorUserId: string;
+  }) => MaybePromise<TeamRecord | null>;
+  readonly listMembers: (input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly state: MembershipState | "all";
+  }) => MaybePromise<readonly MembershipRecord[]>;
+  readonly inviteMember: (input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+    readonly teamTargets?: readonly string[];
+  }) => MaybePromise<{
+    readonly invitation: InvitationRecord;
+    readonly membership: MembershipRecord;
+  } | null>;
+  readonly addMember: (input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+  }) => MaybePromise<MembershipRecord | null>;
+  readonly removeMember: (input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+  }) => MaybePromise<MembershipRecord | null>;
+  readonly listInvitationsForEmail: (input: {
+    readonly email: string;
+  }) => MaybePromise<readonly InvitationRecord[]>;
+  readonly acceptInvitation: (input: {
+    readonly inviteId: string;
+    readonly userId: string;
+    readonly email: string;
+  }) => MaybePromise<MembershipRecord | null>;
+  readonly declineInvitation: (input: {
+    readonly inviteId: string;
+    readonly email: string;
+  }) => MaybePromise<MembershipRecord | null>;
+};
+
+export class InMemoryOrgTeamsStore implements OrgTeamsStore {
+  private readonly organizations = new Map<string, OrganizationRecord>();
+  private readonly teams = new Map<string, TeamRecord>();
+  private readonly activeMemberships = new Map<string, MembershipRecord>();
+  private readonly removedMemberships = new Map<string, MembershipRecord>();
+  private readonly invitations = new Map<string, InvitationRecord>();
+
+  createOrganization(input: {
+    readonly slug: string;
+    readonly name: string;
+    readonly actorUserId: string;
+    readonly actorEmail: string | null;
+  }): MaybePromise<{
+    readonly organization: OrganizationRecord;
+    readonly membership: MembershipRecord;
+  }> {
+    const now = new Date().toISOString();
+    const organization: OrganizationRecord = {
+      id: randomUUID(),
+      slug: input.slug.trim(),
+      name: input.name.trim() || input.slug.trim(),
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.organizations.set(organization.id, organization);
+    const membership = this.createActiveMembership({
+      scope: "organization",
+      organizationId: organization.id,
+      teamId: null,
+      userId: input.actorUserId,
+      email: input.actorEmail,
+      target: input.actorUserId,
+    });
+    return { organization, membership };
+  }
+
+  listOrganizations(input: {
+    readonly actorUserId: string;
+  }): MaybePromise<readonly OrganizationRecord[]> {
+    const allowedOrgIds = new Set(
+      [...this.activeMemberships.values()]
+        .filter(
+          (membership) =>
+            membership.scope === "organization" &&
+            membership.userId === input.actorUserId
+        )
+        .map((membership) => membership.organizationId)
+    );
+    return [...this.organizations.values()].filter((organization) =>
+      allowedOrgIds.has(organization.id)
+    );
+  }
+
+  getOrganization(input: {
+    readonly orgKey: string;
+    readonly actorUserId: string;
+  }): MaybePromise<OrganizationRecord | null> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return null;
+    }
+    const allowed = [...this.activeMemberships.values()].some(
+      (membership) =>
+        membership.scope === "organization" &&
+        membership.organizationId === organization.id &&
+        membership.userId === input.actorUserId
+    );
+    return allowed ? organization : null;
+  }
+
+  createTeam(input: {
+    readonly slug: string;
+    readonly name: string;
+    readonly orgKey: string;
+    readonly actorUserId: string;
+    readonly actorEmail: string | null;
+  }): MaybePromise<{
+    readonly team: TeamRecord;
+    readonly membership: MembershipRecord;
+  } | null> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return null;
+    }
+    const now = new Date().toISOString();
+    const team: TeamRecord = {
+      id: randomUUID(),
+      slug: input.slug.trim(),
+      name: input.name.trim() || input.slug.trim(),
+      organizationId: organization.id,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.teams.set(team.id, team);
+    const membership = this.createActiveMembership({
+      scope: "team",
+      organizationId: organization.id,
+      teamId: team.id,
+      userId: input.actorUserId,
+      email: input.actorEmail,
+      target: input.actorUserId,
+    });
+    return { team, membership };
+  }
+
+  listTeams(input: {
+    readonly orgKey: string | null;
+    readonly actorUserId: string;
+  }): MaybePromise<readonly TeamRecord[]> {
+    const allowedTeamIds = new Set(
+      [...this.activeMemberships.values()]
+        .filter(
+          (membership) =>
+            membership.scope === "team" &&
+            membership.userId === input.actorUserId
+        )
+        .map((membership) => membership.teamId)
+        .filter((teamId): teamId is string => typeof teamId === "string")
+    );
+    const organization = input.orgKey
+      ? this.findOrganization({ orgKey: input.orgKey })
+      : null;
+    return [...this.teams.values()].filter((team) => {
+      if (organization && team.organizationId !== organization.id) {
+        return false;
+      }
+      return allowedTeamIds.has(team.id);
+    });
+  }
+
+  getTeam(input: {
+    readonly teamKey: string;
+    readonly orgKey: string | null;
+    readonly actorUserId: string;
+  }): MaybePromise<TeamRecord | null> {
+    const team = this.findTeam({
+      teamKey: input.teamKey,
+      orgKey: input.orgKey,
+    });
+    if (!team) {
+      return null;
+    }
+    const allowed = [...this.activeMemberships.values()].some(
+      (membership) =>
+        membership.scope === "team" &&
+        membership.teamId === team.id &&
+        membership.userId === input.actorUserId
+    );
+    return allowed ? team : null;
+  }
+
+  listMembers(input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly state: MembershipState | "all";
+  }): MaybePromise<readonly MembershipRecord[]> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return [];
+    }
+    const team =
+      input.scope === "team"
+        ? this.findTeam({ teamKey: input.teamKey ?? "", orgKey: input.orgKey })
+        : null;
+    const pending = [...this.invitations.values()]
+      .filter((invitation) => invitation.status === "pending")
+      .filter(
+        (invitation) =>
+          invitation.scope === input.scope &&
+          invitation.organizationId === organization.id &&
+          invitation.teamId === (team?.id ?? null)
+      )
+      .map((invitation) => this.toPendingMembership({ invitation }));
+    const active = [...this.activeMemberships.values()].filter(
+      (membership) =>
+        membership.scope === input.scope &&
+        membership.organizationId === organization.id &&
+        membership.teamId === (team?.id ?? null)
+    );
+    const removed = [...this.removedMemberships.values()].filter(
+      (membership) =>
+        membership.scope === input.scope &&
+        membership.organizationId === organization.id &&
+        membership.teamId === (team?.id ?? null)
+    );
+    if (input.state === "pending") {
+      return pending;
+    }
+    if (input.state === "active") {
+      return active;
+    }
+    if (input.state === "removed") {
+      return removed;
+    }
+    return [...pending, ...active, ...removed];
+  }
+
+  inviteMember(input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+    readonly teamTargets?: readonly string[];
+  }): MaybePromise<{
+    readonly invitation: InvitationRecord;
+    readonly membership: MembershipRecord;
+  } | null> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return null;
+    }
+    const team =
+      input.scope === "team"
+        ? this.findTeam({ teamKey: input.teamKey ?? "", orgKey: input.orgKey })
+        : null;
+    if (input.scope === "team" && !team) {
+      return null;
+    }
+    const now = new Date().toISOString();
+    const invitation: InvitationRecord = {
+      id: randomUUID(),
+      scope: input.scope,
+      organizationId: organization.id,
+      teamId: team?.id ?? null,
+      email: input.target.trim(),
+      status: "pending",
+      createdAt: now,
+      updatedAt: now,
+      teamTargets: [...(input.teamTargets ?? [])],
+    };
+    this.invitations.set(invitation.id, invitation);
+    return {
+      invitation,
+      membership: this.toPendingMembership({ invitation }),
+    };
+  }
+
+  addMember(input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+  }): MaybePromise<MembershipRecord | null> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return null;
+    }
+    const team =
+      input.scope === "team"
+        ? this.findTeam({ teamKey: input.teamKey ?? "", orgKey: input.orgKey })
+        : null;
+    if (input.scope === "team" && !team) {
+      return null;
+    }
+    return this.createActiveMembership({
+      scope: input.scope,
+      organizationId: organization.id,
+      teamId: team?.id ?? null,
+      userId: input.target.trim(),
+      email: null,
+      target: input.target.trim(),
+    });
+  }
+
+  removeMember(input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+  }): MaybePromise<MembershipRecord | null> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return null;
+    }
+    const team =
+      input.scope === "team"
+        ? this.findTeam({ teamKey: input.teamKey ?? "", orgKey: input.orgKey })
+        : null;
+    if (input.scope === "team" && !team) {
+      return null;
+    }
+    const normalizedTarget = input.target.trim();
+    for (const invitation of this.invitations.values()) {
+      if (
+        invitation.status === "pending" &&
+        invitation.scope === input.scope &&
+        invitation.organizationId === organization.id &&
+        invitation.teamId === (team?.id ?? null) &&
+        invitation.email === normalizedTarget
+      ) {
+        const removed: InvitationRecord = {
+          ...invitation,
+          status: "removed",
+          updatedAt: new Date().toISOString(),
+        };
+        this.invitations.set(invitation.id, removed);
+        const membership = this.toRemovedMembership({
+          scope: invitation.scope,
+          organizationId: invitation.organizationId,
+          teamId: invitation.teamId,
+          userId: null,
+          email: invitation.email,
+          target: invitation.email,
+        });
+        this.removedMemberships.set(membership.id, membership);
+        return membership;
+      }
+    }
+
+    for (const [key, membership] of this.activeMemberships.entries()) {
+      if (
+        membership.scope === input.scope &&
+        membership.organizationId === organization.id &&
+        membership.teamId === (team?.id ?? null) &&
+        membership.target === normalizedTarget
+      ) {
+        this.activeMemberships.delete(key);
+        const removed = this.toRemovedMembership({
+          scope: membership.scope,
+          organizationId: membership.organizationId,
+          teamId: membership.teamId,
+          userId: membership.userId,
+          email: membership.email,
+          target: membership.target,
+        });
+        this.removedMemberships.set(removed.id, removed);
+        return removed;
+      }
+    }
+    return null;
+  }
+
+  listInvitationsForEmail(input: {
+    readonly email: string;
+  }): MaybePromise<readonly InvitationRecord[]> {
+    const normalizedEmail = input.email.trim();
+    return [...this.invitations.values()].filter(
+      (invitation) =>
+        invitation.status === "pending" && invitation.email === normalizedEmail
+    );
+  }
+
+  acceptInvitation(input: {
+    readonly inviteId: string;
+    readonly userId: string;
+    readonly email: string;
+  }): MaybePromise<MembershipRecord | null> {
+    const invitation = this.invitations.get(input.inviteId);
+    if (
+      !invitation ||
+      invitation.status !== "pending" ||
+      invitation.email !== input.email.trim()
+    ) {
+      return null;
+    }
+    this.invitations.set(invitation.id, {
+      ...invitation,
+      status: "accepted",
+      updatedAt: new Date().toISOString(),
+    });
+    return this.createActiveMembership({
+      scope: invitation.scope,
+      organizationId: invitation.organizationId,
+      teamId: invitation.teamId,
+      userId: input.userId,
+      email: input.email.trim(),
+      target: input.userId,
+    });
+  }
+
+  declineInvitation(input: {
+    readonly inviteId: string;
+    readonly email: string;
+  }): MaybePromise<MembershipRecord | null> {
+    const invitation = this.invitations.get(input.inviteId);
+    if (
+      !invitation ||
+      invitation.status !== "pending" ||
+      invitation.email !== input.email.trim()
+    ) {
+      return null;
+    }
+    this.invitations.set(invitation.id, {
+      ...invitation,
+      status: "removed",
+      updatedAt: new Date().toISOString(),
+    });
+    const removed = this.toRemovedMembership({
+      scope: invitation.scope,
+      organizationId: invitation.organizationId,
+      teamId: invitation.teamId,
+      userId: null,
+      email: invitation.email,
+      target: invitation.email,
+    });
+    this.removedMemberships.set(removed.id, removed);
+    return removed;
+  }
+
+  private findOrganization(input: {
+    readonly orgKey: string;
+  }): OrganizationRecord | null {
+    const key = input.orgKey.trim();
+    for (const organization of this.organizations.values()) {
+      if (organization.id === key || organization.slug === key) {
+        return organization;
+      }
+    }
+    return null;
+  }
+
+  private findTeam(input: {
+    readonly teamKey: string;
+    readonly orgKey: string | null;
+  }): TeamRecord | null {
+    const key = input.teamKey.trim();
+    const organization = input.orgKey
+      ? this.findOrganization({ orgKey: input.orgKey })
+      : null;
+    for (const team of this.teams.values()) {
+      if (!(team.id === key || team.slug === key)) {
+        continue;
+      }
+      if (organization && team.organizationId !== organization.id) {
+        continue;
+      }
+      return team;
+    }
+    return null;
+  }
+
+  private createActiveMembership(input: {
+    readonly scope: "organization" | "team";
+    readonly organizationId: string;
+    readonly teamId: string | null;
+    readonly userId: string | null;
+    readonly email: string | null;
+    readonly target: string;
+  }): MembershipRecord {
+    const now = new Date().toISOString();
+    const membership: MembershipRecord = {
+      id: randomUUID(),
+      scope: input.scope,
+      state: "active",
+      organizationId: input.organizationId,
+      teamId: input.teamId,
+      userId: input.userId,
+      email: input.email,
+      target: input.target,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.activeMemberships.set(membership.id, membership);
+    return membership;
+  }
+
+  private toPendingMembership(input: {
+    readonly invitation: InvitationRecord;
+  }): MembershipRecord {
+    return {
+      id: input.invitation.id,
+      scope: input.invitation.scope,
+      state: "pending",
+      organizationId: input.invitation.organizationId,
+      teamId: input.invitation.teamId,
+      userId: null,
+      email: input.invitation.email,
+      target: input.invitation.email,
+      createdAt: input.invitation.createdAt,
+      updatedAt: input.invitation.updatedAt,
+    };
+  }
+
+  private toRemovedMembership(input: {
+    readonly scope: "organization" | "team";
+    readonly organizationId: string;
+    readonly teamId: string | null;
+    readonly userId: string | null;
+    readonly email: string | null;
+    readonly target: string;
+  }): MembershipRecord {
+    const now = new Date().toISOString();
+    return {
+      id: randomUUID(),
+      scope: input.scope,
+      state: "removed",
+      organizationId: input.organizationId,
+      teamId: input.teamId,
+      userId: input.userId,
+      email: input.email,
+      target: input.target,
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+}
diff --git a/services/auth-broker/tests/org-team-membership.test.ts b/services/auth-broker/tests/org-team-membership.test.ts
new file mode 100644
index 000000000..3a57f86b0
--- /dev/null
+++ b/services/auth-broker/tests/org-team-membership.test.ts
@@ -0,0 +1,401 @@
+import { describe, expect, test } from "bun:test";
+
+import type { BetterAuthRuntime } from "../src/better-auth.ts";
+import { createAuthBrokerApp } from "../src/index.ts";
+import { InMemoryOrgTeamsStore } from "../src/modules/orgs/service.ts";
+
+type BetterAuthAuth = NonNullable<BetterAuthRuntime["auth"]>;
+type BetterAuthSession = Awaited<
+  ReturnType<BetterAuthAuth["api"]["getSession"]>
+>;
+
+function createTestConfig() {
+  return {
+    port: 0,
+    host: "127.0.0.1",
+    publicBaseUrl: "http://127.0.0.1:8080",
+    flowStorePath: ".data/test-oauth-flows.json",
+    githubClientId: "test-client-id",
+    githubClientSecret: "test-client-secret",
+    githubScopes: "repo,read:org",
+    githubAuthorizeUrl: "https://github.com/login/oauth/authorize",
+    githubTokenUrl: "https://github.com/login/oauth/access_token",
+    githubApiBaseUrl: "https://api.github.com",
+    githubRedirectUri: "http://127.0.0.1:8080/gh/callback",
+    betterAuthGitHubAutoProvisionUsers: false,
+    betterAuthLinearAutoProvisionUsers: false,
+    linearClientId: "linear-client-id",
+    linearClientSecret: "linear-client-secret",
+    linearActor: "app",
+    linearScopes: "read,write,app:mentionable,app:assignable",
+    linearAuthorizeUrl: "https://linear.app/oauth/authorize",
+    linearTokenUrl: "https://api.linear.app/oauth/token",
+    linearApiBaseUrl: "https://api.linear.app/graphql",
+    linearRedirectUri: "http://127.0.0.1:8080/linear/callback",
+    linearWebhookPath: "/linear/webhooks",
+    flowTtlMs: 60_000,
+    flowSweepIntervalMs: 60_000,
+  } as const;
+}
+
+function createBetterAuthRuntimeWithSession(
+  session: BetterAuthSession
+): BetterAuthRuntime {
+  return {
+    enabled: true,
+    socialProviders: [{ id: "github", label: "GitHub" }],
+    accountLinkingPolicy: {
+      requireVerifiedEmail: true,
+      allowDifferentEmails: false,
+      trustedProviders: [],
+    },
+    auth: {
+      api: {
+        getSession: async () => session,
+      },
+    } as unknown as BetterAuthAuth["api"],
+  } as unknown as BetterAuthRuntime;
+}
+
+function createSession(input?: {
+  readonly userId?: string;
+  readonly email?: string;
+  readonly activeOrganizationId?: string;
+  readonly activeTeamId?: string;
+}): BetterAuthSession {
+  return {
+    user: {
+      id: input?.userId ?? "user-123",
+      email: input?.email ?? "hack@example.com",
+      emailVerified: true,
+      name: "Hack User",
+    },
+    session: {
+      id: "sess-123",
+      userId: input?.userId ?? "user-123",
+      token: "session-token",
+      activeOrganizationId: input?.activeOrganizationId ?? null,
+      activeTeamId: input?.activeTeamId ?? null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      expiresAt: new Date(Date.now() + 60_000),
+    },
+  } as unknown as BetterAuthSession;
+}
+
+describe("org and team membership broker routes", () => {
+  test("org create and list return active ownership for the creator", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const app = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    const createResponse = await app.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+    expect(createResponse.status).toBe(200);
+    const created = (await createResponse.json()) as {
+      readonly ok: boolean;
+      readonly organization?: { readonly slug?: string };
+      readonly membership?: { readonly state?: string };
+    };
+    expect(created.ok).toBe(true);
+    expect(created.organization?.slug).toBe("hack");
+    expect(created.membership?.state).toBe("active");
+
+    const listResponse = await app.handle(
+      new Request("http://localhost/v1/auth/orgs")
+    );
+    expect(listResponse.status).toBe(200);
+    const listed = (await listResponse.json()) as {
+      readonly organizations?: ReadonlyArray<{ readonly slug?: string }>;
+    };
+    expect(
+      listed.organizations?.map((organization) => organization.slug)
+    ).toEqual(["hack"]);
+  });
+
+  test("team create, invite, and remove follow the expected state transitions", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const app = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    await app.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    const createTeamResponse = await app.handle(
+      new Request("http://localhost/v1/auth/teams", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "cli",
+          org: "hack",
+          name: "CLI",
+        }),
+      })
+    );
+    expect(createTeamResponse.status).toBe(200);
+
+    const addOrgMemberResponse = await app.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "person@example.com",
+        }),
+      })
+    );
+    expect(addOrgMemberResponse.status).toBe(200);
+
+    const inviteResponse = await app.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/invite", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "person@example.com",
+        }),
+      })
+    );
+    expect(inviteResponse.status).toBe(200);
+    const invitePayload = (await inviteResponse.json()) as {
+      readonly membership?: { readonly state?: string };
+    };
+    expect(invitePayload.membership?.state).toBe("pending");
+
+    const removeResponse = await app.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/remove", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "person@example.com",
+        }),
+      })
+    );
+    expect(removeResponse.status).toBe(200);
+    const removed = (await removeResponse.json()) as {
+      readonly membership?: { readonly state?: string };
+    };
+    expect(removed.membership?.state).toBe("removed");
+  });
+
+  test("org and team admin routes reject callers who are not active org members", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const ownerApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    const outsiderApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(
+        createSession({
+          userId: "user-999",
+          email: "outsider@example.com",
+        })
+      ),
+      orgTeamsStore: store,
+    });
+
+    const createTeamResponse = await outsiderApp.handle(
+      new Request("http://localhost/v1/auth/teams", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "cli",
+          org: "hack",
+          name: "CLI",
+        }),
+      })
+    );
+    expect(createTeamResponse.status).toBe(404);
+
+    const listMembersResponse = await outsiderApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members")
+    );
+    expect(listMembersResponse.status).toBe(404);
+  });
+
+  test("team membership changes require an active parent org membership", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const ownerApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "cli",
+          org: "hack",
+          name: "CLI",
+        }),
+      })
+    );
+
+    const addResponse = await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "user-456",
+        }),
+      })
+    );
+    expect(addResponse.status).toBe(409);
+
+    const inviteResponse = await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/invite", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "person@example.com",
+        }),
+      })
+    );
+    expect(inviteResponse.status).toBe(409);
+  });
+
+  test("recipient invitation accept and decline are scoped to the signed-in email", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const session = createSession({
+      userId: "user-123",
+      email: "person@example.com",
+    });
+    const app = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(session),
+      orgTeamsStore: store,
+    });
+
+    await app.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    const inviteResponse = await app.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/invite", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "person@example.com",
+        }),
+      })
+    );
+    const invitePayload = (await inviteResponse.json()) as {
+      readonly invitation?: { readonly id?: string };
+    };
+    const inviteId = invitePayload.invitation?.id;
+    expect(typeof inviteId).toBe("string");
+    if (!inviteId) {
+      return;
+    }
+
+    const listResponse = await app.handle(
+      new Request("http://localhost/v1/auth/invitations")
+    );
+    expect(listResponse.status).toBe(200);
+    const listed = (await listResponse.json()) as {
+      readonly invitations?: ReadonlyArray<{ readonly id?: string }>;
+    };
+    expect(listed.invitations?.[0]?.id).toBe(inviteId);
+
+    const acceptResponse = await app.handle(
+      new Request(`http://localhost/v1/auth/invitations/${inviteId}/accept`, {
+        method: "POST",
+      })
+    );
+    expect(acceptResponse.status).toBe(200);
+    const accepted = (await acceptResponse.json()) as {
+      readonly membership?: { readonly state?: string };
+    };
+    expect(accepted.membership?.state).toBe("active");
+
+    const secondInviteResponse = await app.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/invite", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "person@example.com",
+        }),
+      })
+    );
+    const secondInvitePayload = (await secondInviteResponse.json()) as {
+      readonly invitation?: { readonly id?: string };
+    };
+    const secondInviteId = secondInvitePayload.invitation?.id;
+    expect(typeof secondInviteId).toBe("string");
+    if (!secondInviteId) {
+      return;
+    }
+
+    const declineResponse = await app.handle(
+      new Request(
+        `http://localhost/v1/auth/invitations/${secondInviteId}/decline`,
+        {
+          method: "POST",
+        }
+      )
+    );
+    expect(declineResponse.status).toBe(200);
+    const declined = (await declineResponse.json()) as {
+      readonly membership?: { readonly state?: string };
+    };
+    expect(declined.membership?.state).toBe("removed");
+  });
+});
diff --git a/src/cli/help.ts b/src/cli/help.ts
index f58e64353..a7f4a5fc1 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -200,7 +200,7 @@ function renderCommandHelp(
   lines.push(`${invocation} — ${command.summary}`);
   lines.push("");
   lines.push("Usage:");
-  lines.push(`  ${invocation} [options]`);
+  lines.push(`  ${renderCommandUsage(invocation, command)}`);
   lines.push("");
 
   if (command.description) {
@@ -249,7 +249,7 @@ function renderCommandHelpMarkdown(
   lines.push("### Usage");
   lines.push("");
   lines.push("```bash");
-  lines.push(`${invocation} [options]`);
+  lines.push(renderCommandUsage(invocation, command));
   lines.push("```");
   lines.push("");
 
@@ -292,6 +292,16 @@ function renderCommandHelpMarkdown(
   return lines.join("\n");
 }
 
+function renderCommandUsage(
+  invocation: string,
+  command: AnyCommandSpec
+): string {
+  const hasSubcommands = command.subcommands.length > 0;
+  return hasSubcommands
+    ? `${invocation} <subcommand> [options]`
+    : `${invocation} [options]`;
+}
+
 function buildInvocation(
   cliName: string,
   path: readonly string[],
diff --git a/src/cli/spec.ts b/src/cli/spec.ts
index 079084d87..b7ea22cf9 100644
--- a/src/cli/spec.ts
+++ b/src/cli/spec.ts
@@ -16,6 +16,7 @@ import { linearCommand } from "../commands/linear.ts";
 import { logPipeCommand } from "../commands/log-pipe.ts";
 import { mcpCommand } from "../commands/mcp.ts";
 import { nodeCommand } from "../commands/node.ts";
+import { orgCommand } from "../commands/org.ts";
 import {
   downCommand,
   initCommand,
@@ -32,6 +33,7 @@ import { secretsCommand } from "../commands/secrets.ts";
 import { sessionCommand } from "../commands/session.ts";
 import { setupCommand } from "../commands/setup.ts";
 import { sshCommand } from "../commands/ssh.ts";
+import { teamCommand } from "../commands/team.ts";
 import { theCommand } from "../commands/the.ts";
 import { ticketsCommand } from "../commands/tickets.ts";
 import { tuiCommand } from "../commands/tui.ts";
@@ -56,6 +58,8 @@ export const CLI_SPEC = defineCli({
   commands: [
     globalCommand,
     authCommand,
+    orgCommand,
+    teamCommand,
     statusCommand,
     usageCommand,
     projectsCommand,
diff --git a/src/commands/auth.ts b/src/commands/auth.ts
index 243db4f65..3add2e937 100644
--- a/src/commands/auth.ts
+++ b/src/commands/auth.ts
@@ -1,6 +1,7 @@
 import type { CommandHandlerFor } from "../cli/command.ts";
 import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
 import { optJson } from "../cli/options.ts";
+import { requestHackAuthBroker } from "../lib/auth-broker-client.ts";
 import {
   deleteHackAuthSession,
   fetchHackAuthMe,
@@ -74,6 +75,55 @@ const whoamiSpec = defineCommand({
   subcommands: [] as const,
 } as const);
 
+const inviteIdPositionals = [{ name: "inviteId", required: true }] as const;
+
+const invitesSpec = defineCommand({
+  name: "invites",
+  summary: "List pending invitations for the authenticated user",
+  description:
+    "Recipient-side membership lifecycle entry point. Lists pending org and team invites so the authenticated user can accept or decline them explicitly.",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: [] as const,
+  subcommands: [] as const,
+} as const);
+
+const inviteAcceptSpec = defineCommand({
+  name: "accept",
+  summary: "Accept a pending invitation and activate membership",
+  description:
+    "Moves a pending org or team invite to active membership for the authenticated user.",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: inviteIdPositionals,
+  subcommands: [] as const,
+} as const);
+
+const inviteDeclineSpec = defineCommand({
+  name: "decline",
+  summary: "Decline a pending invitation and mark it removed",
+  description:
+    "Moves a pending org or team invite to the removed audit state for the authenticated user.",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: inviteIdPositionals,
+  subcommands: [] as const,
+} as const);
+
+const inviteSpec = defineCommand({
+  name: "invite",
+  summary: "Act on a specific invitation",
+  description:
+    "Recipient-side invitation actions. Acceptance and decline stay under auth so admins cannot implicitly activate access for someone else.",
+  group: "Global",
+  options: [] as const,
+  positionals: [] as const,
+  subcommands: [
+    withHandler(inviteAcceptSpec, handleAuthInviteAccept),
+    withHandler(inviteDeclineSpec, handleAuthInviteDecline),
+  ] as const,
+} as const);
+
 export const authCommand = defineCommand({
   name: "auth",
   summary: "Manage Hack auth sessions",
@@ -86,6 +136,8 @@ export const authCommand = defineCommand({
     withHandler(logoutSpec, handleAuthLogout),
     withHandler(statusSpec, handleAuthStatus),
     withHandler(whoamiSpec, handleAuthWhoami),
+    withHandler(invitesSpec, handleAuthInvites),
+    inviteSpec,
   ] as const,
 } as const);
 
@@ -93,6 +145,9 @@ type LoginSpec = typeof loginSpec;
 type LogoutSpec = typeof logoutSpec;
 type StatusSpec = typeof statusSpec;
 type WhoamiSpec = typeof whoamiSpec;
+type InvitesSpec = typeof invitesSpec;
+type InviteAcceptSpec = typeof inviteAcceptSpec;
+type InviteDeclineSpec = typeof inviteDeclineSpec;
 
 async function handleAuthLogin({
   args,
@@ -348,6 +403,98 @@ async function handleAuthWhoami({
   });
 }
 
+async function handleAuthInvites({
+  args,
+}: Parameters<CommandHandlerFor<InvitesSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: "/v1/auth/invitations",
+    brokerUrl: args.options.brokerUrl,
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      payload: {
+        brokerBaseUrl: response.brokerBaseUrl,
+        loginRequired: response.loginRequired,
+      },
+    });
+  }
+
+  const invitations = Array.isArray(response.value.invitations)
+    ? response.value.invitations
+    : [];
+  return writeSuccess({
+    json: args.options.json === true,
+    human:
+      invitations.length > 0
+        ? `Found ${invitations.length} pending Hack auth invitation${invitations.length === 1 ? "" : "s"}.`
+        : "No pending Hack auth invitations.",
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleAuthInviteAccept({
+  args,
+}: Parameters<CommandHandlerFor<InviteAcceptSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/invitations/${encodeURIComponent(args.positionals.inviteId)}/accept`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      payload: {
+        brokerBaseUrl: response.brokerBaseUrl,
+        loginRequired: response.loginRequired,
+      },
+    });
+  }
+
+  return writeSuccess({
+    json: args.options.json === true,
+    human: "Invitation accepted.",
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleAuthInviteDecline({
+  args,
+}: Parameters<CommandHandlerFor<InviteDeclineSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/invitations/${encodeURIComponent(args.positionals.inviteId)}/decline`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      payload: {
+        brokerBaseUrl: response.brokerBaseUrl,
+        loginRequired: response.loginRequired,
+      },
+    });
+  }
+
+  return writeSuccess({
+    json: args.options.json === true,
+    human: "Invitation declined.",
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
 function writeSuccess(input: {
   readonly json: boolean;
   readonly human: string;
diff --git a/src/commands/org.ts b/src/commands/org.ts
new file mode 100644
index 000000000..eba63e5b4
--- /dev/null
+++ b/src/commands/org.ts
@@ -0,0 +1,396 @@
+import type { CommandHandlerFor } from "../cli/command.ts";
+import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
+import { optJson } from "../cli/options.ts";
+import { requestHackAuthBroker } from "../lib/auth-broker-client.ts";
+import { logger } from "../ui/logger.ts";
+
+const optName = defineOption({
+  name: "name",
+  type: "string",
+  long: "--name",
+  valueHint: "<display-name>",
+  description: "Human-friendly name to store alongside the slug",
+} as const);
+
+const optState = defineOption({
+  name: "state",
+  type: "string",
+  long: "--state",
+  valueHint: "<pending|active|removed|all>",
+  description: "Filter membership rows by lifecycle state",
+} as const);
+
+const optTeam = defineOption({
+  name: "team",
+  type: "string",
+  long: "--team",
+  valueHint: "<team>",
+  description: "Seed one or more team-scoped invites alongside the org invite",
+} as const);
+
+const optBrokerUrl = defineOption({
+  name: "brokerUrl",
+  type: "string",
+  long: "--broker-url",
+  valueHint: "<url>",
+  description: "Override the Hack auth broker base URL",
+} as const);
+
+const orgPositionals = [{ name: "org", required: true }] as const;
+const orgSlugPositionals = [{ name: "slug", required: true }] as const;
+const orgMemberTargetPositionals = [
+  { name: "org", required: true },
+  { name: "target", required: true },
+] as const;
+
+const createSpec = defineCommand({
+  name: "create",
+  summary: "Create an organization without creating any teams implicitly",
+  description:
+    "Creates the organization record and makes the caller the initial active org admin.",
+  group: "Global",
+  options: [optName, optJson, optBrokerUrl] as const,
+  positionals: orgSlugPositionals,
+  subcommands: [] as const,
+} as const);
+
+const listSpec = defineCommand({
+  name: "list",
+  summary: "List organizations visible to the authenticated user",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: [] as const,
+  subcommands: [] as const,
+} as const);
+
+const showSpec = defineCommand({
+  name: "show",
+  summary: "Show one organization and its current membership context",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: orgPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberListSpec = defineCommand({
+  name: "list",
+  summary: "List org members and pending invites",
+  description:
+    "Defaults to actionable memberships; use --state removed or --state all for audit history.",
+  group: "Global",
+  options: [optState, optJson, optBrokerUrl] as const,
+  positionals: orgPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberInviteSpec = defineCommand({
+  name: "invite",
+  summary: "Create pending org membership for an email address",
+  description:
+    "Creates pending access only. Existing accounts still stay pending until the recipient accepts.",
+  group: "Global",
+  options: [optTeam, optJson, optBrokerUrl] as const,
+  positionals: orgMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberAddSpec = defineCommand({
+  name: "add",
+  summary: "Grant active org membership immediately to an existing user",
+  description:
+    "Requires a resolvable Hack user identity. Use invite when the target does not already exist.",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: orgMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberRemoveSpec = defineCommand({
+  name: "remove",
+  summary: "Remove org membership or cancel a pending org invite",
+  description:
+    "Admin-side revoke verb. Removing org access is expected to preview and cascade affected team memberships in the same org.",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: orgMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberSpec = defineCommand({
+  name: "member",
+  summary: "Manage org memberships and invitation lifecycle",
+  group: "Global",
+  options: [] as const,
+  positionals: [] as const,
+  subcommands: [
+    withHandler(memberListSpec, handleOrgMemberList),
+    withHandler(memberInviteSpec, handleOrgMemberInvite),
+    withHandler(memberAddSpec, handleOrgMemberAdd),
+    withHandler(memberRemoveSpec, handleOrgMemberRemove),
+  ] as const,
+} as const);
+
+export const orgCommand = defineCommand({
+  name: "org",
+  summary: "Manage organizations and org-scoped membership lifecycle",
+  description:
+    "Admin-side organization surface. Org membership is the parent grant for team access.",
+  group: "Global",
+  expandInRootHelp: true,
+  options: [] as const,
+  positionals: [] as const,
+  subcommands: [
+    withHandler(createSpec, handleOrgCreate),
+    withHandler(listSpec, handleOrgList),
+    withHandler(showSpec, handleOrgShow),
+    memberSpec,
+  ] as const,
+} as const);
+
+type CreateSpec = typeof createSpec;
+type ListSpec = typeof listSpec;
+type ShowSpec = typeof showSpec;
+type MemberListSpec = typeof memberListSpec;
+type MemberInviteSpec = typeof memberInviteSpec;
+type MemberAddSpec = typeof memberAddSpec;
+type MemberRemoveSpec = typeof memberRemoveSpec;
+
+async function handleOrgCreate({
+  args,
+}: Parameters<CommandHandlerFor<CreateSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: "/v1/auth/orgs",
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      slug: args.positionals.slug,
+      ...(args.options.name ? { name: args.options.name } : {}),
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Created organization ${args.positionals.slug}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgList({
+  args,
+}: Parameters<CommandHandlerFor<ListSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: "/v1/auth/orgs",
+    brokerUrl: args.options.brokerUrl,
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  const organizations = Array.isArray(response.value.organizations)
+    ? response.value.organizations
+    : [];
+  return writeSuccess({
+    json: args.options.json === true,
+    human:
+      organizations.length > 0
+        ? `Found ${organizations.length} organization${organizations.length === 1 ? "" : "s"}.`
+        : "No organizations found.",
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgShow({
+  args,
+}: Parameters<CommandHandlerFor<ShowSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/orgs/${encodeURIComponent(args.positionals.org)}`,
+    brokerUrl: args.options.brokerUrl,
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Loaded organization ${args.positionals.org}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgMemberList({
+  args,
+}: Parameters<CommandHandlerFor<MemberListSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/orgs/${encodeURIComponent(args.positionals.org)}/members`,
+    brokerUrl: args.options.brokerUrl,
+    query: {
+      state: args.options.state,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Loaded membership state for org ${args.positionals.org}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgMemberInvite({
+  args,
+}: Parameters<CommandHandlerFor<MemberInviteSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/orgs/${encodeURIComponent(args.positionals.org)}/members/invite`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+      ...(args.options.team ? { teams: [args.options.team] } : {}),
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Created pending org invite for ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgMemberAdd({
+  args,
+}: Parameters<CommandHandlerFor<MemberAddSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/orgs/${encodeURIComponent(args.positionals.org)}/members/add`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Granted org access to ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgMemberRemove({
+  args,
+}: Parameters<CommandHandlerFor<MemberRemoveSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/orgs/${encodeURIComponent(args.positionals.org)}/members/remove`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Removed org access for ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+function writeSuccess(input: {
+  readonly json: boolean;
+  readonly human: string;
+  readonly payload: Record<string, unknown>;
+}): number {
+  if (input.json) {
+    process.stdout.write(`${JSON.stringify(input.payload, null, 2)}\n`);
+  } else {
+    logger.success({ message: input.human });
+  }
+  return 0;
+}
+
+function writeFailure(input: {
+  readonly json: boolean;
+  readonly error: string;
+  readonly brokerBaseUrl: string;
+  readonly loginRequired: boolean;
+}): number {
+  if (input.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: false,
+          error: input.error,
+          brokerBaseUrl: input.brokerBaseUrl,
+          loginRequired: input.loginRequired,
+        },
+        null,
+        2
+      )}\n`
+    );
+  } else {
+    logger.error({ message: input.error });
+  }
+  return 1;
+}
diff --git a/src/commands/team.ts b/src/commands/team.ts
new file mode 100644
index 000000000..0c8c436a1
--- /dev/null
+++ b/src/commands/team.ts
@@ -0,0 +1,404 @@
+import type { CommandHandlerFor } from "../cli/command.ts";
+import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
+import { optJson } from "../cli/options.ts";
+import { requestHackAuthBroker } from "../lib/auth-broker-client.ts";
+import { logger } from "../ui/logger.ts";
+
+const optOrg = defineOption({
+  name: "org",
+  type: "string",
+  long: "--org",
+  valueHint: "<org>",
+  description: "Parent organization slug or id",
+} as const);
+
+const optName = defineOption({
+  name: "name",
+  type: "string",
+  long: "--name",
+  valueHint: "<display-name>",
+  description: "Human-friendly name to store alongside the slug",
+} as const);
+
+const optState = defineOption({
+  name: "state",
+  type: "string",
+  long: "--state",
+  valueHint: "<pending|active|removed|all>",
+  description: "Filter membership rows by lifecycle state",
+} as const);
+
+const optBrokerUrl = defineOption({
+  name: "brokerUrl",
+  type: "string",
+  long: "--broker-url",
+  valueHint: "<url>",
+  description: "Override the Hack auth broker base URL",
+} as const);
+
+const teamPositionals = [{ name: "team", required: true }] as const;
+const teamSlugPositionals = [{ name: "slug", required: true }] as const;
+const teamMemberTargetPositionals = [
+  { name: "team", required: true },
+  { name: "target", required: true },
+] as const;
+
+const createSpec = defineCommand({
+  name: "create",
+  summary: "Create a team inside an existing organization",
+  description:
+    "Requires an explicit --org value and does not add any members implicitly.",
+  group: "Global",
+  options: [optOrg, optName, optJson, optBrokerUrl] as const,
+  positionals: teamSlugPositionals,
+  subcommands: [] as const,
+} as const);
+
+const listSpec = defineCommand({
+  name: "list",
+  summary: "List teams for one organization",
+  group: "Global",
+  options: [optOrg, optJson, optBrokerUrl] as const,
+  positionals: [] as const,
+  subcommands: [] as const,
+} as const);
+
+const showSpec = defineCommand({
+  name: "show",
+  summary: "Show one team and its parent org context",
+  group: "Global",
+  options: [optOrg, optJson, optBrokerUrl] as const,
+  positionals: teamPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberListSpec = defineCommand({
+  name: "list",
+  summary: "List team members and pending invites",
+  description:
+    "Team membership depends on active org membership in the same organization.",
+  group: "Global",
+  options: [optOrg, optState, optJson, optBrokerUrl] as const,
+  positionals: teamPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberInviteSpec = defineCommand({
+  name: "invite",
+  summary: "Create pending team membership for an email address",
+  description:
+    "If the recipient is not already an org member, the final implementation must pair this with an org invite instead of granting access implicitly.",
+  group: "Global",
+  options: [optOrg, optJson, optBrokerUrl] as const,
+  positionals: teamMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberAddSpec = defineCommand({
+  name: "add",
+  summary: "Grant active team membership immediately to an existing user",
+  description:
+    "Requires both a resolvable Hack user and active org membership in the parent org.",
+  group: "Global",
+  options: [optOrg, optJson, optBrokerUrl] as const,
+  positionals: teamMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberRemoveSpec = defineCommand({
+  name: "remove",
+  summary: "Remove team membership or cancel a pending team invite",
+  description:
+    "Revokes only the team-level grant. Parent org membership stays unchanged.",
+  group: "Global",
+  options: [optOrg, optJson, optBrokerUrl] as const,
+  positionals: teamMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberSpec = defineCommand({
+  name: "member",
+  summary: "Manage team memberships and invitation lifecycle",
+  group: "Global",
+  options: [] as const,
+  positionals: [] as const,
+  subcommands: [
+    withHandler(memberListSpec, handleTeamMemberList),
+    withHandler(memberInviteSpec, handleTeamMemberInvite),
+    withHandler(memberAddSpec, handleTeamMemberAdd),
+    withHandler(memberRemoveSpec, handleTeamMemberRemove),
+  ] as const,
+} as const);
+
+export const teamCommand = defineCommand({
+  name: "team",
+  summary: "Manage teams and team-scoped membership lifecycle",
+  description:
+    "Admin-side team surface. Team membership is always nested under one organization.",
+  group: "Global",
+  expandInRootHelp: true,
+  options: [] as const,
+  positionals: [] as const,
+  subcommands: [
+    withHandler(createSpec, handleTeamCreate),
+    withHandler(listSpec, handleTeamList),
+    withHandler(showSpec, handleTeamShow),
+    memberSpec,
+  ] as const,
+} as const);
+
+type CreateSpec = typeof createSpec;
+type ListSpec = typeof listSpec;
+type ShowSpec = typeof showSpec;
+type MemberListSpec = typeof memberListSpec;
+type MemberInviteSpec = typeof memberInviteSpec;
+type MemberAddSpec = typeof memberAddSpec;
+type MemberRemoveSpec = typeof memberRemoveSpec;
+
+async function handleTeamCreate({
+  args,
+}: Parameters<CommandHandlerFor<CreateSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: "/v1/auth/teams",
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      slug: args.positionals.slug,
+      org: args.options.org,
+      ...(args.options.name ? { name: args.options.name } : {}),
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Created team ${args.positionals.slug}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamList({
+  args,
+}: Parameters<CommandHandlerFor<ListSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: "/v1/auth/teams",
+    brokerUrl: args.options.brokerUrl,
+    query: {
+      org: args.options.org,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  const teams = Array.isArray(response.value.teams) ? response.value.teams : [];
+  return writeSuccess({
+    json: args.options.json === true,
+    human:
+      teams.length > 0
+        ? `Found ${teams.length} team${teams.length === 1 ? "" : "s"}.`
+        : "No teams found.",
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamShow({
+  args,
+}: Parameters<CommandHandlerFor<ShowSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/teams/${encodeURIComponent(args.positionals.team)}`,
+    brokerUrl: args.options.brokerUrl,
+    query: {
+      org: args.options.org,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Loaded team ${args.positionals.team}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamMemberList({
+  args,
+}: Parameters<CommandHandlerFor<MemberListSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/teams/${encodeURIComponent(args.positionals.team)}/members`,
+    brokerUrl: args.options.brokerUrl,
+    query: {
+      org: args.options.org,
+      state: args.options.state,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Loaded membership state for team ${args.positionals.team}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamMemberInvite({
+  args,
+}: Parameters<CommandHandlerFor<MemberInviteSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/teams/${encodeURIComponent(args.positionals.team)}/members/invite`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+      org: args.options.org,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Created pending team invite for ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamMemberAdd({
+  args,
+}: Parameters<CommandHandlerFor<MemberAddSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/teams/${encodeURIComponent(args.positionals.team)}/members/add`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+      org: args.options.org,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Granted team access to ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamMemberRemove({
+  args,
+}: Parameters<CommandHandlerFor<MemberRemoveSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/teams/${encodeURIComponent(args.positionals.team)}/members/remove`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+      org: args.options.org,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Removed team access for ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+function writeSuccess(input: {
+  readonly json: boolean;
+  readonly human: string;
+  readonly payload: Record<string, unknown>;
+}): number {
+  if (input.json) {
+    process.stdout.write(`${JSON.stringify(input.payload, null, 2)}\n`);
+  } else {
+    logger.success({ message: input.human });
+  }
+  return 0;
+}
+
+function writeFailure(input: {
+  readonly json: boolean;
+  readonly error: string;
+  readonly brokerBaseUrl: string;
+  readonly loginRequired: boolean;
+}): number {
+  if (input.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: false,
+          error: input.error,
+          brokerBaseUrl: input.brokerBaseUrl,
+          loginRequired: input.loginRequired,
+        },
+        null,
+        2
+      )}\n`
+    );
+  } else {
+    logger.error({ message: input.error });
+  }
+  return 1;
+}
diff --git a/src/lib/auth-broker-client.ts b/src/lib/auth-broker-client.ts
new file mode 100644
index 000000000..d19f8f2d7
--- /dev/null
+++ b/src/lib/auth-broker-client.ts
@@ -0,0 +1,123 @@
+import {
+  type FetchLike,
+  loadHackAuthSession,
+  resolveHackAuthBrokerBaseUrl,
+} from "./auth-session.ts";
+
+type BrokerResult<T> =
+  | {
+      readonly ok: true;
+      readonly value: T;
+      readonly brokerBaseUrl: string;
+    }
+  | {
+      readonly ok: false;
+      readonly error: string;
+      readonly brokerBaseUrl: string;
+      readonly loginRequired: boolean;
+    };
+
+export async function requestHackAuthBroker(input: {
+  readonly path: string;
+  readonly method?: "GET" | "POST";
+  readonly query?: Record<string, string | undefined>;
+  readonly body?: Record<string, unknown>;
+  readonly brokerUrl?: string;
+  readonly fetchImpl?: FetchLike;
+}): Promise<BrokerResult<Record<string, unknown>>> {
+  const brokerBaseUrl = resolveHackAuthBrokerBaseUrl({
+    override: input.brokerUrl,
+  });
+  const stored = await loadHackAuthSession().catch(() => null);
+  const token = stored?.token?.trim() ?? "";
+  if (!token) {
+    return {
+      ok: false,
+      error:
+        "Hack auth login is required for broker-managed org and team commands. Run `hack auth login` and retry.",
+      brokerBaseUrl,
+      loginRequired: true,
+    };
+  }
+
+  const url = new URL(input.path, `${brokerBaseUrl}/`);
+  for (const [key, value] of Object.entries(input.query ?? {})) {
+    if (typeof value === "string" && value.trim()) {
+      url.searchParams.set(key, value.trim());
+    }
+  }
+
+  const fetchImpl: FetchLike =
+    input.fetchImpl ?? ((resource, init) => fetch(resource, init));
+
+  let response: Response;
+  try {
+    response = await fetchImpl(url.toString(), {
+      method: input.method ?? "GET",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${token}`,
+        ...(input.body ? { "content-type": "application/json" } : {}),
+      },
+      ...(input.body ? { body: JSON.stringify(input.body) } : {}),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Unable to reach Hack auth broker route ${input.path}: ${toErrorMessage(error)}`,
+      brokerBaseUrl,
+      loginRequired: false,
+    };
+  }
+
+  const body = await readJsonBody({ response });
+  if (!response.ok) {
+    const remoteError = readOptionalString(
+      (body as Record<string, unknown>).error
+    );
+    return {
+      ok: false,
+      error: remoteError
+        ? `Hack auth broker rejected ${input.path} (HTTP ${response.status}): ${remoteError}`
+        : `Hack auth broker rejected ${input.path} (HTTP ${response.status}).`,
+      brokerBaseUrl,
+      loginRequired: response.status === 401,
+    };
+  }
+
+  return {
+    ok: true,
+    value: isRecord(body) ? body : { ok: true },
+    brokerBaseUrl,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+async function readJsonBody(input: {
+  readonly response: Response;
+}): Promise<unknown> {
+  const text = await input.response.text();
+  if (!text.trim()) {
+    return {};
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+function readOptionalString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "Unknown error";
+}
diff --git a/tests/auth-command.test.ts b/tests/auth-command.test.ts
index fb116e028..8f1ee3888 100644
--- a/tests/auth-command.test.ts
+++ b/tests/auth-command.test.ts
@@ -512,6 +512,134 @@ test("auth status json includes a next step when login is required", async () =>
   expect(payload.nextStep).toContain("hack auth login");
 });
 
+test("auth invites lists pending invitations via the broker", async () => {
+  await writeStoredTokenEnvelope({
+    token: "hack-session-token",
+    expiresAt: "2099-03-06T19:00:00.000Z",
+  });
+
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/invitations") {
+      return Response.json({
+        ok: true,
+        invitations: [
+          {
+            id: "invite_123",
+            scope: "organization",
+            state: "pending",
+          },
+        ],
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["auth", "invites", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/invitations"
+  );
+  expect(fetchCalls[0]?.init?.method).toBe("GET");
+  expect(fetchCalls[0]?.init?.headers).toMatchObject({
+    authorization: "Bearer hack-session-token",
+  });
+  const payload = JSON.parse(result.stdout) as {
+    readonly invitations?: ReadonlyArray<{ readonly id?: string }>;
+  };
+  expect(payload.invitations?.[0]?.id).toBe("invite_123");
+});
+
+test("auth invite accept posts an activation request to the broker", async () => {
+  await writeStoredTokenEnvelope({
+    token: "hack-session-token",
+    expiresAt: "2099-03-06T19:00:00.000Z",
+  });
+
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (
+      url === "https://auth.hack.broker/v1/auth/invitations/invite_123/accept"
+    ) {
+      return Response.json({
+        ok: true,
+        membership: {
+          state: "active",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["auth", "invite", "accept", "invite_123", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/invitations/invite_123/accept"
+  );
+  expect(fetchCalls[0]?.init?.method).toBe("POST");
+  const payload = JSON.parse(result.stdout) as {
+    readonly membership?: { readonly state?: string };
+  };
+  expect(payload.membership?.state).toBe("active");
+});
+
+test("auth invite decline posts a removal request to the broker", async () => {
+  await writeStoredTokenEnvelope({
+    token: "hack-session-token",
+    expiresAt: "2099-03-06T19:00:00.000Z",
+  });
+
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (
+      url === "https://auth.hack.broker/v1/auth/invitations/invite_123/decline"
+    ) {
+      return Response.json({
+        ok: true,
+        membership: {
+          state: "removed",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["auth", "invite", "decline", "invite_123", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/invitations/invite_123/decline"
+  );
+  expect(fetchCalls[0]?.init?.method).toBe("POST");
+  const payload = JSON.parse(result.stdout) as {
+    readonly membership?: { readonly state?: string };
+  };
+  expect(payload.membership?.state).toBe("removed");
+});
+
 type CapturedRunResult = {
   readonly exitCode: number;
   readonly stdout: string;
diff --git a/tests/cli-command.test.ts b/tests/cli-command.test.ts
index be68608ee..0c8021d09 100644
--- a/tests/cli-command.test.ts
+++ b/tests/cli-command.test.ts
@@ -1,4 +1,4 @@
-import { expect, test } from "bun:test";
+import { afterEach, beforeEach, expect, test } from "bun:test";
 import {
   collectAllowedOptionNames,
   parseOptionsForCommand,
@@ -7,6 +7,35 @@ import {
 } from "../src/cli/command.ts";
 import { CLI_SPEC } from "../src/cli/spec.ts";
 
+type CapturedRunResult = {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+let originalSetupSyncMode: string | undefined;
+let originalLogger: string | undefined;
+
+beforeEach(() => {
+  originalSetupSyncMode = process.env.HACK_SETUP_SYNC_MODE;
+  originalLogger = process.env.HACK_LOGGER;
+  process.env.HACK_SETUP_SYNC_MODE = "off";
+  process.env.HACK_LOGGER = "console";
+});
+
+afterEach(() => {
+  if (originalSetupSyncMode !== undefined) {
+    process.env.HACK_SETUP_SYNC_MODE = originalSetupSyncMode;
+  } else {
+    process.env.HACK_SETUP_SYNC_MODE = undefined;
+  }
+  if (originalLogger !== undefined) {
+    process.env.HACK_LOGGER = originalLogger;
+  } else {
+    process.env.HACK_LOGGER = undefined;
+  }
+});
+
 test("resolveCommand finds nested subcommand and remaining positionals", () => {
   const resolved = resolveCommand(CLI_SPEC, ["global", "logs", "caddy"]);
   expect(resolved.command?.name).toBe("logs");
@@ -60,3 +89,72 @@ test("resolveCommand finds crash-capture command", () => {
   ]);
   expect(resolved.remainingPositionals).toEqual([]);
 });
+
+test("resolveCommand exposes org, team, and auth invite command paths", () => {
+  const orgResolved = resolveCommand(CLI_SPEC, ["org", "member", "invite"]);
+  expect(orgResolved.command?.name).toBe("invite");
+  expect(orgResolved.path.map((command) => command.name)).toEqual([
+    "org",
+    "member",
+    "invite",
+  ]);
+
+  const teamResolved = resolveCommand(CLI_SPEC, ["team", "member", "remove"]);
+  expect(teamResolved.command?.name).toBe("remove");
+  expect(teamResolved.path.map((command) => command.name)).toEqual([
+    "team",
+    "member",
+    "remove",
+  ]);
+
+  const authInviteResolved = resolveCommand(CLI_SPEC, [
+    "auth",
+    "invite",
+    "accept",
+  ]);
+  expect(authInviteResolved.command?.name).toBe("accept");
+  expect(authInviteResolved.path.map((command) => command.name)).toEqual([
+    "auth",
+    "invite",
+    "accept",
+  ]);
+});
+
+test("help shows subcommand usage for namespace commands", async () => {
+  const result = await runCliWithCapturedOutput(["help", "org"]);
+
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("Usage:");
+  expect(result.stdout).toContain("hack org <subcommand> [options]");
+  expect(result.stdout).toContain("hack org member");
+});
+
+async function runCliWithCapturedOutput(
+  args: readonly string[]
+): Promise<CapturedRunResult> {
+  let stdout = "";
+  let stderr = "";
+  const originalStdoutWrite = process.stdout.write;
+  const originalStderrWrite = process.stderr.write;
+
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdout +=
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    return true;
+  }) as typeof process.stdout.write;
+
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderr +=
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    return true;
+  }) as typeof process.stderr.write;
+
+  try {
+    const { runCli } = await import("../src/cli/run.ts");
+    const exitCode = await runCli(args);
+    return { exitCode, stdout, stderr };
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+}
diff --git a/tests/org-team-command.test.ts b/tests/org-team-command.test.ts
new file mode 100644
index 000000000..3ed0c58e0
--- /dev/null
+++ b/tests/org-team-command.test.ts
@@ -0,0 +1,375 @@
+import { afterAll, afterEach, beforeEach, expect, mock, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+type FetchCall = {
+  readonly url: string;
+  readonly init: RequestInit | undefined;
+};
+
+type CapturedRunResult = {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit
+) => Promise<Response>;
+
+let fetchCalls: FetchCall[] = [];
+let fetchImpl: FetchLike = async () =>
+  new Response("not mocked", {
+    status: 500,
+    headers: { "content-type": "text/plain" },
+  });
+
+const originalFetch = globalThis.fetch;
+const originalLogger = process.env.HACK_LOGGER;
+const originalGlobalConfigPath = process.env.HACK_GLOBAL_CONFIG_PATH;
+const originalSecretsKey = process.env.HACK_SECRETS_FILE_KEY;
+const originalHome = process.env.HOME;
+
+const { runCli } = await import("../src/cli/run.ts");
+const { saveHackAuthSession } = await import("../src/lib/auth-session.ts");
+
+let tempDir: string | null = null;
+let tempGlobalConfigPath: string | null = null;
+
+mock.module("../src/lib/os.ts", () => ({
+  isMac: () => process.platform === "darwin",
+  openUrl: async () => 0,
+}));
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-org-team-command-"));
+  tempGlobalConfigPath = resolve(tempDir, "hack.config.json");
+  process.env.HOME = tempDir;
+  process.env.HACK_GLOBAL_CONFIG_PATH = tempGlobalConfigPath;
+  process.env.HACK_SECRETS_FILE_KEY = "test-org-team-command-key";
+  process.env.HACK_LOGGER = "console";
+  process.env.HACK_AUTH_BROKER_URL = undefined;
+  process.env.HACK_SETUP_SYNC_MODE = "off";
+
+  await writeFile(
+    tempGlobalConfigPath,
+    `${JSON.stringify(
+      {
+        controlPlane: {
+          secrets: {
+            backend: "encrypted_file",
+            encryptedFile: {
+              path: resolve(tempDir, "secrets.enc.json"),
+            },
+          },
+        },
+      },
+      null,
+      2
+    )}\n`
+  );
+
+  await saveHackAuthSession({
+    session: {
+      token: "hack-session-token",
+      expiresAt: "2099-03-06T19:00:00.000Z",
+    },
+  });
+
+  fetchCalls = [];
+  fetchImpl = async () =>
+    new Response("not mocked", {
+      status: 500,
+      headers: { "content-type": "text/plain" },
+    });
+  globalThis.fetch = (async (
+    input: string | URL | Request,
+    init?: RequestInit
+  ) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    fetchCalls.push({ url, init });
+    return await fetchImpl(input, init);
+  }) as typeof globalThis.fetch;
+});
+
+afterEach(async () => {
+  globalThis.fetch = originalFetch;
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+  tempDir = null;
+  tempGlobalConfigPath = null;
+
+  if (originalLogger === undefined) {
+    process.env.HACK_LOGGER = undefined;
+  } else {
+    process.env.HACK_LOGGER = originalLogger;
+  }
+  if (originalGlobalConfigPath === undefined) {
+    process.env.HACK_GLOBAL_CONFIG_PATH = undefined;
+  } else {
+    process.env.HACK_GLOBAL_CONFIG_PATH = originalGlobalConfigPath;
+  }
+  if (originalSecretsKey === undefined) {
+    process.env.HACK_SECRETS_FILE_KEY = undefined;
+  } else {
+    process.env.HACK_SECRETS_FILE_KEY = originalSecretsKey;
+  }
+  if (originalHome === undefined) {
+    process.env.HOME = undefined;
+  } else {
+    process.env.HOME = originalHome;
+  }
+});
+
+afterAll(() => {
+  mock.restore();
+  globalThis.fetch = originalFetch;
+});
+
+test("org create posts slug and display name to the broker", async () => {
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/orgs") {
+      return Response.json({
+        ok: true,
+        organization: {
+          id: "org_123",
+          slug: "hack",
+          name: "Hack",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["org", "create", "hack", "--name", "Hack", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls).toHaveLength(1);
+  expect(fetchCalls[0]?.url).toBe("https://auth.hack.broker/v1/auth/orgs");
+  expect(fetchCalls[0]?.init?.method).toBe("POST");
+  expect(fetchCalls[0]?.init?.headers).toMatchObject({
+    authorization: "Bearer hack-session-token",
+  });
+  expect(JSON.parse(String(fetchCalls[0]?.init?.body))).toEqual({
+    slug: "hack",
+    name: "Hack",
+  });
+  const payload = JSON.parse(result.stdout) as {
+    readonly ok: boolean;
+    readonly organization?: { readonly slug?: string };
+  };
+  expect(payload.ok).toBe(true);
+  expect(payload.organization?.slug).toBe("hack");
+});
+
+test("org member invite posts pending membership request to the broker", async () => {
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/orgs/hack/members/invite") {
+      return Response.json({
+        ok: true,
+        membership: {
+          scope: "organization",
+          state: "pending",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["org", "member", "invite", "hack", "person@example.com", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/orgs/hack/members/invite"
+  );
+  expect(JSON.parse(String(fetchCalls[0]?.init?.body))).toEqual({
+    target: "person@example.com",
+  });
+  const payload = JSON.parse(result.stdout) as {
+    readonly membership?: { readonly state?: string };
+  };
+  expect(payload.membership?.state).toBe("pending");
+});
+
+test("org member invite includes seeded team targets in the broker request", async () => {
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/orgs/hack/members/invite") {
+      return Response.json({
+        ok: true,
+        membership: {
+          scope: "organization",
+          state: "pending",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: [
+      "org",
+      "member",
+      "invite",
+      "hack",
+      "person@example.com",
+      "--team",
+      "cli",
+      "--json",
+    ],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/orgs/hack/members/invite"
+  );
+  expect(JSON.parse(String(fetchCalls[0]?.init?.body))).toEqual({
+    target: "person@example.com",
+    teams: ["cli"],
+  });
+});
+
+test("team create posts to the broker with explicit org scope", async () => {
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/teams") {
+      return Response.json({
+        ok: true,
+        team: {
+          id: "team_123",
+          slug: "cli",
+          name: "CLI",
+          organizationId: "org_123",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["team", "create", "cli", "--org", "hack", "--name", "CLI", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe("https://auth.hack.broker/v1/auth/teams");
+  expect(JSON.parse(String(fetchCalls[0]?.init?.body))).toEqual({
+    slug: "cli",
+    org: "hack",
+    name: "CLI",
+  });
+  const payload = JSON.parse(result.stdout) as {
+    readonly team?: { readonly slug?: string };
+  };
+  expect(payload.team?.slug).toBe("cli");
+});
+
+test("team member remove posts the revoke action to the broker", async () => {
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/teams/cli/members/remove") {
+      return Response.json({
+        ok: true,
+        membership: {
+          scope: "team",
+          state: "removed",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: [
+      "team",
+      "member",
+      "remove",
+      "cli",
+      "user_123",
+      "--org",
+      "hack",
+      "--json",
+    ],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/teams/cli/members/remove"
+  );
+  expect(JSON.parse(String(fetchCalls[0]?.init?.body))).toEqual({
+    target: "user_123",
+    org: "hack",
+  });
+});
+
+async function runCliWithCapturedIo(input: {
+  readonly argv: readonly string[];
+}): Promise<CapturedRunResult> {
+  const stdoutChunks: string[] = [];
+  const stderrChunks: string[] = [];
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdoutChunks.push(
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8")
+    );
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderrChunks.push(
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8")
+    );
+    return true;
+  }) as typeof process.stderr.write;
+
+  try {
+    const exitCode = await runCli([...input.argv]);
+    return {
+      exitCode,
+      stdout: stdoutChunks.join(""),
+      stderr: stderrChunks.join(""),
+    };
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+}

From c72c436d774cbff67ec45f607dfcfa5653a90654 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:25:11 +0000
Subject: [PATCH 029/134] feat: add linear project artifact client support

---
 src/control-plane/extensions/linear/client.ts | 765 ++++++++++++++++++
 tests/linear-client.test.ts                   | 488 +++++++++++
 2 files changed, 1253 insertions(+)

diff --git a/src/control-plane/extensions/linear/client.ts b/src/control-plane/extensions/linear/client.ts
index 6581c8e75..15c68d46b 100644
--- a/src/control-plane/extensions/linear/client.ts
+++ b/src/control-plane/extensions/linear/client.ts
@@ -68,6 +68,51 @@ export type LinearIssue = {
   readonly parentIdentifier?: string;
 };
 
+export type LinearProjectDocument = {
+  readonly id: string;
+  readonly title: string;
+  readonly content?: string;
+  readonly url?: string;
+  readonly slugId?: string;
+  readonly sortOrder?: number;
+  readonly icon?: string;
+  readonly projectId?: string;
+  readonly projectName?: string;
+  readonly archived: boolean;
+  readonly createdAt?: string;
+  readonly updatedAt?: string;
+};
+
+export type LinearProjectMilestone = {
+  readonly id: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly sortOrder?: number;
+  readonly status?: string;
+  readonly targetDate?: string;
+  readonly projectId?: string;
+  readonly projectName?: string;
+  readonly archived: boolean;
+  readonly createdAt?: string;
+  readonly updatedAt?: string;
+};
+
+export type LinearProjectUpdate = {
+  readonly id: string;
+  readonly body: string;
+  readonly health?: string;
+  readonly url?: string;
+  readonly slugId?: string;
+  readonly projectId?: string;
+  readonly projectName?: string;
+  readonly userId?: string;
+  readonly userName?: string;
+  readonly userDisplayName?: string;
+  readonly userEmail?: string;
+  readonly createdAt: string;
+  readonly updatedAt?: string;
+};
+
 type LinearGraphQlError = {
   readonly message: string;
 };
@@ -134,6 +179,53 @@ export type LinearClient = {
     readonly first?: number;
     readonly after?: string;
   }) => Promise<LinearRequestResult<LinearProjectIssuePage>>;
+  readonly listProjectDocuments: (input: {
+    readonly projectId: string;
+    readonly first?: number;
+  }) => Promise<LinearRequestResult<readonly LinearProjectDocument[]>>;
+  readonly createProjectDocument: (input: {
+    readonly projectId: string;
+    readonly title: string;
+    readonly content?: string;
+    readonly icon?: string;
+    readonly sortOrder?: number;
+  }) => Promise<LinearRequestResult<LinearProjectDocument>>;
+  readonly updateProjectDocument: (input: {
+    readonly documentId: string;
+    readonly title?: string;
+    readonly content?: string;
+    readonly icon?: string;
+    readonly sortOrder?: number;
+  }) => Promise<LinearRequestResult<LinearProjectDocument>>;
+  readonly listProjectMilestones: (input: {
+    readonly projectId: string;
+    readonly first?: number;
+  }) => Promise<LinearRequestResult<readonly LinearProjectMilestone[]>>;
+  readonly createProjectMilestone: (input: {
+    readonly projectId: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly targetDate?: string;
+    readonly sortOrder?: number;
+  }) => Promise<LinearRequestResult<LinearProjectMilestone>>;
+  readonly updateProjectMilestone: (input: {
+    readonly milestoneId: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly targetDate?: string;
+    readonly sortOrder?: number;
+    readonly status?: string;
+  }) => Promise<LinearRequestResult<LinearProjectMilestone>>;
+  readonly listProjectUpdates: (input: {
+    readonly projectId: string;
+    readonly first?: number;
+  }) => Promise<LinearRequestResult<readonly LinearProjectUpdate[]>>;
+  readonly createProjectUpdate: (input: {
+    readonly projectId: string;
+    readonly body: string;
+    readonly health?: string;
+    readonly isDiffHidden?: boolean;
+  }) => Promise<LinearRequestResult<LinearProjectUpdate>>;
   readonly listTeamStates: (input: {
     readonly teamId: string;
   }) => Promise<LinearRequestResult<readonly LinearWorkflowState[]>>;
@@ -581,6 +673,420 @@ export function createLinearClient(input: {
       };
     },
 
+    listProjectDocuments: async (input) => {
+      const projectId = input.projectId.trim();
+      if (!projectId) {
+        return {
+          ok: false,
+          status: 400,
+          error: "Missing Linear project id.",
+        };
+      }
+      const first = normalizePositiveInt({
+        value: input.first,
+        fallback: DEFAULT_PAGE_SIZE,
+      });
+      const result = await request<{
+        readonly project?: unknown;
+      }>({
+        query: [
+          "query LinearProjectDocuments($projectId: String!, $first: Int!) {",
+          "  project(id: $projectId) {",
+          "    documents(first: $first) {",
+          "      nodes {",
+          documentFieldsSelection({ indent: "        " }),
+          "      }",
+          "    }",
+          "  }",
+          "}",
+        ].join("\n"),
+        variables: { projectId, first },
+      });
+      if (!result.ok) {
+        return result;
+      }
+      return {
+        ok: true,
+        data: parseProjectDocuments(result.data.project),
+      };
+    },
+
+    createProjectDocument: async (input) => {
+      const projectId = input.projectId.trim();
+      const title = input.title.trim();
+      if (!(projectId && title)) {
+        return {
+          ok: false,
+          status: 400,
+          error:
+            "Linear project document creation requires projectId and title.",
+        };
+      }
+      const mutationInput: Record<string, unknown> = {
+        projectId,
+        title,
+      };
+      if (input.content !== undefined) {
+        mutationInput.content = input.content;
+      }
+      if (input.icon !== undefined) {
+        mutationInput.icon = input.icon;
+      }
+      if (input.sortOrder !== undefined) {
+        mutationInput.sortOrder = input.sortOrder;
+      }
+
+      const result = await request<{
+        readonly documentCreate?: unknown;
+      }>({
+        query: [
+          "mutation LinearDocumentCreate($input: DocumentCreateInput!) {",
+          "  documentCreate(input: $input) {",
+          "    success",
+          "    document {",
+          documentFieldsSelection({ indent: "      " }),
+          "    }",
+          "  }",
+          "}",
+        ].join("\n"),
+        variables: {
+          input: mutationInput,
+        },
+      });
+      if (!result.ok) {
+        return result;
+      }
+      const document = parseDocumentMutation(result.data.documentCreate);
+      if (!document) {
+        return {
+          ok: false,
+          status: 500,
+          error: "Linear documentCreate payload missing document data.",
+        };
+      }
+      return {
+        ok: true,
+        data: document,
+      };
+    },
+
+    updateProjectDocument: async (input) => {
+      const documentId = input.documentId.trim();
+      if (!documentId) {
+        return {
+          ok: false,
+          status: 400,
+          error: "Missing Linear document id.",
+        };
+      }
+      const mutationInput: Record<string, unknown> = {};
+      if (input.title !== undefined) {
+        mutationInput.title = input.title;
+      }
+      if (input.content !== undefined) {
+        mutationInput.content = input.content;
+      }
+      if (input.icon !== undefined) {
+        mutationInput.icon = input.icon;
+      }
+      if (input.sortOrder !== undefined) {
+        mutationInput.sortOrder = input.sortOrder;
+      }
+
+      const result = await request<{
+        readonly documentUpdate?: unknown;
+      }>({
+        query: [
+          "mutation LinearDocumentUpdate($id: String!, $input: DocumentUpdateInput!) {",
+          "  documentUpdate(id: $id, input: $input) {",
+          "    success",
+          "    document {",
+          documentFieldsSelection({ indent: "      " }),
+          "    }",
+          "  }",
+          "}",
+        ].join("\n"),
+        variables: {
+          id: documentId,
+          input: mutationInput,
+        },
+      });
+      if (!result.ok) {
+        return result;
+      }
+      const document = parseDocumentMutation(result.data.documentUpdate);
+      if (!document) {
+        return {
+          ok: false,
+          status: 500,
+          error: "Linear documentUpdate payload missing document data.",
+        };
+      }
+      return {
+        ok: true,
+        data: document,
+      };
+    },
+
+    listProjectMilestones: async (input) => {
+      const projectId = input.projectId.trim();
+      if (!projectId) {
+        return {
+          ok: false,
+          status: 400,
+          error: "Missing Linear project id.",
+        };
+      }
+      const first = normalizePositiveInt({
+        value: input.first,
+        fallback: DEFAULT_PAGE_SIZE,
+      });
+      const result = await request<{
+        readonly project?: unknown;
+      }>({
+        query: [
+          "query LinearProjectMilestones($projectId: String!, $first: Int!) {",
+          "  project(id: $projectId) {",
+          "    projectMilestones(first: $first) {",
+          "      nodes {",
+          projectMilestoneFieldsSelection({ indent: "        " }),
+          "      }",
+          "    }",
+          "  }",
+          "}",
+        ].join("\n"),
+        variables: { projectId, first },
+      });
+      if (!result.ok) {
+        return result;
+      }
+      return {
+        ok: true,
+        data: parseProjectMilestones(result.data.project),
+      };
+    },
+
+    createProjectMilestone: async (input) => {
+      const projectId = input.projectId.trim();
+      const name = input.title.trim();
+      if (!(projectId && name)) {
+        return {
+          ok: false,
+          status: 400,
+          error:
+            "Linear project milestone creation requires projectId and title.",
+        };
+      }
+      const mutationInput: Record<string, unknown> = {
+        projectId,
+        name,
+      };
+      if (input.description !== undefined) {
+        mutationInput.description = input.description;
+      }
+      if (input.targetDate !== undefined) {
+        mutationInput.targetDate = input.targetDate;
+      }
+      if (input.sortOrder !== undefined) {
+        mutationInput.sortOrder = input.sortOrder;
+      }
+
+      const result = await request<{
+        readonly projectMilestoneCreate?: unknown;
+      }>({
+        query: [
+          "mutation LinearProjectMilestoneCreate($input: ProjectMilestoneCreateInput!) {",
+          "  projectMilestoneCreate(input: $input) {",
+          "    success",
+          "    projectMilestone {",
+          projectMilestoneFieldsSelection({ indent: "      " }),
+          "    }",
+          "  }",
+          "}",
+        ].join("\n"),
+        variables: {
+          input: mutationInput,
+        },
+      });
+      if (!result.ok) {
+        return result;
+      }
+      const milestone = parseProjectMilestoneMutation(
+        result.data.projectMilestoneCreate
+      );
+      if (!milestone) {
+        return {
+          ok: false,
+          status: 500,
+          error:
+            "Linear projectMilestoneCreate payload missing milestone data.",
+        };
+      }
+      return {
+        ok: true,
+        data: milestone,
+      };
+    },
+
+    updateProjectMilestone: async (input) => {
+      const milestoneId = input.milestoneId.trim();
+      if (!milestoneId) {
+        return {
+          ok: false,
+          status: 400,
+          error: "Missing Linear project milestone id.",
+        };
+      }
+      const mutationInput: Record<string, unknown> = {};
+      if (input.title !== undefined) {
+        mutationInput.name = input.title;
+      }
+      if (input.description !== undefined) {
+        mutationInput.description = input.description;
+      }
+      if (input.targetDate !== undefined) {
+        mutationInput.targetDate = input.targetDate;
+      }
+      if (input.sortOrder !== undefined) {
+        mutationInput.sortOrder = input.sortOrder;
+      }
+      if (input.status !== undefined) {
+        mutationInput.status = input.status;
+      }
+
+      const result = await request<{
+        readonly projectMilestoneUpdate?: unknown;
+      }>({
+        query: [
+          "mutation LinearProjectMilestoneUpdate($id: String!, $input: ProjectMilestoneUpdateInput!) {",
+          "  projectMilestoneUpdate(id: $id, input: $input) {",
+          "    success",
+          "    projectMilestone {",
+          projectMilestoneFieldsSelection({ indent: "      " }),
+          "    }",
+          "  }",
+          "}",
+        ].join("\n"),
+        variables: {
+          id: milestoneId,
+          input: mutationInput,
+        },
+      });
+      if (!result.ok) {
+        return result;
+      }
+      const milestone = parseProjectMilestoneMutation(
+        result.data.projectMilestoneUpdate
+      );
+      if (!milestone) {
+        return {
+          ok: false,
+          status: 500,
+          error:
+            "Linear projectMilestoneUpdate payload missing milestone data.",
+        };
+      }
+      return {
+        ok: true,
+        data: milestone,
+      };
+    },
+
+    listProjectUpdates: async (input) => {
+      const projectId = input.projectId.trim();
+      if (!projectId) {
+        return {
+          ok: false,
+          status: 400,
+          error: "Missing Linear project id.",
+        };
+      }
+      const first = normalizePositiveInt({
+        value: input.first,
+        fallback: DEFAULT_PAGE_SIZE,
+      });
+      const result = await request<{
+        readonly project?: unknown;
+      }>({
+        query: [
+          "query LinearProjectUpdates($projectId: String!, $first: Int!) {",
+          "  project(id: $projectId) {",
+          "    projectUpdates(first: $first) {",
+          "      nodes {",
+          projectUpdateFieldsSelection({ indent: "        " }),
+          "      }",
+          "    }",
+          "  }",
+          "}",
+        ].join("\n"),
+        variables: { projectId, first },
+      });
+      if (!result.ok) {
+        return result;
+      }
+      return {
+        ok: true,
+        data: parseProjectUpdates(result.data.project),
+      };
+    },
+
+    createProjectUpdate: async (input) => {
+      const projectId = input.projectId.trim();
+      const body = input.body.trim();
+      if (!(projectId && body)) {
+        return {
+          ok: false,
+          status: 400,
+          error: "Linear project update creation requires projectId and body.",
+        };
+      }
+      const mutationInput: Record<string, unknown> = {
+        projectId,
+        body,
+      };
+      if (input.health !== undefined) {
+        mutationInput.health = input.health;
+      }
+      if (input.isDiffHidden !== undefined) {
+        mutationInput.isDiffHidden = input.isDiffHidden;
+      }
+
+      const result = await request<{
+        readonly projectUpdateCreate?: unknown;
+      }>({
+        query: [
+          "mutation LinearProjectUpdateCreate($input: ProjectUpdateCreateInput!) {",
+          "  projectUpdateCreate(input: $input) {",
+          "    success",
+          "    projectUpdate {",
+          projectUpdateFieldsSelection({ indent: "      " }),
+          "    }",
+          "  }",
+          "}",
+        ].join("\n"),
+        variables: {
+          input: mutationInput,
+        },
+      });
+      if (!result.ok) {
+        return result;
+      }
+      const update = parseProjectUpdateMutation(
+        result.data.projectUpdateCreate
+      );
+      if (!update) {
+        return {
+          ok: false,
+          status: 500,
+          error: "Linear projectUpdateCreate payload missing update data.",
+        };
+      }
+      return {
+        ok: true,
+        data: update,
+      };
+    },
+
     listTeamStates: async ({ teamId }) => {
       const id = teamId.trim();
       if (!id) {
@@ -781,6 +1287,66 @@ export function createLinearClient(input: {
   };
 }
 
+function documentFieldsSelection(input: { readonly indent: string }): string {
+  return [
+    `${input.indent}id`,
+    `${input.indent}title`,
+    `${input.indent}content`,
+    `${input.indent}url`,
+    `${input.indent}slugId`,
+    `${input.indent}sortOrder`,
+    `${input.indent}icon`,
+    `${input.indent}trashed`,
+    `${input.indent}createdAt`,
+    `${input.indent}updatedAt`,
+    `${input.indent}project {`,
+    `${input.indent}  id`,
+    `${input.indent}  name`,
+    `${input.indent}}`,
+  ].join("\n");
+}
+
+function projectMilestoneFieldsSelection(input: {
+  readonly indent: string;
+}): string {
+  return [
+    `${input.indent}id`,
+    `${input.indent}name`,
+    `${input.indent}description`,
+    `${input.indent}sortOrder`,
+    `${input.indent}status`,
+    `${input.indent}targetDate`,
+    `${input.indent}archivedAt`,
+    `${input.indent}createdAt`,
+    `${input.indent}updatedAt`,
+    `${input.indent}project {`,
+    `${input.indent}  id`,
+    `${input.indent}  name`,
+    `${input.indent}}`,
+  ].join("\n");
+}
+
+function projectUpdateFieldsSelection(input: {
+  readonly indent: string;
+}): string {
+  return [
+    `${input.indent}id`,
+    `${input.indent}body`,
+    `${input.indent}health`,
+    `${input.indent}url`,
+    `${input.indent}slugId`,
+    `${input.indent}createdAt`,
+    `${input.indent}updatedAt`,
+    `${input.indent}project {`,
+    `${input.indent}  id`,
+    `${input.indent}  name`,
+    `${input.indent}}`,
+    `${input.indent}user {`,
+    userFieldsSelection({ indent: `${input.indent}  ` }),
+    `${input.indent}}`,
+  ].join("\n");
+}
+
 function issueFieldsQuery(input: {
   readonly operation: string;
   readonly variablesDef: string;
@@ -1177,6 +1743,205 @@ function parseCommentMutationComment(value: unknown): LinearComment | null {
   return parseComment(value.comment);
 }
 
+function parseProjectDocuments(value: unknown): LinearProjectDocument[] {
+  if (!isRecord(value)) {
+    return [];
+  }
+  const documents = isRecord(value.documents) ? value.documents : null;
+  const nodes = Array.isArray(documents?.nodes) ? documents.nodes : [];
+  const out: LinearProjectDocument[] = [];
+  for (const node of nodes) {
+    const parsed = parseProjectDocument(node);
+    if (!parsed) {
+      continue;
+    }
+    out.push(parsed);
+  }
+  return out;
+}
+
+function parseProjectDocument(value: unknown): LinearProjectDocument | null {
+  if (!(isRecord(value) && typeof value.id === "string")) {
+    return null;
+  }
+  if (typeof value.title !== "string") {
+    return null;
+  }
+  const project = isRecord(value.project) ? value.project : null;
+  return {
+    id: value.id,
+    title: value.title,
+    ...(typeof value.content === "string" ? { content: value.content } : {}),
+    ...(typeof value.url === "string" ? { url: value.url } : {}),
+    ...(typeof value.slugId === "string" ? { slugId: value.slugId } : {}),
+    ...(typeof value.sortOrder === "number"
+      ? { sortOrder: value.sortOrder }
+      : {}),
+    ...(typeof value.icon === "string" ? { icon: value.icon } : {}),
+    ...parseEntityProjectFields(project),
+    archived: value.trashed === true,
+    ...(typeof value.createdAt === "string"
+      ? { createdAt: value.createdAt }
+      : {}),
+    ...(typeof value.updatedAt === "string"
+      ? { updatedAt: value.updatedAt }
+      : {}),
+  };
+}
+
+function parseDocumentMutation(value: unknown): LinearProjectDocument | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const success = value.success;
+  if (typeof success === "boolean" && !success) {
+    return null;
+  }
+  return parseProjectDocument(value.document);
+}
+
+function parseProjectMilestones(value: unknown): LinearProjectMilestone[] {
+  if (!isRecord(value)) {
+    return [];
+  }
+  const milestones = isRecord(value.projectMilestones)
+    ? value.projectMilestones
+    : null;
+  const nodes = Array.isArray(milestones?.nodes) ? milestones.nodes : [];
+  const out: LinearProjectMilestone[] = [];
+  for (const node of nodes) {
+    const parsed = parseProjectMilestone(node);
+    if (!parsed) {
+      continue;
+    }
+    out.push(parsed);
+  }
+  return out;
+}
+
+function parseProjectMilestone(value: unknown): LinearProjectMilestone | null {
+  if (!(isRecord(value) && typeof value.id === "string")) {
+    return null;
+  }
+  if (typeof value.name !== "string") {
+    return null;
+  }
+  const project = isRecord(value.project) ? value.project : null;
+  return {
+    id: value.id,
+    title: value.name,
+    ...(typeof value.description === "string"
+      ? { description: value.description }
+      : {}),
+    ...(typeof value.sortOrder === "number"
+      ? { sortOrder: value.sortOrder }
+      : {}),
+    ...(typeof value.status === "string" ? { status: value.status } : {}),
+    ...(typeof value.targetDate === "string"
+      ? { targetDate: value.targetDate }
+      : {}),
+    ...parseEntityProjectFields(project),
+    archived: typeof value.archivedAt === "string",
+    ...(typeof value.createdAt === "string"
+      ? { createdAt: value.createdAt }
+      : {}),
+    ...(typeof value.updatedAt === "string"
+      ? { updatedAt: value.updatedAt }
+      : {}),
+  };
+}
+
+function parseProjectMilestoneMutation(
+  value: unknown
+): LinearProjectMilestone | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const success = value.success;
+  if (typeof success === "boolean" && !success) {
+    return null;
+  }
+  return parseProjectMilestone(value.projectMilestone);
+}
+
+function parseProjectUpdates(value: unknown): LinearProjectUpdate[] {
+  if (!isRecord(value)) {
+    return [];
+  }
+  const updates = isRecord(value.projectUpdates) ? value.projectUpdates : null;
+  const nodes = Array.isArray(updates?.nodes) ? updates.nodes : [];
+  const out: LinearProjectUpdate[] = [];
+  for (const node of nodes) {
+    const parsed = parseProjectUpdate(node);
+    if (!parsed) {
+      continue;
+    }
+    out.push(parsed);
+  }
+  return out;
+}
+
+function parseProjectUpdate(value: unknown): LinearProjectUpdate | null {
+  if (!(isRecord(value) && typeof value.id === "string")) {
+    return null;
+  }
+  if (
+    !(typeof value.body === "string" && typeof value.createdAt === "string")
+  ) {
+    return null;
+  }
+  const project = isRecord(value.project) ? value.project : null;
+  const user = parseUser(value.user);
+  return {
+    id: value.id,
+    body: value.body,
+    ...(typeof value.health === "string" ? { health: value.health } : {}),
+    ...(typeof value.url === "string" ? { url: value.url } : {}),
+    ...(typeof value.slugId === "string" ? { slugId: value.slugId } : {}),
+    ...parseEntityProjectFields(project),
+    ...(user
+      ? {
+          userId: user.id,
+          ...(typeof user.name === "string" ? { userName: user.name } : {}),
+          ...(typeof user.displayName === "string"
+            ? { userDisplayName: user.displayName }
+            : {}),
+          ...(typeof user.email === "string" ? { userEmail: user.email } : {}),
+        }
+      : {}),
+    createdAt: value.createdAt,
+    ...(typeof value.updatedAt === "string"
+      ? { updatedAt: value.updatedAt }
+      : {}),
+  };
+}
+
+function parseProjectUpdateMutation(
+  value: unknown
+): LinearProjectUpdate | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const success = value.success;
+  if (typeof success === "boolean" && !success) {
+    return null;
+  }
+  return parseProjectUpdate(value.projectUpdate);
+}
+
+function parseEntityProjectFields(value: Record<string, unknown> | null): {
+  readonly projectId?: string;
+  readonly projectName?: string;
+} {
+  if (!(value && typeof value.id === "string")) {
+    return {};
+  }
+  return {
+    projectId: value.id,
+    ...(typeof value.name === "string" ? { projectName: value.name } : {}),
+  };
+}
+
 function parseIssueBase(value: Record<string, unknown>): {
   readonly id: string;
   readonly identifier: string;
diff --git a/tests/linear-client.test.ts b/tests/linear-client.test.ts
index 935413c30..1a4aa9ffa 100644
--- a/tests/linear-client.test.ts
+++ b/tests/linear-client.test.ts
@@ -544,3 +544,491 @@ test("updateIssue forwards assigneeId when provided", async () => {
   });
   expect(result.data?.assigneeId).toBe("user_123");
 });
+
+test("listProjectDocuments returns project-scoped documents", async () => {
+  let requestBody: {
+    readonly query?: unknown;
+    readonly variables?: unknown;
+  } | null = null;
+  globalThis.fetch = (async (_input, init) => {
+    requestBody = JSON.parse(String(init?.body)) as {
+      readonly query?: unknown;
+      readonly variables?: unknown;
+    };
+    return new Response(
+      JSON.stringify({
+        data: {
+          project: {
+            documents: {
+              nodes: [
+                {
+                  id: "doc_123",
+                  title: "Launch plan",
+                  content: "# Launch plan",
+                  url: "https://linear.app/docs/doc_123",
+                  slugId: "launch-plan",
+                  sortOrder: 42,
+                  icon: "rocket",
+                  trashed: false,
+                  updatedAt: "2026-03-14T10:00:00.000Z",
+                  project: {
+                    id: "project_123",
+                    name: "Linear dogfood",
+                  },
+                },
+              ],
+            },
+          },
+        },
+      }),
+      { status: 200 }
+    );
+  }) as typeof fetch;
+
+  const client = createLinearClient({ token: "linear-token" });
+  const result = await client.listProjectDocuments({
+    projectId: "project_123",
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(
+    String((requestBody as { readonly query?: unknown } | null)?.query ?? "")
+  ).toContain("documents(first: $first)");
+  expect(
+    (requestBody as { readonly variables?: unknown } | null)?.variables
+  ).toEqual({
+    projectId: "project_123",
+    first: 50,
+  });
+  expect(result.data).toEqual([
+    {
+      id: "doc_123",
+      title: "Launch plan",
+      content: "# Launch plan",
+      url: "https://linear.app/docs/doc_123",
+      slugId: "launch-plan",
+      sortOrder: 42,
+      icon: "rocket",
+      projectId: "project_123",
+      projectName: "Linear dogfood",
+      archived: false,
+      updatedAt: "2026-03-14T10:00:00.000Z",
+    },
+  ]);
+});
+
+test("createProjectDocument sends documentCreate mutation for a project", async () => {
+  let requestBody: {
+    readonly query?: unknown;
+    readonly variables?: unknown;
+  } | null = null;
+  globalThis.fetch = (async (_input, init) => {
+    requestBody = JSON.parse(String(init?.body)) as {
+      readonly query?: unknown;
+      readonly variables?: unknown;
+    };
+    return new Response(
+      JSON.stringify({
+        data: {
+          documentCreate: {
+            success: true,
+            document: {
+              id: "doc_123",
+              title: "Launch plan",
+              content: "# Launch plan",
+              slugId: "launch-plan",
+              sortOrder: 1,
+              icon: "rocket",
+              trashed: false,
+              project: {
+                id: "project_123",
+                name: "Linear dogfood",
+              },
+            },
+          },
+        },
+      }),
+      { status: 200 }
+    );
+  }) as typeof fetch;
+
+  const client = createLinearClient({ token: "linear-token" });
+  const result = await client.createProjectDocument({
+    projectId: "project_123",
+    title: "Launch plan",
+    content: "# Launch plan",
+    icon: "rocket",
+    sortOrder: 1,
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(
+    String((requestBody as { readonly query?: unknown } | null)?.query ?? "")
+  ).toContain("mutation LinearDocumentCreate");
+  expect(
+    (requestBody as { readonly variables?: unknown } | null)?.variables
+  ).toEqual({
+    input: {
+      projectId: "project_123",
+      title: "Launch plan",
+      content: "# Launch plan",
+      icon: "rocket",
+      sortOrder: 1,
+    },
+  });
+  expect(result.data).toMatchObject({
+    id: "doc_123",
+    projectId: "project_123",
+    projectName: "Linear dogfood",
+    archived: false,
+  });
+});
+
+test("updateProjectDocument sends documentUpdate mutation for a managed document", async () => {
+  let requestBody: {
+    readonly query?: unknown;
+    readonly variables?: unknown;
+  } | null = null;
+  globalThis.fetch = (async (_input, init) => {
+    requestBody = JSON.parse(String(init?.body)) as {
+      readonly query?: unknown;
+      readonly variables?: unknown;
+    };
+    return new Response(
+      JSON.stringify({
+        data: {
+          documentUpdate: {
+            success: true,
+            document: {
+              id: "doc_123",
+              title: "Launch plan v2",
+              content: "# Launch plan v2",
+              slugId: "launch-plan",
+              sortOrder: 2,
+              icon: "rocket",
+              trashed: false,
+              project: {
+                id: "project_123",
+                name: "Linear dogfood",
+              },
+            },
+          },
+        },
+      }),
+      { status: 200 }
+    );
+  }) as typeof fetch;
+
+  const client = createLinearClient({ token: "linear-token" });
+  const result = await client.updateProjectDocument({
+    documentId: "doc_123",
+    title: "Launch plan v2",
+    content: "# Launch plan v2",
+    sortOrder: 2,
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(
+    String((requestBody as { readonly query?: unknown } | null)?.query ?? "")
+  ).toContain("mutation LinearDocumentUpdate");
+  expect(
+    (requestBody as { readonly variables?: unknown } | null)?.variables
+  ).toEqual({
+    id: "doc_123",
+    input: {
+      title: "Launch plan v2",
+      content: "# Launch plan v2",
+      sortOrder: 2,
+    },
+  });
+  expect(result.data.title).toBe("Launch plan v2");
+});
+
+test("listProjectMilestones returns structured milestones", async () => {
+  let requestBody: {
+    readonly query?: unknown;
+    readonly variables?: unknown;
+  } | null = null;
+  globalThis.fetch = (async (_input, init) => {
+    requestBody = JSON.parse(String(init?.body)) as {
+      readonly query?: unknown;
+      readonly variables?: unknown;
+    };
+    return new Response(
+      JSON.stringify({
+        data: {
+          project: {
+            projectMilestones: {
+              nodes: [
+                {
+                  id: "milestone_123",
+                  name: "Private beta",
+                  description: "Ship the beta cohort",
+                  sortOrder: 7,
+                  status: "pending",
+                  targetDate: "2026-04-01",
+                  archivedAt: null,
+                  updatedAt: "2026-03-14T10:00:00.000Z",
+                  project: {
+                    id: "project_123",
+                    name: "Linear dogfood",
+                  },
+                },
+              ],
+            },
+          },
+        },
+      }),
+      { status: 200 }
+    );
+  }) as typeof fetch;
+
+  const client = createLinearClient({ token: "linear-token" });
+  const result = await client.listProjectMilestones({
+    projectId: "project_123",
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(
+    String((requestBody as { readonly query?: unknown } | null)?.query ?? "")
+  ).toContain("projectMilestones(first: $first)");
+  expect(result.data).toEqual([
+    {
+      id: "milestone_123",
+      title: "Private beta",
+      description: "Ship the beta cohort",
+      sortOrder: 7,
+      status: "pending",
+      targetDate: "2026-04-01",
+      projectId: "project_123",
+      projectName: "Linear dogfood",
+      archived: false,
+      updatedAt: "2026-03-14T10:00:00.000Z",
+    },
+  ]);
+});
+
+test("createProjectMilestone sends projectMilestoneCreate mutation", async () => {
+  let requestBody: {
+    readonly query?: unknown;
+    readonly variables?: unknown;
+  } | null = null;
+  globalThis.fetch = (async (_input, init) => {
+    requestBody = JSON.parse(String(init?.body)) as {
+      readonly query?: unknown;
+      readonly variables?: unknown;
+    };
+    return new Response(
+      JSON.stringify({
+        data: {
+          projectMilestoneCreate: {
+            success: true,
+            projectMilestone: {
+              id: "milestone_123",
+              name: "Private beta",
+              description: "Ship the beta cohort",
+              sortOrder: 7,
+              status: "pending",
+              targetDate: "2026-04-01",
+              archivedAt: null,
+              project: {
+                id: "project_123",
+                name: "Linear dogfood",
+              },
+            },
+          },
+        },
+      }),
+      { status: 200 }
+    );
+  }) as typeof fetch;
+
+  const client = createLinearClient({ token: "linear-token" });
+  const result = await client.createProjectMilestone({
+    projectId: "project_123",
+    title: "Private beta",
+    description: "Ship the beta cohort",
+    sortOrder: 7,
+    targetDate: "2026-04-01",
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(
+    String((requestBody as { readonly query?: unknown } | null)?.query ?? "")
+  ).toContain("mutation LinearProjectMilestoneCreate");
+  expect(
+    (requestBody as { readonly variables?: unknown } | null)?.variables
+  ).toEqual({
+    input: {
+      projectId: "project_123",
+      name: "Private beta",
+      description: "Ship the beta cohort",
+      sortOrder: 7,
+      targetDate: "2026-04-01",
+    },
+  });
+  expect(result.data.title).toBe("Private beta");
+});
+
+test("listProjectUpdates returns project updates with health", async () => {
+  let requestBody: {
+    readonly query?: unknown;
+    readonly variables?: unknown;
+  } | null = null;
+  globalThis.fetch = (async (_input, init) => {
+    requestBody = JSON.parse(String(init?.body)) as {
+      readonly query?: unknown;
+      readonly variables?: unknown;
+    };
+    return new Response(
+      JSON.stringify({
+        data: {
+          project: {
+            projectUpdates: {
+              nodes: [
+                {
+                  id: "update_123",
+                  body: "Still on track for dogfooding.",
+                  health: "onTrack",
+                  slugId: "weekly-update",
+                  createdAt: "2026-03-14T10:00:00.000Z",
+                  updatedAt: "2026-03-14T10:15:00.000Z",
+                  url: "https://linear.app/project/update_123",
+                  user: {
+                    id: "user_123",
+                    name: "Alice Example",
+                    displayName: "Alice",
+                    email: "alice@example.com",
+                  },
+                  project: {
+                    id: "project_123",
+                    name: "Linear dogfood",
+                  },
+                },
+              ],
+            },
+          },
+        },
+      }),
+      { status: 200 }
+    );
+  }) as typeof fetch;
+
+  const client = createLinearClient({ token: "linear-token" });
+  const result = await client.listProjectUpdates({
+    projectId: "project_123",
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(
+    String((requestBody as { readonly query?: unknown } | null)?.query ?? "")
+  ).toContain("projectUpdates(first: $first)");
+  expect(result.data).toEqual([
+    {
+      id: "update_123",
+      body: "Still on track for dogfooding.",
+      health: "onTrack",
+      slugId: "weekly-update",
+      createdAt: "2026-03-14T10:00:00.000Z",
+      updatedAt: "2026-03-14T10:15:00.000Z",
+      url: "https://linear.app/project/update_123",
+      projectId: "project_123",
+      projectName: "Linear dogfood",
+      userId: "user_123",
+      userName: "Alice Example",
+      userDisplayName: "Alice",
+      userEmail: "alice@example.com",
+    },
+  ]);
+});
+
+test("createProjectUpdate sends projectUpdateCreate mutation", async () => {
+  let requestBody: {
+    readonly query?: unknown;
+    readonly variables?: unknown;
+  } | null = null;
+  globalThis.fetch = (async (_input, init) => {
+    requestBody = JSON.parse(String(init?.body)) as {
+      readonly query?: unknown;
+      readonly variables?: unknown;
+    };
+    return new Response(
+      JSON.stringify({
+        data: {
+          projectUpdateCreate: {
+            success: true,
+            projectUpdate: {
+              id: "update_123",
+              body: "Still on track for dogfooding.",
+              health: "onTrack",
+              slugId: "weekly-update",
+              createdAt: "2026-03-14T10:00:00.000Z",
+              updatedAt: "2026-03-14T10:15:00.000Z",
+              project: {
+                id: "project_123",
+                name: "Linear dogfood",
+              },
+              user: {
+                id: "user_123",
+                displayName: "Alice",
+              },
+            },
+          },
+        },
+      }),
+      { status: 200 }
+    );
+  }) as typeof fetch;
+
+  const client = createLinearClient({ token: "linear-token" });
+  const result = await client.createProjectUpdate({
+    projectId: "project_123",
+    body: "Still on track for dogfooding.",
+    health: "onTrack",
+    isDiffHidden: true,
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(
+    String((requestBody as { readonly query?: unknown } | null)?.query ?? "")
+  ).toContain("mutation LinearProjectUpdateCreate");
+  expect(
+    (requestBody as { readonly variables?: unknown } | null)?.variables
+  ).toEqual({
+    input: {
+      projectId: "project_123",
+      body: "Still on track for dogfooding.",
+      health: "onTrack",
+      isDiffHidden: true,
+    },
+  });
+  expect(result.data.userDisplayName).toBe("Alice");
+});

From 8ffc5df49e406ab13d09214608f745f45c232c37 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:25:14 +0000
Subject: [PATCH 030/134] feat: add linear project artifact file model

---
 .../extensions/linear/project-artifacts.ts    | 484 ++++++++++++++++++
 tests/linear-project-artifacts.test.ts        | 247 +++++++++
 2 files changed, 731 insertions(+)
 create mode 100644 src/control-plane/extensions/linear/project-artifacts.ts
 create mode 100644 tests/linear-project-artifacts.test.ts

diff --git a/src/control-plane/extensions/linear/project-artifacts.ts b/src/control-plane/extensions/linear/project-artifacts.ts
new file mode 100644
index 000000000..3e5f0217b
--- /dev/null
+++ b/src/control-plane/extensions/linear/project-artifacts.ts
@@ -0,0 +1,484 @@
+import { join } from "node:path";
+import { YAML } from "bun";
+
+import { isRecord } from "../../../lib/guards.ts";
+
+export type LinearProjectArtifactKind =
+  | "linear-project-document"
+  | "linear-project-milestone"
+  | "linear-project-status-update";
+
+type LinearProjectArtifactBase = {
+  readonly kind: LinearProjectArtifactKind;
+  readonly linearProjectId: string;
+  readonly title: string;
+  readonly linearId?: string;
+  readonly slug?: string;
+  readonly archived: boolean;
+  readonly updatedAt?: string;
+  readonly body: string;
+};
+
+export type LinearProjectArtifactSnapshot =
+  | (LinearProjectArtifactBase & {
+      readonly kind: "linear-project-document";
+      readonly sortOrder?: number;
+      readonly icon?: string;
+    })
+  | (LinearProjectArtifactBase & {
+      readonly kind: "linear-project-milestone";
+      readonly targetDate?: string;
+      readonly state?: string;
+      readonly sortOrder?: number;
+    })
+  | (LinearProjectArtifactBase & {
+      readonly kind: "linear-project-status-update";
+      readonly date?: string;
+      readonly health?: string;
+      readonly linkedMilestoneIds?: readonly string[];
+    });
+
+export type LocalLinearProjectArtifact = LinearProjectArtifactSnapshot & {
+  readonly path: string;
+};
+
+export type LinearProjectArtifactPlan = {
+  readonly errors: readonly string[];
+  readonly create: readonly LocalLinearProjectArtifact[];
+  readonly update: readonly {
+    readonly local: LocalLinearProjectArtifact;
+    readonly remote: LinearProjectArtifactSnapshot;
+  }[];
+  readonly noop: readonly {
+    readonly local: LocalLinearProjectArtifact;
+    readonly remote: LinearProjectArtifactSnapshot;
+  }[];
+  readonly remoteOnly: readonly LinearProjectArtifactSnapshot[];
+};
+
+const FRONTMATTER_PATTERN = /^---\n([\s\S]*?)\n---\n?/;
+
+/** Resolve the repo-backed root for all managed artifacts of a bound Linear project. */
+export const resolveLinearProjectArtifactsRoot = ({
+  projectDir,
+  linearProjectId,
+}: {
+  readonly projectDir: string;
+  readonly linearProjectId: string;
+}): string => join(projectDir, ".hack/linear/projects", linearProjectId);
+
+/** Parse a repo-managed Markdown artifact into a normalized record for planning and sync. */
+export const parseLinearProjectArtifactFile = ({
+  filePath,
+  text,
+}: {
+  readonly filePath: string;
+  readonly text: string;
+}): LocalLinearProjectArtifact => {
+  const match = text.match(FRONTMATTER_PATTERN);
+  if (!match) {
+    throw new Error(`Missing YAML frontmatter in ${filePath}`);
+  }
+
+  const parsed = YAML.parse(match[1]) as unknown;
+  if (!isRecord(parsed)) {
+    throw new Error(`Invalid YAML frontmatter in ${filePath}`);
+  }
+
+  const kind = parseKind(parsed.kind, filePath);
+  const linearProjectId = readRequiredString({
+    value: parsed.linearProjectId,
+    key: "linearProjectId",
+    filePath,
+  });
+  const title = readRequiredString({
+    value: parsed.title,
+    key: "title",
+    filePath,
+  });
+  const body = text.slice(match[0].length);
+  const base = {
+    kind,
+    linearProjectId,
+    title,
+    ...(typeof parsed.linearId === "string"
+      ? { linearId: parsed.linearId }
+      : {}),
+    ...(typeof parsed.slug === "string" ? { slug: parsed.slug } : {}),
+    archived: parsed.archived === true,
+    ...(typeof parsed.updatedAt === "string"
+      ? { updatedAt: parsed.updatedAt }
+      : {}),
+    body,
+    path: filePath,
+  } as const;
+
+  if (kind === "linear-project-document") {
+    return {
+      ...base,
+      ...(typeof parsed.sortOrder === "number"
+        ? { sortOrder: parsed.sortOrder }
+        : {}),
+      ...(typeof parsed.icon === "string" ? { icon: parsed.icon } : {}),
+    };
+  }
+
+  if (kind === "linear-project-milestone") {
+    return {
+      ...base,
+      ...(typeof parsed.targetDate === "string"
+        ? { targetDate: parsed.targetDate }
+        : {}),
+      ...(typeof parsed.state === "string" ? { state: parsed.state } : {}),
+      ...(typeof parsed.sortOrder === "number"
+        ? { sortOrder: parsed.sortOrder }
+        : {}),
+    };
+  }
+
+  return {
+    ...base,
+    ...(typeof parsed.date === "string" ? { date: parsed.date } : {}),
+    ...(typeof parsed.health === "string" ? { health: parsed.health } : {}),
+    ...(Array.isArray(parsed.linkedMilestoneIds)
+      ? {
+          linkedMilestoneIds: parsed.linkedMilestoneIds.filter(
+            (value): value is string => typeof value === "string"
+          ),
+        }
+      : {}),
+  };
+};
+
+/** Serialize an artifact back to stable frontmatter + Markdown body for pull/apply workflows. */
+export const serializeLinearProjectArtifactFile = ({
+  artifact,
+}: {
+  readonly artifact: LocalLinearProjectArtifact;
+}): string => {
+  const lines = ["---", ...serializeCommonFrontmatter({ artifact })];
+  lines.push(...serializeKindSpecificFrontmatter({ artifact }));
+  lines.push("---");
+  return `${lines.join("\n")}\n${artifact.body}`;
+};
+
+/** Compare local and remote artifact snapshots to produce explicit create/update/noop actions. */
+export const planLinearProjectArtifactChanges = ({
+  localArtifacts,
+  remoteArtifacts,
+}: {
+  readonly localArtifacts: readonly LocalLinearProjectArtifact[];
+  readonly remoteArtifacts: readonly LinearProjectArtifactSnapshot[];
+}): LinearProjectArtifactPlan => {
+  const errors = [
+    ...detectLocalDuplicates({ artifacts: localArtifacts }),
+    ...detectRemoteDuplicates({ artifacts: remoteArtifacts }),
+  ];
+  if (errors.length > 0) {
+    return {
+      errors,
+      create: [],
+      update: [],
+      noop: [],
+      remoteOnly: [],
+    };
+  }
+
+  const remoteByKey = new Map<string, LinearProjectArtifactSnapshot>();
+  for (const artifact of remoteArtifacts) {
+    remoteByKey.set(buildArtifactKey({ artifact }), artifact);
+  }
+
+  const create: LocalLinearProjectArtifact[] = [];
+  const update: {
+    local: LocalLinearProjectArtifact;
+    remote: LinearProjectArtifactSnapshot;
+  }[] = [];
+  const noop: {
+    local: LocalLinearProjectArtifact;
+    remote: LinearProjectArtifactSnapshot;
+  }[] = [];
+  const seenRemoteKeys = new Set<string>();
+
+  for (const local of localArtifacts) {
+    const key = buildArtifactKey({ artifact: local });
+    const remote = remoteByKey.get(key);
+    if (!remote) {
+      create.push(local);
+      continue;
+    }
+    seenRemoteKeys.add(key);
+    if (artifactsEqual({ local, remote })) {
+      noop.push({ local, remote });
+      continue;
+    }
+    update.push({ local, remote });
+  }
+
+  const remoteOnly = remoteArtifacts.filter(
+    (artifact) => !seenRemoteKeys.has(buildArtifactKey({ artifact }))
+  );
+
+  return {
+    errors: [],
+    create,
+    update,
+    noop,
+    remoteOnly,
+  };
+};
+
+const parseKind = (
+  value: unknown,
+  filePath: string
+): LinearProjectArtifactKind => {
+  if (
+    value === "linear-project-document" ||
+    value === "linear-project-milestone" ||
+    value === "linear-project-status-update"
+  ) {
+    return value;
+  }
+  throw new Error(`Invalid or missing kind in ${filePath}`);
+};
+
+const readRequiredString = ({
+  value,
+  key,
+  filePath,
+}: {
+  readonly value: unknown;
+  readonly key: string;
+  readonly filePath: string;
+}): string => {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+  throw new Error(`Missing ${key} in ${filePath}`);
+};
+
+const serializeCommonFrontmatter = ({
+  artifact,
+}: {
+  readonly artifact: LocalLinearProjectArtifact;
+}): string[] => {
+  const lines = [
+    `kind: ${artifact.kind}`,
+    `linearProjectId: ${artifact.linearProjectId}`,
+    `title: ${artifact.title}`,
+  ];
+
+  if (artifact.linearId) {
+    lines.push(`linearId: ${artifact.linearId}`);
+  }
+  if (artifact.slug) {
+    lines.push(`slug: ${artifact.slug}`);
+  }
+  lines.push(`archived: ${artifact.archived ? "true" : "false"}`);
+  if (artifact.updatedAt) {
+    lines.push(`updatedAt: ${artifact.updatedAt}`);
+  }
+
+  return lines;
+};
+
+const serializeKindSpecificFrontmatter = ({
+  artifact,
+}: {
+  readonly artifact: LocalLinearProjectArtifact;
+}): string[] => {
+  if (artifact.kind === "linear-project-document") {
+    return serializeDocumentFrontmatter({ artifact });
+  }
+
+  if (artifact.kind === "linear-project-milestone") {
+    return serializeMilestoneFrontmatter({ artifact });
+  }
+
+  return serializeStatusUpdateFrontmatter({ artifact });
+};
+
+const serializeDocumentFrontmatter = ({
+  artifact,
+}: {
+  readonly artifact: Extract<
+    LocalLinearProjectArtifact,
+    { readonly kind: "linear-project-document" }
+  >;
+}): string[] => {
+  const lines: string[] = [];
+  if (artifact.sortOrder !== undefined) {
+    lines.push(`sortOrder: ${artifact.sortOrder}`);
+  }
+  if (artifact.icon) {
+    lines.push(`icon: ${artifact.icon}`);
+  }
+  return lines;
+};
+
+const serializeMilestoneFrontmatter = ({
+  artifact,
+}: {
+  readonly artifact: Extract<
+    LocalLinearProjectArtifact,
+    { readonly kind: "linear-project-milestone" }
+  >;
+}): string[] => {
+  const lines: string[] = [];
+  if (artifact.targetDate) {
+    lines.push(`targetDate: ${artifact.targetDate}`);
+  }
+  if (artifact.state) {
+    lines.push(`state: ${artifact.state}`);
+  }
+  if (artifact.sortOrder !== undefined) {
+    lines.push(`sortOrder: ${artifact.sortOrder}`);
+  }
+  return lines;
+};
+
+const serializeStatusUpdateFrontmatter = ({
+  artifact,
+}: {
+  readonly artifact: Extract<
+    LocalLinearProjectArtifact,
+    { readonly kind: "linear-project-status-update" }
+  >;
+}): string[] => {
+  const lines: string[] = [];
+  if (artifact.date) {
+    lines.push(`date: ${artifact.date}`);
+  }
+  if (artifact.health) {
+    lines.push(`health: ${artifact.health}`);
+  }
+  if (artifact.linkedMilestoneIds && artifact.linkedMilestoneIds.length > 0) {
+    lines.push("linkedMilestoneIds:");
+    for (const milestoneId of artifact.linkedMilestoneIds) {
+      lines.push(`  - ${milestoneId}`);
+    }
+  }
+  return lines;
+};
+
+const detectLocalDuplicates = ({
+  artifacts,
+}: {
+  readonly artifacts: readonly LocalLinearProjectArtifact[];
+}): string[] => {
+  const errors: string[] = [];
+  const seenLinearIds = new Map<string, string>();
+  const seenSlugs = new Map<string, string>();
+
+  for (const artifact of artifacts) {
+    if (artifact.linearId) {
+      const existing = seenLinearIds.get(artifact.linearId);
+      if (existing) {
+        errors.push(
+          `Duplicate local linearId "${artifact.linearId}" in ${existing} and ${artifact.path}`
+        );
+      } else {
+        seenLinearIds.set(artifact.linearId, artifact.path);
+      }
+    }
+
+    if (artifact.slug) {
+      const slugKey = `${artifact.kind}:${artifact.linearProjectId}:${artifact.slug}`;
+      const existing = seenSlugs.get(slugKey);
+      if (existing) {
+        errors.push(
+          `Duplicate local slug "${artifact.slug}" in ${existing} and ${artifact.path}`
+        );
+      } else {
+        seenSlugs.set(slugKey, artifact.path);
+      }
+    }
+  }
+
+  return errors;
+};
+
+const detectRemoteDuplicates = ({
+  artifacts,
+}: {
+  readonly artifacts: readonly LinearProjectArtifactSnapshot[];
+}): string[] => {
+  const errors: string[] = [];
+  const seenKeys = new Set<string>();
+  for (const artifact of artifacts) {
+    const key = buildArtifactKey({ artifact });
+    if (seenKeys.has(key)) {
+      errors.push(`Duplicate remote artifact mapping for ${key}`);
+      continue;
+    }
+    seenKeys.add(key);
+  }
+  return errors;
+};
+
+const buildArtifactKey = ({
+  artifact,
+}: {
+  readonly artifact: LinearProjectArtifactSnapshot;
+}): string => {
+  if (artifact.linearId) {
+    return `${artifact.kind}:id:${artifact.linearId}`;
+  }
+  if (artifact.slug) {
+    return `${artifact.kind}:slug:${artifact.linearProjectId}:${artifact.slug}`;
+  }
+  return `${artifact.kind}:title:${artifact.linearProjectId}:${artifact.title}`;
+};
+
+const artifactsEqual = ({
+  local,
+  remote,
+}: {
+  readonly local: LocalLinearProjectArtifact;
+  readonly remote: LinearProjectArtifactSnapshot;
+}): boolean =>
+  JSON.stringify(normalizeArtifactForComparison({ artifact: local })) ===
+  JSON.stringify(normalizeArtifactForComparison({ artifact: remote }));
+
+const normalizeArtifactForComparison = ({
+  artifact,
+}: {
+  readonly artifact: LinearProjectArtifactSnapshot;
+}): Record<
+  string,
+  string | number | boolean | readonly string[] | undefined
+> => {
+  const base = {
+    kind: artifact.kind,
+    linearProjectId: artifact.linearProjectId,
+    title: artifact.title,
+    linearId: artifact.linearId,
+    slug: artifact.slug,
+    archived: artifact.archived,
+    body: artifact.body,
+  };
+
+  if (artifact.kind === "linear-project-document") {
+    return {
+      ...base,
+      sortOrder: artifact.sortOrder,
+      icon: artifact.icon,
+    };
+  }
+
+  if (artifact.kind === "linear-project-milestone") {
+    return {
+      ...base,
+      targetDate: artifact.targetDate,
+      state: artifact.state,
+      sortOrder: artifact.sortOrder,
+    };
+  }
+
+  return {
+    ...base,
+    date: artifact.date,
+    health: artifact.health,
+    linkedMilestoneIds: artifact.linkedMilestoneIds,
+  };
+};
diff --git a/tests/linear-project-artifacts.test.ts b/tests/linear-project-artifacts.test.ts
new file mode 100644
index 000000000..151d2eef8
--- /dev/null
+++ b/tests/linear-project-artifacts.test.ts
@@ -0,0 +1,247 @@
+import { expect, test } from "bun:test";
+import { join } from "node:path";
+
+import {
+  parseLinearProjectArtifactFile,
+  planLinearProjectArtifactChanges,
+  resolveLinearProjectArtifactsRoot,
+  serializeLinearProjectArtifactFile,
+} from "../src/control-plane/extensions/linear/project-artifacts.ts";
+
+test("parseLinearProjectArtifactFile parses a project document frontmatter block", () => {
+  const artifact = parseLinearProjectArtifactFile({
+    filePath: "/repo/.hack/linear/projects/proj_123/documents/launch-plan.md",
+    text: `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: Launch plan
+linearId: doc_123
+slug: launch-plan
+sortOrder: 1
+icon: rocket
+archived: false
+updatedAt: 2026-03-14T10:00:00.000Z
+---
+# Launch plan
+`,
+  });
+
+  expect(artifact).toMatchObject({
+    kind: "linear-project-document",
+    linearProjectId: "proj_123",
+    title: "Launch plan",
+    linearId: "doc_123",
+    slug: "launch-plan",
+    sortOrder: 1,
+    icon: "rocket",
+    archived: false,
+    updatedAt: "2026-03-14T10:00:00.000Z",
+    body: "# Launch plan\n",
+  });
+});
+
+test("parseLinearProjectArtifactFile parses a milestone with notes", () => {
+  const artifact = parseLinearProjectArtifactFile({
+    filePath: "/repo/.hack/linear/projects/proj_123/milestones/private-beta.md",
+    text: `---
+kind: linear-project-milestone
+linearProjectId: proj_123
+title: Private beta
+linearId: milestone_123
+slug: private-beta
+targetDate: 2026-04-01
+state: pending
+sortOrder: 7
+---
+Ship the beta cohort.
+`,
+  });
+
+  expect(artifact).toMatchObject({
+    kind: "linear-project-milestone",
+    linearProjectId: "proj_123",
+    title: "Private beta",
+    linearId: "milestone_123",
+    slug: "private-beta",
+    targetDate: "2026-04-01",
+    state: "pending",
+    sortOrder: 7,
+    body: "Ship the beta cohort.\n",
+  });
+});
+
+test("parseLinearProjectArtifactFile parses a status update draft with linked milestones", () => {
+  const artifact = parseLinearProjectArtifactFile({
+    filePath:
+      "/repo/.hack/linear/projects/proj_123/status-updates/drafts/2026-03-14-weekly.md",
+    text: `---
+kind: linear-project-status-update
+linearProjectId: proj_123
+title: Weekly update
+slug: weekly
+date: 2026-03-14
+health: onTrack
+linkedMilestoneIds:
+  - milestone_123
+  - milestone_456
+---
+Still on track for dogfooding.
+`,
+  });
+
+  expect(artifact).toMatchObject({
+    kind: "linear-project-status-update",
+    linearProjectId: "proj_123",
+    title: "Weekly update",
+    slug: "weekly",
+    date: "2026-03-14",
+    health: "onTrack",
+    linkedMilestoneIds: ["milestone_123", "milestone_456"],
+    body: "Still on track for dogfooding.\n",
+  });
+});
+
+test("resolveLinearProjectArtifactsRoot uses the bound project id", () => {
+  const root = resolveLinearProjectArtifactsRoot({
+    projectDir: "/repo",
+    linearProjectId: "proj_123",
+  });
+
+  expect(root).toBe(join("/repo", ".hack/linear/projects/proj_123"));
+});
+
+test("planLinearProjectArtifactChanges reports duplicate local mappings", () => {
+  const plan = planLinearProjectArtifactChanges({
+    localArtifacts: [
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "Launch plan",
+        linearId: "doc_123",
+        slug: "launch-plan",
+        body: "# Launch plan\n",
+        path: "/repo/.hack/linear/projects/proj_123/documents/launch-plan.md",
+        archived: false,
+      },
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "Launch plan duplicate",
+        linearId: "doc_123",
+        slug: "launch-plan-duplicate",
+        body: "# Launch plan duplicate\n",
+        path: "/repo/.hack/linear/projects/proj_123/documents/launch-plan-duplicate.md",
+        archived: false,
+      },
+    ],
+    remoteArtifacts: [],
+  });
+
+  expect(plan.errors).toEqual([
+    'Duplicate local linearId "doc_123" in /repo/.hack/linear/projects/proj_123/documents/launch-plan.md and /repo/.hack/linear/projects/proj_123/documents/launch-plan-duplicate.md',
+  ]);
+});
+
+test("planLinearProjectArtifactChanges distinguishes create update noop and remote-only", () => {
+  const plan = planLinearProjectArtifactChanges({
+    localArtifacts: [
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "Create me",
+        slug: "create-me",
+        body: "# Create me\n",
+        path: "/repo/.hack/linear/projects/proj_123/documents/create-me.md",
+        archived: false,
+      },
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "Update me",
+        linearId: "doc_update",
+        slug: "update-me",
+        body: "# Updated body\n",
+        path: "/repo/.hack/linear/projects/proj_123/documents/update-me.md",
+        archived: false,
+      },
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "No-op me",
+        linearId: "doc_noop",
+        slug: "noop-me",
+        body: "# No changes\n",
+        path: "/repo/.hack/linear/projects/proj_123/documents/noop-me.md",
+        archived: false,
+      },
+    ],
+    remoteArtifacts: [
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "Update me",
+        linearId: "doc_update",
+        slug: "update-me",
+        body: "# Old body\n",
+        archived: false,
+      },
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "No-op me",
+        linearId: "doc_noop",
+        slug: "noop-me",
+        body: "# No changes\n",
+        archived: false,
+      },
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "Remote only",
+        linearId: "doc_remote",
+        slug: "remote-only",
+        body: "# Remote only\n",
+        archived: false,
+      },
+    ],
+  });
+
+  expect(plan.errors).toEqual([]);
+  expect(plan.create.map((item) => item.title)).toEqual(["Create me"]);
+  expect(plan.update.map((item) => item.local.title)).toEqual(["Update me"]);
+  expect(plan.noop.map((item) => item.local.title)).toEqual(["No-op me"]);
+  expect(plan.remoteOnly.map((item) => item.title)).toEqual(["Remote only"]);
+});
+
+test("serializeLinearProjectArtifactFile writes stable frontmatter", () => {
+  const text = serializeLinearProjectArtifactFile({
+    artifact: {
+      kind: "linear-project-status-update",
+      linearProjectId: "proj_123",
+      title: "Weekly update",
+      linearId: "update_123",
+      slug: "weekly",
+      date: "2026-03-14",
+      health: "onTrack",
+      linkedMilestoneIds: ["milestone_123"],
+      body: "Still on track for dogfooding.\n",
+      archived: false,
+      path: "/repo/.hack/linear/projects/proj_123/status-updates/published/2026-03-14-weekly.md",
+    },
+  });
+
+  expect(text).toBe(`---
+kind: linear-project-status-update
+linearProjectId: proj_123
+title: Weekly update
+linearId: update_123
+slug: weekly
+archived: false
+date: 2026-03-14
+health: onTrack
+linkedMilestoneIds:
+  - milestone_123
+---
+Still on track for dogfooding.
+`);
+});

From f84035975ce4e61288cf22c9ddd12a1a5601fce4 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:28:23 +0000
Subject: [PATCH 031/134] feat: add linear project artifact command parsers

---
 .../extensions/linear/commands.ts             | 123 ++++++++++++++++++
 tests/linear-commands.test.ts                 |  96 ++++++++++++++
 2 files changed, 219 insertions(+)

diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index ebaf9b342..8be46f78d 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -2497,6 +2497,32 @@ type RunAutosyncArgs = {
   json: boolean;
 };
 
+type ProjectArtifactArgsBase = {
+  verb: string;
+  profileId?: string;
+  projectId?: string;
+  projectName?: string;
+  teamId?: string;
+  path?: string;
+  json: boolean;
+};
+
+type ProjectDocumentsVerb = "list" | "pull" | "plan" | "apply" | "archive";
+type ProjectMilestonesVerb = ProjectDocumentsVerb;
+type ProjectStatusUpdatesVerb = "list" | "pull" | "plan" | "publish";
+
+type ProjectDocumentsArgs = Omit<ProjectArtifactArgsBase, "verb"> & {
+  verb: ProjectDocumentsVerb;
+};
+
+type ProjectMilestonesArgs = Omit<ProjectArtifactArgsBase, "verb"> & {
+  verb: ProjectMilestonesVerb;
+};
+
+type ProjectStatusUpdatesArgs = Omit<ProjectArtifactArgsBase, "verb"> & {
+  verb: ProjectStatusUpdatesVerb;
+};
+
 type ApplyDeliveryArgs = {
   profileId?: string;
   deliveryId: string;
@@ -8260,6 +8286,100 @@ function parseRunAutosyncArgs(input: {
   return { ok: true, value };
 }
 
+function parseProjectDocumentsArgs(input: {
+  readonly args: readonly string[];
+}):
+  | { readonly ok: true; readonly value: ProjectDocumentsArgs }
+  | { readonly ok: false; readonly error: string } {
+  return parseProjectArtifactArgs({
+    args: input.args,
+    allowedVerbs: ["list", "pull", "plan", "apply", "archive"],
+  }) as
+    | { readonly ok: true; readonly value: ProjectDocumentsArgs }
+    | { readonly ok: false; readonly error: string };
+}
+
+function parseProjectMilestonesArgs(input: {
+  readonly args: readonly string[];
+}):
+  | { readonly ok: true; readonly value: ProjectMilestonesArgs }
+  | { readonly ok: false; readonly error: string } {
+  return parseProjectArtifactArgs({
+    args: input.args,
+    allowedVerbs: ["list", "pull", "plan", "apply", "archive"],
+  }) as
+    | { readonly ok: true; readonly value: ProjectMilestonesArgs }
+    | { readonly ok: false; readonly error: string };
+}
+
+function parseProjectStatusUpdatesArgs(input: {
+  readonly args: readonly string[];
+}):
+  | { readonly ok: true; readonly value: ProjectStatusUpdatesArgs }
+  | { readonly ok: false; readonly error: string } {
+  return parseProjectArtifactArgs({
+    args: input.args,
+    allowedVerbs: ["list", "pull", "plan", "publish"],
+  }) as
+    | { readonly ok: true; readonly value: ProjectStatusUpdatesArgs }
+    | { readonly ok: false; readonly error: string };
+}
+
+function parseProjectArtifactArgs<TVerb extends string>(input: {
+  readonly args: readonly string[];
+  readonly allowedVerbs: readonly TVerb[];
+}):
+  | {
+      readonly ok: true;
+      readonly value: ProjectArtifactArgsBase & { readonly verb: TVerb };
+    }
+  | { readonly ok: false; readonly error: string } {
+  const first = readOptionalString(input.args[0]);
+  if (!first) {
+    return {
+      ok: false,
+      error: `Missing verb. Expected ${input.allowedVerbs.join("|")}.`,
+    };
+  }
+  if (!input.allowedVerbs.includes(first as TVerb)) {
+    return {
+      ok: false,
+      error: `Invalid verb: ${first}. Expected ${input.allowedVerbs.join("|")}.`,
+    };
+  }
+
+  const value: ProjectArtifactArgsBase & { readonly verb: TVerb } = {
+    verb: first as TVerb,
+    json: false,
+  };
+  const remainingArgs = input.args.slice(1);
+  for (let i = 0; i < remainingArgs.length; i += 1) {
+    const token = remainingArgs[i] ?? "";
+    if (token === "--json") {
+      value.json = true;
+      continue;
+    }
+    const handled = assignKeyValueFlag({
+      token,
+      args: remainingArgs,
+      index: i,
+      out: value,
+      keys: {
+        profile: "profileId",
+        "project-id": "projectId",
+        "project-name": "projectName",
+        "team-id": "teamId",
+        path: "path",
+      },
+    });
+    if (!handled.ok) {
+      return { ok: false, error: handled.error };
+    }
+    i = handled.nextIndex;
+  }
+  return { ok: true, value };
+}
+
 function assignKeyValueFlag<T extends Record<string, unknown>>(input: {
   readonly token: string;
   readonly args: readonly string[];
@@ -8322,6 +8442,9 @@ export const __testOnly = {
   parseOAuthConnectArgs,
   parseSeedLocalAccessArgs,
   parseRunAutosyncArgs,
+  parseProjectDocumentsArgs,
+  parseProjectMilestonesArgs,
+  parseProjectStatusUpdatesArgs,
   parseProjectBindArgs,
   parseProjectLinkArgs,
   parseProjectsArgs,
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index 75eee414b..f6a3ff448 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -1457,3 +1457,99 @@ test("runProjectLinearAutosync syncs issue and project deliveries, then applies
   expect(result.commentsPulled).toBe(5);
   expect(result.checkpointsRecorded).toBe(4);
 });
+
+test("parseProjectDocumentsArgs parses verb and shared routing flags", () => {
+  const parsed = __testOnly.parseProjectDocumentsArgs({
+    args: [
+      "list",
+      "--profile",
+      "work",
+      "--project-id",
+      "proj_123",
+      "--project-name",
+      "Platform",
+      "--team-id",
+      "team_123",
+      "--path",
+      ".hack/linear/projects/proj_123/documents",
+      "--json",
+    ],
+  });
+
+  expect(parsed.ok).toBe(true);
+  if (!parsed.ok) {
+    return;
+  }
+
+  expect(parsed.value).toEqual({
+    verb: "list",
+    profileId: "work",
+    projectId: "proj_123",
+    projectName: "Platform",
+    teamId: "team_123",
+    path: ".hack/linear/projects/proj_123/documents",
+    json: true,
+  });
+});
+
+test("parseProjectMilestonesArgs parses apply verbs and file paths", () => {
+  const parsed = __testOnly.parseProjectMilestonesArgs({
+    args: [
+      "apply",
+      "--path",
+      ".hack/linear/projects/proj_123/milestones/private-beta.md",
+      "--json",
+    ],
+  });
+
+  expect(parsed.ok).toBe(true);
+  if (!parsed.ok) {
+    return;
+  }
+
+  expect(parsed.value).toEqual({
+    verb: "apply",
+    path: ".hack/linear/projects/proj_123/milestones/private-beta.md",
+    json: true,
+  });
+});
+
+test("parseProjectStatusUpdatesArgs parses publish verbs", () => {
+  const parsed = __testOnly.parseProjectStatusUpdatesArgs({
+    args: [
+      "publish",
+      "--profile",
+      "work",
+      "--project-id",
+      "proj_123",
+      "--path",
+      ".hack/linear/projects/proj_123/status-updates/drafts/2026-03-14-weekly.md",
+    ],
+  });
+
+  expect(parsed.ok).toBe(true);
+  if (!parsed.ok) {
+    return;
+  }
+
+  expect(parsed.value).toEqual({
+    verb: "publish",
+    profileId: "work",
+    projectId: "proj_123",
+    path: ".hack/linear/projects/proj_123/status-updates/drafts/2026-03-14-weekly.md",
+    json: false,
+  });
+});
+
+test("parseProjectDocumentsArgs rejects unsupported verbs", () => {
+  const parsed = __testOnly.parseProjectDocumentsArgs({
+    args: ["publish"],
+  });
+
+  expect(parsed.ok).toBe(false);
+  if (parsed.ok) {
+    return;
+  }
+
+  expect(parsed.error).toContain("Expected list|pull|plan|apply|archive");
+});

From 957c2ad25673ad9dd388c7c0e347c0011c768e63 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:29:16 +0000
Subject: [PATCH 032/134] feat(tickets): finalize normalization core flow

---
 docs/guides/tickets.md                        |    2 +
 .../extensions/linear/commands.ts             |   22 +-
 .../extensions/tickets/commands.ts            | 1665 +++++++++--------
 src/control-plane/extensions/tickets/store.ts |  965 ++++++----
 .../extensions/tickets/tickets-git-channel.ts |  365 ++--
 tests/linear-commands.test.ts                 |  158 ++
 tests/tickets-store.test.ts                   |    6 +-
 7 files changed, 1956 insertions(+), 1227 deletions(-)

diff --git a/docs/guides/tickets.md b/docs/guides/tickets.md
index c70da16d6..94fcb0f5e 100644
--- a/docs/guides/tickets.md
+++ b/docs/guides/tickets.md
@@ -144,6 +144,8 @@ In your project repo:
 Portability rules:
 
 - Only the journal under `.hack/tickets/events/` is portable ticket state.
+- The hidden ref stores only the journal tree; it does not include `projection.sqlite` or other local cache files.
+- After `hack x tickets sync`, the checked-out tickets worktree materializes that journal under `.hack/tickets/git/worktree/.hack/tickets/events/`.
 - The SQLite projection is local-only and can be deleted safely.
 - After sync or clone, peers rebuild `.hack/tickets/projection.sqlite` from the journal on first read.
 
diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index 313811047..0df57957f 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -2907,9 +2907,15 @@ type LinearDeliverySummary = {
 
 function resolveTicketAuthority(input: {
   readonly ticket: TicketSummary;
-}): "hack" | "linear" {
+}): "hack" | "linear" | "review_required" {
   const owner = input.ticket.owner.trim().toLowerCase();
   const source = input.ticket.source.trim().toLowerCase();
+  if (
+    (owner === "linear" && source !== "linear") ||
+    (source === "linear" && owner !== "linear")
+  ) {
+    return "review_required";
+  }
   if (owner === "linear" || source === "linear") {
     return "linear";
   }
@@ -2947,7 +2953,7 @@ function normalizeProjectValue(input: {
 }
 
 function detectAuthoritativeFieldConflicts(input: {
-  readonly authority: "hack" | "linear";
+  readonly authority: "hack" | "linear" | "review_required";
   readonly ticket: TicketSummary;
   readonly issue: LinearIssue;
   readonly remoteProjection: Pick<
@@ -2956,13 +2962,15 @@ function detectAuthoritativeFieldConflicts(input: {
   >;
 }): readonly RecordedSyncConflict[] {
   const conflicts: RecordedSyncConflict[] = [];
+  const authorityLabel =
+    input.authority === "review_required" ? "review-required" : input.authority;
   const localTitle = input.ticket.title.trim();
   const remoteTitle = input.issue.title.trim();
   if (localTitle !== remoteTitle) {
     conflicts.push({
       field: "title",
       authority: input.authority,
-      summary: `Authoritative ${input.authority} title diverged from the other side.`,
+      summary: `Authoritative ${authorityLabel} title diverged from the other side.`,
       localValue: localTitle,
       remoteValue: remoteTitle,
     });
@@ -2978,7 +2986,7 @@ function detectAuthoritativeFieldConflicts(input: {
     conflicts.push({
       field: "body",
       authority: input.authority,
-      summary: `Authoritative ${input.authority} body diverged from the other side.`,
+      summary: `Authoritative ${authorityLabel} body diverged from the other side.`,
       localValue: localBody,
       remoteValue: remoteBody,
     });
@@ -2988,7 +2996,7 @@ function detectAuthoritativeFieldConflicts(input: {
     conflicts.push({
       field: "status",
       authority: input.authority,
-      summary: `Authoritative ${input.authority} status diverged from the other side.`,
+      summary: `Authoritative ${authorityLabel} status diverged from the other side.`,
       localValue: input.ticket.status,
       remoteValue: input.remoteProjection.status,
     });
@@ -3009,7 +3017,7 @@ function detectAuthoritativeFieldConflicts(input: {
     conflicts.push({
       field: "project",
       authority: input.authority,
-      summary: `Authoritative ${input.authority} project routing diverged from the other side.`,
+      summary: `Authoritative ${authorityLabel} project routing diverged from the other side.`,
       ...(localProject !== undefined ? { localValue: localProject } : {}),
       ...(remoteProject !== undefined ? { remoteValue: remoteProject } : {}),
     });
@@ -4792,7 +4800,7 @@ async function applyLinearIssueToExistingTicket(input: {
   readonly existingTicket: TicketSummary;
   readonly projection: TicketProjectionFromLinearIssue;
   readonly syncToggles: SyncToggles;
-  readonly authority: "hack" | "linear";
+  readonly authority: "hack" | "linear" | "review_required";
   readonly conflictsRecorded: number;
 }): Promise<
   SyncTicketFromLinearSuccess | { readonly ok: false; readonly error: string }
diff --git a/src/control-plane/extensions/tickets/commands.ts b/src/control-plane/extensions/tickets/commands.ts
index 82192f283..207139492 100644
--- a/src/control-plane/extensions/tickets/commands.ts
+++ b/src/control-plane/extensions/tickets/commands.ts
@@ -885,7 +885,8 @@ export const TICKETS_COMMANDS: readonly ExtensionCommand[] = [
     summary: "Show a ticket",
     scope: "project",
     handler: async ({ ctx, args }) => {
-      if (!ctx.project) {
+      const project = ctx.project;
+      if (!project) {
         ctx.logger.error({ message: "No project found. Run inside a repo." });
         return 1;
       }
@@ -905,7 +906,7 @@ export const TICKETS_COMMANDS: readonly ExtensionCommand[] = [
       await maybeEnsureTicketsSetup({ ctx, json: parsed.value.json });
 
       const store = createTicketsStore({
-        projectRoot: ctx.project.projectRoot,
+        projectRoot: project.projectRoot,
         projectId: ctx.projectId,
         projectName: ctx.projectName,
         controlPlaneConfig: ctx.controlPlaneConfig,
@@ -919,135 +920,9 @@ export const TICKETS_COMMANDS: readonly ExtensionCommand[] = [
         return 1;
       }
 
-      if (parsed.value.json) {
-        process.stdout.write(
-          `${JSON.stringify(
-            {
-              ticket,
-              documents: detail.documents,
-              comments: detail.comments,
-              reviewNotes: detail.reviewNotes,
-              syncCheckpoints: detail.syncCheckpoints,
-              conflicts: detail.conflicts,
-              events: detail.events,
-            },
-            null,
-            2
-          )}\n`
-        );
-        return 0;
-      }
-
-      await display.kv({
-        title: `Ticket ${ticket.ticketId}`,
-        entries: [
-          ["title", ticket.title],
-          ["status", ticket.status],
-          ["owner", ticket.owner],
-          ["source", ticket.source],
-          ["assignee", ticket.assignee ?? ""],
-          ["tags", ticket.tags.join(", ")],
-          ["external_system", ticket.externalSystem ?? ""],
-          ["external_id", ticket.externalId ?? ""],
-          ["external_key", ticket.externalKey ?? ""],
-          ["external_url", ticket.externalUrl ?? ""],
-          ["external_project_id", ticket.externalProjectId ?? ""],
-          ["external_project_name", ticket.externalProjectName ?? ""],
-          ["external_team_id", ticket.externalTeamId ?? ""],
-          ["depends_on", ticket.dependsOn.join(", ")],
-          ["blocks", ticket.blocks.join(", ")],
-          ["created_at", ticket.createdAt],
-          ["updated_at", ticket.updatedAt],
-          ["project_id", ticket.projectId ?? ""],
-          ["project_name", ticket.projectName ?? ""],
-        ],
-      });
-
-      if (ticket.body) {
-        await display.panel({
-          title: "Body",
-          tone: "info",
-          lines: ticket.body.split("\n"),
-        });
-      }
-
-      if (detail.documents.length > 0) {
-        await display.table({
-          columns: ["document_id", "kind", "role", "updated_at"],
-          rows: detail.documents.map((document) => [
-            document.documentId,
-            document.kind,
-            document.role,
-            document.updatedAt,
-          ]),
-        });
-      }
-
-      if (detail.comments.length > 0) {
-        await display.table({
-          columns: ["comment_id", "source", "actor", "created_at", "body"],
-          rows: detail.comments.map((comment) => [
-            comment.commentId,
-            comment.source,
-            comment.actor,
-            comment.createdAt,
-            comment.body,
-          ]),
-        });
-      }
-
-      if (detail.reviewNotes.length > 0) {
-        await display.table({
-          columns: ["note_id", "actor", "created_at", "context", "body"],
-          rows: detail.reviewNotes.map((reviewNote) => [
-            reviewNote.noteId,
-            reviewNote.actor,
-            reviewNote.createdAt,
-            reviewNote.context ?? "",
-            reviewNote.body,
-          ]),
-        });
-      }
-
-      if (detail.syncCheckpoints.length > 0) {
-        await display.table({
-          columns: [
-            "checkpoint_id",
-            "provider",
-            "profile",
-            "direction",
-            "cursor",
-          ],
-          rows: detail.syncCheckpoints.map((checkpoint) => [
-            checkpoint.checkpointId,
-            checkpoint.provider,
-            checkpoint.profileId ?? "",
-            checkpoint.direction ?? "",
-            checkpoint.remoteCursor ?? "",
-          ]),
-        });
-      }
-
-      if (detail.conflicts.length > 0) {
-        await display.table({
-          columns: ["conflict_id", "field", "status", "provider", "resolution"],
-          rows: detail.conflicts.map((conflict) => [
-            conflict.conflictId,
-            conflict.field,
-            conflict.status,
-            conflict.provider,
-            conflict.resolution ?? "",
-          ]),
-        });
-      }
-
-      await display.table({
-        columns: ["ts", "type", "event_id"],
-        rows: detail.events.map((event) => [
-          event.tsIso,
-          event.type,
-          event.eventId,
-        ]),
+      await renderTicketDetail({
+        detail,
+        json: parsed.value.json,
       });
       return 0;
     },
@@ -1308,556 +1183,637 @@ type TicketsSetupParseResult =
   | { readonly ok: true; readonly value: TicketsSetupArgs }
   | { readonly ok: false; readonly error: string };
 
+type MutableTicketsArgs = {
+  title?: string;
+  body?: string;
+  bodyFile?: string;
+  bodyStdin: boolean;
+  kind?: TicketDocumentKind;
+  role?: TicketDocumentRole;
+  dependsOn: string[];
+  blocks: string[];
+  clearDependsOn: boolean;
+  clearBlocks: boolean;
+  owner?: string;
+  source?: string;
+  assignee?: string;
+  clearAssignee: boolean;
+  tags: string[];
+  clearTags: boolean;
+  externalSystem?: string;
+  externalId?: string;
+  externalKey?: string;
+  externalUrl?: string;
+  externalProjectId?: string;
+  externalProjectName?: string;
+  externalTeamId?: string;
+  actor?: string;
+  json: boolean;
+  rest: string[];
+};
+
+type MutableResolveConflictArgs = {
+  conflictId?: string;
+  resolution?: TicketSyncConflictResolution;
+  summary?: string;
+  actor?: string;
+  json: boolean;
+  rest: string[];
+};
+
+type MutableTicketsSetupArgs = {
+  agents: boolean;
+  claude: boolean;
+  all: boolean;
+  global: boolean;
+  check: boolean;
+  remove: boolean;
+  json: boolean;
+};
+
+type TicketsSetupNeeds = {
+  readonly needsGitignore: boolean;
+  readonly needsUntrack: boolean;
+  readonly needsSkill: boolean;
+  readonly needsDocs: boolean;
+};
+
+type TicketDetailResult = Awaited<
+  ReturnType<ReturnType<typeof createTicketsStore>["getTicketDetail"]>
+>;
+
+type TicketsGitHealthSummary = {
+  readonly hasRefDivergence: boolean;
+  readonly hasLegacyRef: boolean;
+  readonly legacyRef?: string;
+  readonly hasNonTicketFiles: boolean;
+  readonly nonTicketPaths: readonly string[];
+  readonly remoteRefOid?: string;
+  readonly legacyRefOid?: string;
+};
+
+type TicketsRepairSummary = {
+  readonly didCommit: boolean;
+  readonly didPush: boolean;
+  readonly pruneError?: string;
+};
+
+type ParseHandlerResult = {
+  readonly handled: boolean;
+  readonly nextIndex: number;
+  readonly error?: string;
+};
+
+type ConsumedOptionValue =
+  | { readonly matched: false }
+  | {
+      readonly matched: true;
+      readonly nextIndex: number;
+      readonly value?: string;
+      readonly error?: string;
+    };
+
+type TicketsSetupTokenResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly error: string };
+
 function parseTicketsArgs(opts: {
   readonly args: readonly string[];
 }): TicketsParseResult {
-  const rest: string[] = [];
-  let title: string | undefined;
-  let body: string | undefined;
-  let bodyFile: string | undefined;
-  let bodyStdin = false;
-  let kind: TicketDocumentKind | undefined;
-  let role: TicketDocumentRole | undefined;
-  const dependsOn: string[] = [];
-  const blocks: string[] = [];
-  let clearDependsOn = false;
-  let clearBlocks = false;
-  let owner: string | undefined;
-  let source: string | undefined;
-  let assignee: string | undefined;
-  let clearAssignee = false;
-  const tags: string[] = [];
-  let clearTags = false;
-  let externalSystem: string | undefined;
-  let externalId: string | undefined;
-  let externalKey: string | undefined;
-  let externalUrl: string | undefined;
-  let externalProjectId: string | undefined;
-  let externalProjectName: string | undefined;
-  let externalTeamId: string | undefined;
-  let actor: string | undefined;
-  let json = false;
-
-  const takeValue = (
-    _flag: string,
-    value: string | undefined
-  ): string | null => {
-    if (!value || value.startsWith("-")) {
-      return null;
-    }
-    return value;
+  const state: MutableTicketsArgs = {
+    bodyStdin: false,
+    dependsOn: [],
+    blocks: [],
+    clearDependsOn: false,
+    clearBlocks: false,
+    clearAssignee: false,
+    tags: [],
+    clearTags: false,
+    json: false,
+    rest: [],
   };
 
   for (let i = 0; i < opts.args.length; i += 1) {
     const token = opts.args[i] ?? "";
 
     if (token === "--") {
-      rest.push(...opts.args.slice(i + 1));
+      state.rest.push(...opts.args.slice(i + 1));
       break;
     }
 
     if (token === "--json") {
-      json = true;
-      continue;
-    }
-
-    if (token.startsWith("--title=")) {
-      title = token.slice("--title=".length);
+      state.json = true;
       continue;
     }
-
-    if (token === "--title") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--title requires a value." };
+    const handlers = [
+      parseTicketContentOption,
+      parseTicketDocumentOption,
+      parseTicketRelationshipOption,
+      parseTicketIdentityOption,
+      parseTicketTagOption,
+      parseTicketExternalOption,
+    ] as const;
+    let handled = false;
+    for (const handler of handlers) {
+      const result = handler({
+        args: opts.args,
+        index: i,
+        state,
+      });
+      if (result.error) {
+        return { ok: false, error: result.error };
       }
-      title = value;
-      i += 1;
-      continue;
-    }
-
-    if (token.startsWith("--body=")) {
-      body = token.slice("--body=".length);
-      continue;
-    }
-
-    if (token === "--body") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--body requires a value." };
+      if (result.handled) {
+        i = result.nextIndex;
+        handled = true;
+        break;
       }
-      body = value;
-      i += 1;
-      continue;
-    }
-
-    if (token.startsWith("--body-file=")) {
-      bodyFile = token.slice("--body-file=".length);
-      continue;
     }
-
-    if (token === "--body-file") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--body-file requires a value." };
-      }
-      bodyFile = value;
-      i += 1;
+    if (handled) {
       continue;
     }
 
-    if (token === "--body-stdin") {
-      bodyStdin = true;
-      continue;
+    if (token.startsWith("-")) {
+      return { ok: false, error: `Unknown option: ${token}` };
     }
 
-    if (token.startsWith("--kind=")) {
-      const value = token.slice("--kind=".length);
-      if (!isTicketDocumentKind(value)) {
-        return {
-          ok: false,
-          error: "Invalid --kind value. Expected description|spec|notes.",
-        };
-      }
-      kind = value;
-      continue;
-    }
+    state.rest.push(token);
+  }
 
-    if (token === "--kind") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--kind requires a value." };
-      }
-      if (!isTicketDocumentKind(value)) {
-        return {
-          ok: false,
-          error: "Invalid --kind value. Expected description|spec|notes.",
-        };
-      }
-      kind = value;
-      i += 1;
-      continue;
-    }
+  return {
+    ok: true,
+    value: finalizeTicketsArgs(state),
+  };
+}
 
-    if (token.startsWith("--role=")) {
-      const value = token.slice("--role=".length);
-      if (!isTicketDocumentRole(value)) {
-        return {
-          ok: false,
-          error:
-            "Invalid --role value. Expected description|spec|notes|handoff.",
-        };
-      }
-      role = value;
-      continue;
-    }
+function parseResolveConflictArgs(opts: {
+  readonly args: readonly string[];
+}):
+  | { readonly ok: true; readonly value: ResolveConflictArgs }
+  | { readonly ok: false; readonly error: string } {
+  const state: MutableResolveConflictArgs = {
+    json: false,
+    rest: [],
+  };
 
-    if (token === "--role") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--role requires a value." };
-      }
-      if (!isTicketDocumentRole(value)) {
-        return {
-          ok: false,
-          error:
-            "Invalid --role value. Expected description|spec|notes|handoff.",
-        };
-      }
-      role = value;
-      i += 1;
-      continue;
+  for (let i = 0; i < opts.args.length; i += 1) {
+    const token = opts.args[i] ?? "";
+    if (token === "--") {
+      state.rest.push(...opts.args.slice(i + 1));
+      break;
     }
-
-    if (token === "--clear-depends-on") {
-      clearDependsOn = true;
+    if (token === "--json") {
+      state.json = true;
       continue;
     }
 
-    if (token === "--clear-blocks") {
-      clearBlocks = true;
-      continue;
-    }
-    if (token === "--clear-tags") {
-      clearTags = true;
-      continue;
+    const result = parseResolveConflictOption({
+      args: opts.args,
+      index: i,
+      state,
+    });
+    if (result.error) {
+      return { ok: false, error: result.error };
     }
-    if (token === "--clear-assignee") {
-      clearAssignee = true;
+    if (result.handled) {
+      i = result.nextIndex;
       continue;
     }
 
-    if (token.startsWith("--depends-on=")) {
-      dependsOn.push(...splitTicketRefs(token.slice("--depends-on=".length)));
-      continue;
+    if (token.startsWith("-")) {
+      return { ok: false, error: `Unknown option: ${token}` };
     }
+    state.rest.push(token);
+  }
 
-    if (token === "--depends-on") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--depends-on requires a value." };
-      }
-      dependsOn.push(...splitTicketRefs(value));
-      i += 1;
-      continue;
-    }
+  if (!state.conflictId) {
+    return { ok: false, error: "Missing --conflict-id <ID>." };
+  }
+  if (!state.resolution) {
+    return {
+      ok: false,
+      error: "Missing --resolution <accept_local|accept_remote|merged|ignore>.",
+    };
+  }
 
-    if (token.startsWith("--blocks=")) {
-      blocks.push(...splitTicketRefs(token.slice("--blocks=".length)));
-      continue;
-    }
+  return {
+    ok: true,
+    value: {
+      conflictId: state.conflictId,
+      resolution: state.resolution,
+      ...(state.summary !== undefined ? { summary: state.summary } : {}),
+      ...(state.actor ? { actor: state.actor } : {}),
+      json: state.json,
+      rest: state.rest,
+    },
+  };
+}
 
-    if (token === "--blocks") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--blocks requires a value." };
-      }
-      blocks.push(...splitTicketRefs(value));
-      i += 1;
-      continue;
-    }
+function finalizeTicketsArgs(state: MutableTicketsArgs): TicketsArgs {
+  return {
+    ...(state.title ? { title: state.title } : {}),
+    ...(state.body ? { body: state.body } : {}),
+    ...(state.bodyFile ? { bodyFile: state.bodyFile } : {}),
+    bodyStdin: state.bodyStdin,
+    ...(state.kind ? { kind: state.kind } : {}),
+    ...(state.role ? { role: state.role } : {}),
+    dependsOn: state.dependsOn,
+    blocks: state.blocks,
+    clearDependsOn: state.clearDependsOn,
+    clearBlocks: state.clearBlocks,
+    ...(state.owner ? { owner: state.owner } : {}),
+    ...(state.source ? { source: state.source } : {}),
+    ...(state.assignee !== undefined ? { assignee: state.assignee } : {}),
+    clearAssignee: state.clearAssignee,
+    tags: normalizeTags(state.tags),
+    clearTags: state.clearTags,
+    ...(state.externalSystem !== undefined
+      ? { externalSystem: state.externalSystem }
+      : {}),
+    ...(state.externalId !== undefined ? { externalId: state.externalId } : {}),
+    ...(state.externalKey !== undefined
+      ? { externalKey: state.externalKey }
+      : {}),
+    ...(state.externalUrl !== undefined
+      ? { externalUrl: state.externalUrl }
+      : {}),
+    ...(state.externalProjectId !== undefined
+      ? { externalProjectId: state.externalProjectId }
+      : {}),
+    ...(state.externalProjectName !== undefined
+      ? { externalProjectName: state.externalProjectName }
+      : {}),
+    ...(state.externalTeamId !== undefined
+      ? { externalTeamId: state.externalTeamId }
+      : {}),
+    ...(state.actor ? { actor: state.actor } : {}),
+    json: state.json,
+    rest: state.rest,
+  };
+}
 
-    if (token.startsWith("--actor=")) {
-      actor = token.slice("--actor=".length);
-      continue;
-    }
+function consumeOptionValue(opts: {
+  readonly args: readonly string[];
+  readonly index: number;
+  readonly flag: string;
+}): ConsumedOptionValue {
+  const token = opts.args[opts.index] ?? "";
+  if (token.startsWith(`${opts.flag}=`)) {
+    return {
+      matched: true,
+      nextIndex: opts.index,
+      value: token.slice(opts.flag.length + 1),
+    };
+  }
+  if (token !== opts.flag) {
+    return { matched: false };
+  }
+  const value = opts.args[opts.index + 1];
+  if (!value || value.startsWith("-")) {
+    return {
+      matched: true,
+      nextIndex: opts.index,
+      error: `${opts.flag} requires a value.`,
+    };
+  }
+  return {
+    matched: true,
+    nextIndex: opts.index + 1,
+    value,
+  };
+}
 
-    if (token.startsWith("--owner=")) {
-      owner = token.slice("--owner=".length);
-      continue;
-    }
-    if (token === "--owner") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--owner requires a value." };
-      }
-      owner = value;
-      i += 1;
-      continue;
-    }
-    if (token.startsWith("--source=")) {
-      source = token.slice("--source=".length);
-      continue;
-    }
-    if (token === "--source") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--source requires a value." };
-      }
-      source = value;
-      i += 1;
-      continue;
-    }
-    if (token.startsWith("--assignee=")) {
-      assignee = token.slice("--assignee=".length);
-      continue;
-    }
-    if (token === "--assignee") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--assignee requires a value." };
-      }
-      assignee = value;
-      i += 1;
-      continue;
-    }
-    if (token.startsWith("--tags=")) {
-      tags.push(...splitTags(token.slice("--tags=".length)));
-      continue;
-    }
-    if (token === "--tags") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--tags requires a value." };
-      }
-      tags.push(...splitTags(value));
-      i += 1;
-      continue;
-    }
-    if (token.startsWith("--tag=")) {
-      tags.push(token.slice("--tag=".length));
-      continue;
-    }
-    if (token === "--tag") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--tag requires a value." };
-      }
-      tags.push(value);
-      i += 1;
-      continue;
-    }
-    if (token.startsWith("--external-system=")) {
-      externalSystem = token.slice("--external-system=".length);
-      continue;
-    }
-    if (token === "--external-system") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--external-system requires a value." };
-      }
-      externalSystem = value;
-      i += 1;
-      continue;
-    }
-    if (token.startsWith("--external-id=")) {
-      externalId = token.slice("--external-id=".length);
-      continue;
-    }
-    if (token === "--external-id") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--external-id requires a value." };
-      }
-      externalId = value;
-      i += 1;
-      continue;
-    }
-    if (token.startsWith("--external-key=")) {
-      externalKey = token.slice("--external-key=".length);
-      continue;
-    }
-    if (token === "--external-key") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--external-key requires a value." };
-      }
-      externalKey = value;
-      i += 1;
-      continue;
-    }
-    if (token.startsWith("--external-url=")) {
-      externalUrl = token.slice("--external-url=".length);
-      continue;
-    }
-    if (token === "--external-url") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--external-url requires a value." };
-      }
-      externalUrl = value;
-      i += 1;
-      continue;
-    }
-    if (token.startsWith("--external-project-id=")) {
-      externalProjectId = token.slice("--external-project-id=".length);
-      continue;
-    }
-    if (token === "--external-project-id") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--external-project-id requires a value." };
-      }
-      externalProjectId = value;
-      i += 1;
-      continue;
-    }
-    if (token.startsWith("--external-project-name=")) {
-      externalProjectName = token.slice("--external-project-name=".length);
+function parseTicketContentOption(opts: {
+  readonly args: readonly string[];
+  readonly index: number;
+  readonly state: MutableTicketsArgs;
+}): ParseHandlerResult {
+  const bodyStdinToken = opts.args[opts.index];
+  if (bodyStdinToken === "--body-stdin") {
+    opts.state.bodyStdin = true;
+    return { handled: true, nextIndex: opts.index };
+  }
+
+  for (const [flag, assign] of [
+    ["--title", (value: string | undefined) => (opts.state.title = value)],
+    ["--body", (value: string | undefined) => (opts.state.body = value)],
+    [
+      "--body-file",
+      (value: string | undefined) => (opts.state.bodyFile = value),
+    ],
+  ] as const) {
+    const consumed = consumeOptionValue({
+      args: opts.args,
+      index: opts.index,
+      flag,
+    });
+    if (!consumed.matched) {
       continue;
     }
-    if (token === "--external-project-name") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return {
-          ok: false,
-          error: "--external-project-name requires a value.",
-        };
-      }
-      externalProjectName = value;
-      i += 1;
-      continue;
+    if (consumed.error) {
+      return {
+        handled: true,
+        nextIndex: consumed.nextIndex,
+        error: consumed.error,
+      };
     }
-    if (token.startsWith("--external-team-id=")) {
-      externalTeamId = token.slice("--external-team-id=".length);
+    assign(consumed.value);
+    return { handled: true, nextIndex: consumed.nextIndex };
+  }
+
+  return { handled: false, nextIndex: opts.index };
+}
+
+function parseTicketDocumentOption(opts: {
+  readonly args: readonly string[];
+  readonly index: number;
+  readonly state: MutableTicketsArgs;
+}): ParseHandlerResult {
+  for (const [flag, kind, error] of [
+    [
+      "--kind",
+      (value: string) => (isTicketDocumentKind(value) ? value : null),
+      "Invalid --kind value. Expected description|spec|notes.",
+    ],
+    [
+      "--role",
+      (value: string) => (isTicketDocumentRole(value) ? value : null),
+      "Invalid --role value. Expected description|spec|notes|handoff.",
+    ],
+  ] as const) {
+    const consumed = consumeOptionValue({
+      args: opts.args,
+      index: opts.index,
+      flag,
+    });
+    if (!consumed.matched) {
       continue;
     }
-    if (token === "--external-team-id") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--external-team-id requires a value." };
-      }
-      externalTeamId = value;
-      i += 1;
-      continue;
+    if (consumed.error) {
+      return {
+        handled: true,
+        nextIndex: consumed.nextIndex,
+        error: consumed.error,
+      };
     }
-
-    if (token === "--actor") {
-      const value = takeValue(token, opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--actor requires a value." };
-      }
-      actor = value;
-      i += 1;
-      continue;
+    const value = kind(consumed.value ?? "");
+    if (!value) {
+      return {
+        handled: true,
+        nextIndex: consumed.nextIndex,
+        error,
+      };
     }
-
-    if (token.startsWith("-")) {
-      return { ok: false, error: `Unknown option: ${token}` };
+    if (flag === "--kind") {
+      opts.state.kind = value;
+    } else {
+      opts.state.role = value;
     }
-
-    rest.push(token);
+    return { handled: true, nextIndex: consumed.nextIndex };
   }
 
-  return {
-    ok: true,
-    value: {
-      ...(title ? { title } : {}),
-      ...(body ? { body } : {}),
-      ...(bodyFile ? { bodyFile } : {}),
-      bodyStdin,
-      ...(kind ? { kind } : {}),
-      ...(role ? { role } : {}),
-      dependsOn,
-      blocks,
-      clearDependsOn,
-      clearBlocks,
-      ...(owner ? { owner } : {}),
-      ...(source ? { source } : {}),
-      ...(assignee !== undefined ? { assignee } : {}),
-      clearAssignee,
-      tags: normalizeTags(tags),
-      clearTags,
-      ...(externalSystem !== undefined ? { externalSystem } : {}),
-      ...(externalId !== undefined ? { externalId } : {}),
-      ...(externalKey !== undefined ? { externalKey } : {}),
-      ...(externalUrl !== undefined ? { externalUrl } : {}),
-      ...(externalProjectId !== undefined ? { externalProjectId } : {}),
-      ...(externalProjectName !== undefined ? { externalProjectName } : {}),
-      ...(externalTeamId !== undefined ? { externalTeamId } : {}),
-      ...(actor ? { actor } : {}),
-      json,
-      rest,
-    },
-  };
+  return { handled: false, nextIndex: opts.index };
 }
 
-function parseResolveConflictArgs(opts: {
+function parseTicketRelationshipOption(opts: {
   readonly args: readonly string[];
-}):
-  | { readonly ok: true; readonly value: ResolveConflictArgs }
-  | { readonly ok: false; readonly error: string } {
-  const rest: string[] = [];
-  let conflictId: string | undefined;
-  let resolution: TicketSyncConflictResolution | undefined;
-  let summary: string | undefined;
-  let actor: string | undefined;
-  let json = false;
-
-  const takeValue = (value: string | undefined): string | null => {
-    if (!value || value.startsWith("-")) {
-      return null;
-    }
-    return value;
-  };
-
-  for (let i = 0; i < opts.args.length; i += 1) {
-    const token = opts.args[i] ?? "";
-    if (token === "--") {
-      rest.push(...opts.args.slice(i + 1));
+  readonly index: number;
+  readonly state: MutableTicketsArgs;
+}): ParseHandlerResult {
+  const token = opts.args[opts.index] ?? "";
+  switch (token) {
+    case "--clear-depends-on":
+      opts.state.clearDependsOn = true;
+      return { handled: true, nextIndex: opts.index };
+    case "--clear-blocks":
+      opts.state.clearBlocks = true;
+      return { handled: true, nextIndex: opts.index };
+    case "--clear-tags":
+      opts.state.clearTags = true;
+      return { handled: true, nextIndex: opts.index };
+    case "--clear-assignee":
+      opts.state.clearAssignee = true;
+      return { handled: true, nextIndex: opts.index };
+    default:
       break;
-    }
-    if (token === "--json") {
-      json = true;
+  }
+
+  for (const [flag, assign] of [
+    [
+      "--depends-on",
+      (value: string) => opts.state.dependsOn.push(...splitTicketRefs(value)),
+    ],
+    [
+      "--blocks",
+      (value: string) => opts.state.blocks.push(...splitTicketRefs(value)),
+    ],
+  ] as const) {
+    const consumed = consumeOptionValue({
+      args: opts.args,
+      index: opts.index,
+      flag,
+    });
+    if (!consumed.matched) {
       continue;
     }
-    if (token.startsWith("--conflict-id=")) {
-      conflictId = token.slice("--conflict-id=".length);
-      continue;
+    if (consumed.error) {
+      return {
+        handled: true,
+        nextIndex: consumed.nextIndex,
+        error: consumed.error,
+      };
     }
-    if (token === "--conflict-id") {
-      const value = takeValue(opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--conflict-id requires a value." };
-      }
-      conflictId = value;
-      i += 1;
+    assign(consumed.value ?? "");
+    return { handled: true, nextIndex: consumed.nextIndex };
+  }
+
+  return { handled: false, nextIndex: opts.index };
+}
+
+function parseTicketIdentityOption(opts: {
+  readonly args: readonly string[];
+  readonly index: number;
+  readonly state: MutableTicketsArgs;
+}): ParseHandlerResult {
+  for (const [flag, assign] of [
+    ["--actor", (value: string | undefined) => (opts.state.actor = value)],
+    ["--owner", (value: string | undefined) => (opts.state.owner = value)],
+    ["--source", (value: string | undefined) => (opts.state.source = value)],
+    [
+      "--assignee",
+      (value: string | undefined) => (opts.state.assignee = value),
+    ],
+  ] as const) {
+    const consumed = consumeOptionValue({
+      args: opts.args,
+      index: opts.index,
+      flag,
+    });
+    if (!consumed.matched) {
       continue;
     }
-    if (token.startsWith("--resolution=")) {
-      const parsedResolution = parseConflictResolutionValue({
-        value: token.slice("--resolution=".length),
-      });
-      if (!parsedResolution) {
-        return {
-          ok: false,
-          error:
-            "Invalid --resolution value. Expected accept_local|accept_remote|merged|ignore.",
-        };
-      }
-      resolution = parsedResolution;
-      continue;
+    if (consumed.error) {
+      return {
+        handled: true,
+        nextIndex: consumed.nextIndex,
+        error: consumed.error,
+      };
     }
-    if (token === "--resolution") {
-      const value = takeValue(opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--resolution requires a value." };
-      }
-      const parsedResolution = parseConflictResolutionValue({ value });
-      if (!parsedResolution) {
-        return {
-          ok: false,
-          error:
-            "Invalid --resolution value. Expected accept_local|accept_remote|merged|ignore.",
-        };
-      }
-      resolution = parsedResolution;
-      i += 1;
+    assign(consumed.value);
+    return { handled: true, nextIndex: consumed.nextIndex };
+  }
+
+  return { handled: false, nextIndex: opts.index };
+}
+
+function parseTicketTagOption(opts: {
+  readonly args: readonly string[];
+  readonly index: number;
+  readonly state: MutableTicketsArgs;
+}): ParseHandlerResult {
+  for (const [flag, split] of [
+    ["--tags", splitTags],
+    ["--tag", (value: string) => [value]],
+  ] as const) {
+    const consumed = consumeOptionValue({
+      args: opts.args,
+      index: opts.index,
+      flag,
+    });
+    if (!consumed.matched) {
       continue;
     }
-    if (token.startsWith("--summary=")) {
-      summary = token.slice("--summary=".length);
-      continue;
+    if (consumed.error) {
+      return {
+        handled: true,
+        nextIndex: consumed.nextIndex,
+        error: consumed.error,
+      };
     }
-    if (token === "--summary") {
-      const value = takeValue(opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--summary requires a value." };
-      }
-      summary = value;
-      i += 1;
+    opts.state.tags.push(...split(consumed.value ?? ""));
+    return { handled: true, nextIndex: consumed.nextIndex };
+  }
+
+  return { handled: false, nextIndex: opts.index };
+}
+
+function parseTicketExternalOption(opts: {
+  readonly args: readonly string[];
+  readonly index: number;
+  readonly state: MutableTicketsArgs;
+}): ParseHandlerResult {
+  for (const [flag, assign] of [
+    [
+      "--external-system",
+      (value: string | undefined) => (opts.state.externalSystem = value),
+    ],
+    [
+      "--external-id",
+      (value: string | undefined) => (opts.state.externalId = value),
+    ],
+    [
+      "--external-key",
+      (value: string | undefined) => (opts.state.externalKey = value),
+    ],
+    [
+      "--external-url",
+      (value: string | undefined) => (opts.state.externalUrl = value),
+    ],
+    [
+      "--external-project-id",
+      (value: string | undefined) => (opts.state.externalProjectId = value),
+    ],
+    [
+      "--external-project-name",
+      (value: string | undefined) => (opts.state.externalProjectName = value),
+    ],
+    [
+      "--external-team-id",
+      (value: string | undefined) => (opts.state.externalTeamId = value),
+    ],
+  ] as const) {
+    const consumed = consumeOptionValue({
+      args: opts.args,
+      index: opts.index,
+      flag,
+    });
+    if (!consumed.matched) {
       continue;
     }
-    if (token.startsWith("--actor=")) {
-      actor = token.slice("--actor=".length);
-      continue;
+    if (consumed.error) {
+      return {
+        handled: true,
+        nextIndex: consumed.nextIndex,
+        error: consumed.error,
+      };
     }
-    if (token === "--actor") {
-      const value = takeValue(opts.args[i + 1]);
-      if (!value) {
-        return { ok: false, error: "--actor requires a value." };
-      }
-      actor = value;
-      i += 1;
+    assign(consumed.value);
+    return { handled: true, nextIndex: consumed.nextIndex };
+  }
+
+  return { handled: false, nextIndex: opts.index };
+}
+
+function parseResolveConflictOption(opts: {
+  readonly args: readonly string[];
+  readonly index: number;
+  readonly state: MutableResolveConflictArgs;
+}): ParseHandlerResult {
+  for (const [flag, assign] of [
+    [
+      "--conflict-id",
+      (value: string | undefined) => (opts.state.conflictId = value),
+    ],
+    ["--summary", (value: string | undefined) => (opts.state.summary = value)],
+    ["--actor", (value: string | undefined) => (opts.state.actor = value)],
+  ] as const) {
+    const consumed = consumeOptionValue({
+      args: opts.args,
+      index: opts.index,
+      flag,
+    });
+    if (!consumed.matched) {
       continue;
     }
-    if (token.startsWith("-")) {
-      return { ok: false, error: `Unknown option: ${token}` };
+    if (consumed.error) {
+      return {
+        handled: true,
+        nextIndex: consumed.nextIndex,
+        error: consumed.error,
+      };
     }
-    rest.push(token);
+    assign(consumed.value);
+    return { handled: true, nextIndex: consumed.nextIndex };
   }
 
-  if (!conflictId) {
-    return { ok: false, error: "Missing --conflict-id <ID>." };
+  const resolution = consumeOptionValue({
+    args: opts.args,
+    index: opts.index,
+    flag: "--resolution",
+  });
+  if (!resolution.matched) {
+    return { handled: false, nextIndex: opts.index };
   }
-  if (!resolution) {
+  if (resolution.error) {
     return {
-      ok: false,
-      error: "Missing --resolution <accept_local|accept_remote|merged|ignore>.",
+      handled: true,
+      nextIndex: resolution.nextIndex,
+      error: resolution.error,
     };
   }
-
-  return {
-    ok: true,
-    value: {
-      conflictId,
-      resolution,
-      ...(summary !== undefined ? { summary } : {}),
-      ...(actor ? { actor } : {}),
-      json,
-      rest,
-    },
-  };
+  const parsedResolution = parseConflictResolutionValue({
+    value: resolution.value ?? "",
+  });
+  if (!parsedResolution) {
+    return {
+      handled: true,
+      nextIndex: resolution.nextIndex,
+      error:
+        "Invalid --resolution value. Expected accept_local|accept_remote|merged|ignore.",
+    };
+  }
+  opts.state.resolution = parsedResolution;
+  return { handled: true, nextIndex: resolution.nextIndex };
 }
 
 async function resolveTicketBody(opts: {
@@ -1968,6 +1924,154 @@ function resolveTicketRefs(opts: {
   return { ok: true, refs: normalizeTicketRefs(normalized) };
 }
 
+async function renderTicketDetail(opts: {
+  readonly detail: TicketDetailResult;
+  readonly json: boolean;
+}): Promise<void> {
+  if (opts.json) {
+    writeTicketDetailJson({ detail: opts.detail });
+    return;
+  }
+
+  await displayTicketDetailSections({ detail: opts.detail });
+}
+
+function writeTicketDetailJson(opts: {
+  readonly detail: TicketDetailResult;
+}): void {
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        ticket: opts.detail.ticket,
+        documents: opts.detail.documents,
+        comments: opts.detail.comments,
+        reviewNotes: opts.detail.reviewNotes,
+        syncCheckpoints: opts.detail.syncCheckpoints,
+        conflicts: opts.detail.conflicts,
+        events: opts.detail.events,
+      },
+      null,
+      2
+    )}\n`
+  );
+}
+
+async function displayTicketDetailSections(opts: {
+  readonly detail: TicketDetailResult;
+}): Promise<void> {
+  const { detail } = opts;
+  const ticket = detail.ticket;
+  if (!ticket) {
+    return;
+  }
+
+  await display.kv({
+    title: `Ticket ${ticket.ticketId}`,
+    entries: [
+      ["title", ticket.title],
+      ["status", ticket.status],
+      ["owner", ticket.owner],
+      ["source", ticket.source],
+      ["assignee", ticket.assignee ?? ""],
+      ["tags", ticket.tags.join(", ")],
+      ["external_system", ticket.externalSystem ?? ""],
+      ["external_id", ticket.externalId ?? ""],
+      ["external_key", ticket.externalKey ?? ""],
+      ["external_url", ticket.externalUrl ?? ""],
+      ["external_project_id", ticket.externalProjectId ?? ""],
+      ["external_project_name", ticket.externalProjectName ?? ""],
+      ["external_team_id", ticket.externalTeamId ?? ""],
+      ["depends_on", ticket.dependsOn.join(", ")],
+      ["blocks", ticket.blocks.join(", ")],
+      ["created_at", ticket.createdAt],
+      ["updated_at", ticket.updatedAt],
+      ["project_id", ticket.projectId ?? ""],
+      ["project_name", ticket.projectName ?? ""],
+    ],
+  });
+
+  if (ticket.body) {
+    await display.panel({
+      title: "Body",
+      tone: "info",
+      lines: ticket.body.split("\n"),
+    });
+  }
+
+  if (detail.documents.length > 0) {
+    await display.table({
+      columns: ["document_id", "kind", "role", "updated_at"],
+      rows: detail.documents.map((document) => [
+        document.documentId,
+        document.kind,
+        document.role,
+        document.updatedAt,
+      ]),
+    });
+  }
+
+  if (detail.comments.length > 0) {
+    await display.table({
+      columns: ["comment_id", "source", "actor", "created_at", "body"],
+      rows: detail.comments.map((comment) => [
+        comment.commentId,
+        comment.source,
+        comment.actor,
+        comment.createdAt,
+        comment.body,
+      ]),
+    });
+  }
+
+  if (detail.reviewNotes.length > 0) {
+    await display.table({
+      columns: ["note_id", "actor", "created_at", "context", "body"],
+      rows: detail.reviewNotes.map((reviewNote) => [
+        reviewNote.noteId,
+        reviewNote.actor,
+        reviewNote.createdAt,
+        reviewNote.context ?? "",
+        reviewNote.body,
+      ]),
+    });
+  }
+
+  if (detail.syncCheckpoints.length > 0) {
+    await display.table({
+      columns: ["checkpoint_id", "provider", "profile", "direction", "cursor"],
+      rows: detail.syncCheckpoints.map((checkpoint) => [
+        checkpoint.checkpointId,
+        checkpoint.provider,
+        checkpoint.profileId ?? "",
+        checkpoint.direction ?? "",
+        checkpoint.remoteCursor ?? "",
+      ]),
+    });
+  }
+
+  if (detail.conflicts.length > 0) {
+    await display.table({
+      columns: ["conflict_id", "field", "status", "provider", "resolution"],
+      rows: detail.conflicts.map((conflict) => [
+        conflict.conflictId,
+        conflict.field,
+        conflict.status,
+        conflict.provider,
+        conflict.resolution ?? "",
+      ]),
+    });
+  }
+
+  await display.table({
+    columns: ["ts", "type", "event_id"],
+    rows: detail.events.map((event) => [
+      event.tsIso,
+      event.type,
+      event.eventId,
+    ]),
+  });
+}
+
 async function maybeEnsureTicketsSetup(opts: {
   readonly ctx: ExtensionCommandContext;
   readonly json: boolean;
@@ -1988,28 +2092,13 @@ async function maybeEnsureTicketsSetup(opts: {
     targets: ["agents", "claude"],
   });
 
-  const needsGitignore = repoState.gitignore.status === "missing";
-  const needsUntrack = repoState.tracked.status === "tracked";
-  const needsSkill = skill.status === "missing" || skill.status === "error";
-  const needsDocs = docs.some(
-    (doc) => doc.status === "missing" || doc.status === "error"
-  );
-
-  if (!(needsGitignore || needsUntrack || needsSkill || needsDocs)) {
+  const needs = getTicketsSetupNeeds({ repoState, skill, docs });
+  if (!hasIncompleteTicketsSetup({ needs })) {
     return;
   }
 
   if (!(isTty() && isGumAvailable())) {
-    const notices: string[] = [];
-    if (needsGitignore) {
-      notices.push("add .hack/tickets/ to .gitignore");
-    }
-    if (needsUntrack) {
-      notices.push("untrack .hack/tickets from main branch");
-    }
-    if (needsSkill || needsDocs) {
-      notices.push("run tickets setup");
-    }
+    const notices = buildTicketsSetupNotices({ needs });
     if (notices.length > 0) {
       opts.ctx.logger.warn({
         message: `Tickets setup incomplete: ${notices.join("; ")}.`,
@@ -2026,38 +2115,7 @@ async function maybeEnsureTicketsSetup(opts: {
     return;
   }
 
-  const lines: string[] = [];
-
-  if (needsGitignore) {
-    const gitignore = await ensureTicketsGitignore({ projectRoot });
-    lines.push(`repo.gitignore: ${gitignore.status} (${gitignore.path})`);
-  }
-
-  if (needsUntrack) {
-    const untrack = await untrackTicketsRepo({ projectRoot });
-    lines.push(
-      `repo.tracking: ${untrack.status}${untrack.message ? ` (${untrack.message})` : ""}`
-    );
-  }
-
-  if (needsSkill) {
-    const installed = await installTicketsSkill({
-      scope: "project",
-      projectRoot,
-    });
-    lines.push(`skill: ${installed.status} (${installed.path})`);
-  }
-
-  if (needsDocs) {
-    const updatedDocs = await upsertTicketsAgentDocs({
-      projectRoot,
-      targets: ["agents", "claude"],
-    });
-    lines.push(
-      ...updatedDocs.map((doc) => `${doc.target}: ${doc.status} (${doc.path})`)
-    );
-  }
-
+  const lines = await repairTicketsSetup({ projectRoot, needs });
   if (lines.length > 0) {
     await display.panel({
       title: "Tickets setup",
@@ -2115,16 +2173,7 @@ async function maybeEnsureTicketsGitHealth(opts: {
     return;
   }
 
-  const reasons: string[] = [];
-  if (health.hasRefDivergence) {
-    reasons.push("hidden ref diverges from legacy branch");
-  }
-  if (health.hasLegacyRef && health.legacyRef) {
-    reasons.push(`legacy ref ${health.legacyRef}`);
-  }
-  if (health.hasNonTicketFiles) {
-    reasons.push("non-ticket files in tickets ref");
-  }
+  const reasons = buildTicketsGitHealthReasons({ health });
 
   if (!(isTty() && isGumAvailable())) {
     opts.ctx.logger.warn({
@@ -2141,14 +2190,7 @@ async function maybeEnsureTicketsGitHealth(opts: {
     return;
   }
 
-  let pruneLegacyRef = false;
-  if (health.hasLegacyRef && health.legacyRef) {
-    const prune = await gumConfirm({
-      prompt: `Remove legacy ref ${health.legacyRef} from the remote?`,
-      default: true,
-    });
-    pruneLegacyRef = prune.ok && prune.value;
-  }
+  const pruneLegacyRef = await confirmLegacyRefPrune({ health });
 
   const repaired = await channel.repair({ pruneLegacyRef });
   if (!repaired.ok) {
@@ -2160,108 +2202,249 @@ async function maybeEnsureTicketsGitHealth(opts: {
     return;
   }
 
+  const lines = buildTicketsRepairLines({
+    health,
+    repaired,
+    pruneLegacyRef,
+  });
+
+  await display.panel({
+    title: "Tickets repair",
+    tone: repaired.pruneError ? "warn" : "success",
+    lines,
+  });
+}
+
+function getTicketsSetupNeeds(opts: {
+  readonly repoState: Awaited<ReturnType<typeof checkTicketsRepoState>>;
+  readonly skill: Awaited<ReturnType<typeof checkTicketsSkill>>;
+  readonly docs: readonly TicketsAgentDocCheckResult[];
+}): TicketsSetupNeeds {
+  return {
+    needsGitignore: opts.repoState.gitignore.status === "missing",
+    needsUntrack: opts.repoState.tracked.status === "tracked",
+    needsSkill:
+      opts.skill.status === "missing" || opts.skill.status === "error",
+    needsDocs: opts.docs.some(
+      (doc) => doc.status === "missing" || doc.status === "error"
+    ),
+  };
+}
+
+function hasIncompleteTicketsSetup(opts: {
+  readonly needs: TicketsSetupNeeds;
+}): boolean {
+  return (
+    opts.needs.needsGitignore ||
+    opts.needs.needsUntrack ||
+    opts.needs.needsSkill ||
+    opts.needs.needsDocs
+  );
+}
+
+function buildTicketsSetupNotices(opts: {
+  readonly needs: TicketsSetupNeeds;
+}): string[] {
+  const notices: string[] = [];
+  if (opts.needs.needsGitignore) {
+    notices.push("add .hack/tickets/ to .gitignore");
+  }
+  if (opts.needs.needsUntrack) {
+    notices.push("untrack .hack/tickets from main branch");
+  }
+  if (opts.needs.needsSkill || opts.needs.needsDocs) {
+    notices.push("run tickets setup");
+  }
+  return notices;
+}
+
+async function repairTicketsSetup(opts: {
+  readonly projectRoot: string;
+  readonly needs: TicketsSetupNeeds;
+}): Promise<string[]> {
   const lines: string[] = [];
-  if (health.hasNonTicketFiles) {
-    const sample = health.nonTicketPaths.slice(0, 5);
-    const extra = health.nonTicketPaths.length - sample.length;
-    lines.push(`non-ticket files: ${health.nonTicketPaths.length}`);
+
+  if (opts.needs.needsGitignore) {
+    const gitignore = await ensureTicketsGitignore({
+      projectRoot: opts.projectRoot,
+    });
+    lines.push(`repo.gitignore: ${gitignore.status} (${gitignore.path})`);
+  }
+
+  if (opts.needs.needsUntrack) {
+    const untrack = await untrackTicketsRepo({ projectRoot: opts.projectRoot });
+    lines.push(
+      `repo.tracking: ${untrack.status}${untrack.message ? ` (${untrack.message})` : ""}`
+    );
+  }
+
+  if (opts.needs.needsSkill) {
+    const installed = await installTicketsSkill({
+      scope: "project",
+      projectRoot: opts.projectRoot,
+    });
+    lines.push(`skill: ${installed.status} (${installed.path})`);
+  }
+
+  if (opts.needs.needsDocs) {
+    const updatedDocs = await upsertTicketsAgentDocs({
+      projectRoot: opts.projectRoot,
+      targets: ["agents", "claude"],
+    });
+    lines.push(
+      ...updatedDocs.map((doc) => `${doc.target}: ${doc.status} (${doc.path})`)
+    );
+  }
+
+  return lines;
+}
+
+function buildTicketsGitHealthReasons(opts: {
+  readonly health: TicketsGitHealthSummary;
+}): string[] {
+  const reasons: string[] = [];
+  if (opts.health.hasRefDivergence) {
+    reasons.push("hidden ref diverges from legacy branch");
+  }
+  if (opts.health.hasLegacyRef && opts.health.legacyRef) {
+    reasons.push(`legacy ref ${opts.health.legacyRef}`);
+  }
+  if (opts.health.hasNonTicketFiles) {
+    reasons.push("non-ticket files in tickets ref");
+  }
+  return reasons;
+}
+
+async function confirmLegacyRefPrune(opts: {
+  readonly health: TicketsGitHealthSummary;
+}): Promise<boolean> {
+  if (!(opts.health.hasLegacyRef && opts.health.legacyRef)) {
+    return false;
+  }
+
+  const prune = await gumConfirm({
+    prompt: `Remove legacy ref ${opts.health.legacyRef} from the remote?`,
+    default: true,
+  });
+  return prune.ok && prune.value;
+}
+
+function buildTicketsRepairLines(opts: {
+  readonly health: TicketsGitHealthSummary;
+  readonly repaired: TicketsRepairSummary;
+  readonly pruneLegacyRef: boolean;
+}): string[] {
+  const lines: string[] = [];
+  if (opts.health.hasNonTicketFiles) {
+    const sample = opts.health.nonTicketPaths.slice(0, 5);
+    const extra = opts.health.nonTicketPaths.length - sample.length;
+    lines.push(`non-ticket files: ${opts.health.nonTicketPaths.length}`);
     if (sample.length > 0) {
       lines.push(
         `sample: ${sample.join(", ")}${extra > 0 ? ` (+${extra} more)` : ""}`
       );
     }
   }
-  if (health.hasLegacyRef && health.legacyRef) {
+  if (opts.health.hasLegacyRef && opts.health.legacyRef) {
     lines.push(
-      `legacy ref: ${health.legacyRef} ${pruneLegacyRef ? "pruned" : "left intact"}`
+      `legacy ref: ${opts.health.legacyRef} ${
+        opts.pruneLegacyRef ? "pruned" : "left intact"
+      }`
     );
   }
-  if (health.hasRefDivergence) {
+  if (opts.health.hasRefDivergence) {
     lines.push(
       `ref divergence: ${
-        health.remoteRefOid?.slice(0, 8) ?? "missing"
-      } vs ${health.legacyRefOid?.slice(0, 8) ?? "missing"}`
+        opts.health.remoteRefOid?.slice(0, 8) ?? "missing"
+      } vs ${opts.health.legacyRefOid?.slice(0, 8) ?? "missing"}`
     );
   }
-  lines.push(`commit: ${repaired.didCommit ? "created" : "noop"}`);
-  lines.push(`push: ${repaired.didPush ? "pushed" : "skipped"}`);
-  if (repaired.pruneError) {
-    lines.push(`legacy prune error: ${repaired.pruneError}`);
+  lines.push(`commit: ${opts.repaired.didCommit ? "created" : "noop"}`);
+  lines.push(`push: ${opts.repaired.didPush ? "pushed" : "skipped"}`);
+  if (opts.repaired.pruneError) {
+    lines.push(`legacy prune error: ${opts.repaired.pruneError}`);
   }
-
-  await display.panel({
-    title: "Tickets repair",
-    tone: repaired.pruneError ? "warn" : "success",
-    lines,
-  });
+  return lines;
 }
 
 function parseTicketsSetupArgs(opts: {
   readonly args: readonly string[];
 }): TicketsSetupParseResult {
-  let agents = false;
-  let claude = false;
-  let all = false;
-  let global = false;
-  let check = false;
-  let remove = false;
-  let json = false;
+  const state: MutableTicketsSetupArgs = {
+    agents: false,
+    claude: false,
+    all: false,
+    global: false,
+    check: false,
+    remove: false,
+    json: false,
+  };
 
   for (const token of opts.args) {
-    if (token === "--agents" || token === "--agents-md") {
-      agents = true;
-      continue;
+    const applied = applyTicketsSetupToken({ token, state });
+    if (!applied.ok) {
+      return applied;
     }
+  }
 
-    if (token === "--claude" || token === "--claude-md") {
-      claude = true;
-      continue;
-    }
+  if (state.check && state.remove) {
+    return { ok: false, error: "--check and --remove are mutually exclusive." };
+  }
 
-    if (token === "--all") {
-      all = true;
-      continue;
-    }
+  return {
+    ok: true,
+    value: state,
+  };
+}
 
-    if (token === "--global") {
-      global = true;
-      continue;
-    }
+function applyTicketsSetupToken(opts: {
+  readonly token: string;
+  readonly state: MutableTicketsSetupArgs;
+}): TicketsSetupTokenResult {
+  if (opts.token === "--agents" || opts.token === "--agents-md") {
+    opts.state.agents = true;
+    return { ok: true };
+  }
 
-    if (token === "--check") {
-      check = true;
-      continue;
-    }
+  if (opts.token === "--claude" || opts.token === "--claude-md") {
+    opts.state.claude = true;
+    return { ok: true };
+  }
 
-    if (token === "--remove") {
-      remove = true;
-      continue;
-    }
+  if (opts.token === "--all") {
+    opts.state.all = true;
+    return { ok: true };
+  }
 
-    if (token === "--json") {
-      json = true;
-      continue;
-    }
+  if (opts.token === "--global") {
+    opts.state.global = true;
+    return { ok: true };
+  }
 
-    if (token === "--help" || token === "help") {
-      return {
-        ok: false,
-        error:
-          "Usage: hack x tickets setup [--agents|--claude|--all] [--global] [--check|--remove] [--json]",
-      };
-    }
+  if (opts.token === "--check") {
+    opts.state.check = true;
+    return { ok: true };
+  }
 
-    return { ok: false, error: `Unknown option: ${token}` };
+  if (opts.token === "--remove") {
+    opts.state.remove = true;
+    return { ok: true };
   }
 
-  if (check && remove) {
-    return { ok: false, error: "--check and --remove are mutually exclusive." };
+  if (opts.token === "--json") {
+    opts.state.json = true;
+    return { ok: true };
   }
 
-  return {
-    ok: true,
-    value: { agents, claude, all, global, check, remove, json },
-  };
+  if (opts.token === "--help" || opts.token === "help") {
+    return {
+      ok: false,
+      error:
+        "Usage: hack x tickets setup [--agents|--claude|--all] [--global] [--check|--remove] [--json]",
+    };
+  }
+
+  return { ok: false, error: `Unknown option: ${opts.token}` };
 }
 
 /**
diff --git a/src/control-plane/extensions/tickets/store.ts b/src/control-plane/extensions/tickets/store.ts
index 5df5be9f3..a90fff7a5 100644
--- a/src/control-plane/extensions/tickets/store.ts
+++ b/src/control-plane/extensions/tickets/store.ts
@@ -188,6 +188,51 @@ type TicketStoreContext = {
   readonly snapshot: TicketStoreSnapshot;
 };
 
+type NormalizedTicketMetadata = {
+  readonly dependsOn: readonly string[];
+  readonly blocks: readonly string[];
+  readonly owner: string;
+  readonly source: string;
+  readonly assignee?: string;
+  readonly tags: readonly string[];
+  readonly externalSystem?: string;
+  readonly externalId?: string;
+  readonly externalKey?: string;
+  readonly externalUrl?: string;
+  readonly externalProjectId?: string;
+  readonly externalProjectName?: string;
+  readonly externalTeamId?: string;
+};
+
+type TicketUpdatePayloadResult =
+  | {
+      readonly ok: true;
+      readonly payload: Record<string, unknown>;
+      readonly documentContent?: string;
+    }
+  | { readonly ok: false; readonly error: string };
+
+type SyncCheckpointBuildResult =
+  | {
+      readonly ok: true;
+      readonly checkpointId: string;
+      readonly provider: string;
+      readonly payload: Record<string, unknown>;
+      readonly checkpoint: TicketSyncCheckpoint;
+    }
+  | { readonly ok: false; readonly error: string };
+
+type SyncConflictBuildResult =
+  | {
+      readonly ok: true;
+      readonly conflictId: string;
+      readonly provider: string;
+      readonly field: string;
+      readonly payload: Record<string, unknown>;
+      readonly conflict: Omit<TicketSyncConflict, "createdAt" | "updatedAt">;
+    }
+  | { readonly ok: false; readonly error: string };
+
 function normalizeTicketSummaryCompatibility(input: {
   readonly ticket: TicketSummary;
 }): TicketSummary {
@@ -695,62 +740,36 @@ export function createTicketsStore(opts: {
   return {
     createTicket: async (input) => {
       const ticketId = await computeNextTicketId();
-      const dependsOn = normalizeTicketRefs(input.dependsOn ?? []);
-      const blocks = normalizeTicketRefs(input.blocks ?? []);
-      const owner = normalizeOwnerOrSource({
-        value: input.owner,
-        fallback: "hack",
-      });
-      const source = normalizeOwnerOrSource({
-        value: input.source,
-        fallback: "hack",
-      });
-      const assignee = normalizeOptionalMetadataString({
-        value: input.assignee,
-      });
-      const tags = normalizeTags(input.tags ?? []);
-      const externalSystem = normalizeOptionalMetadataString({
-        value: input.externalSystem,
-      });
-      const externalId = normalizeOptionalMetadataString({
-        value: input.externalId,
-      });
-      const externalKey = normalizeOptionalMetadataString({
-        value: input.externalKey,
-      });
-      const externalUrl = normalizeOptionalMetadataString({
-        value: input.externalUrl,
-      });
-      const externalProjectId = normalizeOptionalMetadataString({
-        value: input.externalProjectId,
-      });
-      const externalProjectName = normalizeOptionalMetadataString({
-        value: input.externalProjectName,
+      const metadata = normalizeTicketMetadata({
+        dependsOn: input.dependsOn,
+        blocks: input.blocks,
+        owner: input.owner,
+        source: input.source,
+        assignee: input.assignee,
+        tags: input.tags,
+        externalSystem: input.externalSystem,
+        externalId: input.externalId,
+        externalKey: input.externalKey,
+        externalUrl: input.externalUrl,
+        externalProjectId: input.externalProjectId,
+        externalProjectName: input.externalProjectName,
+        externalTeamId: input.externalTeamId,
+        ownerFallback: "hack",
+        sourceFallback: "hack",
       });
-      const externalTeamId = normalizeOptionalMetadataString({
-        value: input.externalTeamId,
+      const payload: Record<string, unknown> = {
+        title: input.title,
+        ...(input.body ? { body: input.body } : {}),
+        status: "open",
+      };
+      appendTicketMetadataPayload({
+        payload,
+        metadata,
       });
       const event = buildEvent({
         ticketId,
         type: "ticket.created",
-        payload: {
-          title: input.title,
-          ...(input.body ? { body: input.body } : {}),
-          ...(dependsOn.length > 0 ? { dependsOn } : {}),
-          ...(blocks.length > 0 ? { blocks } : {}),
-          owner,
-          source,
-          ...(assignee ? { assignee } : {}),
-          ...(tags.length > 0 ? { tags } : {}),
-          ...(externalSystem ? { externalSystem } : {}),
-          ...(externalId ? { externalId } : {}),
-          ...(externalKey ? { externalKey } : {}),
-          ...(externalUrl ? { externalUrl } : {}),
-          ...(externalProjectId ? { externalProjectId } : {}),
-          ...(externalProjectName ? { externalProjectName } : {}),
-          ...(externalTeamId ? { externalTeamId } : {}),
-          status: "open",
-        },
+        payload,
         actor: input.actor,
       });
 
@@ -761,30 +780,16 @@ export function createTicketsStore(opts: {
 
       return {
         ok: true,
-        ticket: normalizeTicketSummaryCompatibility({
-          ticket: {
-            ticketId,
-            title: input.title,
-            ...(input.body ? { body: input.body } : {}),
-            status: "open",
-            createdAt: event.tsIso,
-            updatedAt: event.tsIso,
-            dependsOn,
-            blocks,
-            owner,
-            source,
-            ...(assignee ? { assignee } : {}),
-            tags,
-            ...(externalSystem ? { externalSystem } : {}),
-            ...(externalId ? { externalId } : {}),
-            ...(externalKey ? { externalKey } : {}),
-            ...(externalUrl ? { externalUrl } : {}),
-            ...(externalProjectId ? { externalProjectId } : {}),
-            ...(externalProjectName ? { externalProjectName } : {}),
-            ...(externalTeamId ? { externalTeamId } : {}),
-            ...(opts.projectId ? { projectId: opts.projectId } : {}),
-            ...(opts.projectName ? { projectName: opts.projectName } : {}),
-          },
+        ticket: buildTicketSummary({
+          ticketId,
+          title: input.title,
+          ...(input.body ? { body: input.body } : {}),
+          status: "open",
+          createdAt: event.tsIso,
+          updatedAt: event.tsIso,
+          metadata,
+          projectId: opts.projectId,
+          projectName: opts.projectName,
         }),
       };
     },
@@ -795,102 +800,31 @@ export function createTicketsStore(opts: {
         return { ok: false, error: `Ticket not found: ${input.ticketId}` };
       }
 
-      const payload: Record<string, unknown> = {};
-      const events: TicketEvent[] = [];
-      if (input.title !== undefined) {
-        const title = input.title.trim();
-        if (!title) {
-          return { ok: false, error: "Title cannot be empty." };
-        }
-        payload.title = title;
+      const updatePayload = buildTicketUpdatePayload(input);
+      if (!updatePayload.ok) {
+        return updatePayload;
       }
-      if (input.body !== undefined) {
-        const content = input.body.trimEnd();
-        if (!content) {
-          return { ok: false, error: "Body cannot be empty." };
-        }
+
+      const events: TicketEvent[] = [];
+      if (updatePayload.documentContent) {
         events.push(
-          buildEvent({
+          buildDocumentRecordedEvent({
+            buildEvent,
             ticketId: input.ticketId,
-            type: "ticket.document_recorded",
-            payload: {
-              documentId: randomUUID(),
-              kind: "description",
-              content,
-            },
             actor: input.actor,
+            documentId: randomUUID(),
+            kind: "description",
+            content: updatePayload.documentContent,
           })
         );
       }
-      if (input.dependsOn !== undefined) {
-        payload.dependsOn = normalizeTicketRefs(input.dependsOn);
-      }
-      if (input.blocks !== undefined) {
-        payload.blocks = normalizeTicketRefs(input.blocks);
-      }
-      if (input.owner !== undefined) {
-        payload.owner = normalizeOwnerOrSource({
-          value: input.owner,
-          fallback: "hack",
-        });
-      }
-      if (input.source !== undefined) {
-        payload.source = normalizeOwnerOrSource({
-          value: input.source,
-          fallback: "hack",
-        });
-      }
-      if (input.assignee !== undefined) {
-        payload.assignee =
-          normalizeOptionalMetadataString({
-            value: input.assignee,
-          }) ?? null;
-      }
-      if (input.tags !== undefined) {
-        payload.tags = normalizeTags(input.tags);
-      }
-      if (input.externalSystem !== undefined) {
-        payload.externalSystem = normalizeOptionalMetadataString({
-          value: input.externalSystem,
-        });
-      }
-      if (input.externalId !== undefined) {
-        payload.externalId = normalizeOptionalMetadataString({
-          value: input.externalId,
-        });
-      }
-      if (input.externalKey !== undefined) {
-        payload.externalKey = normalizeOptionalMetadataString({
-          value: input.externalKey,
-        });
-      }
-      if (input.externalUrl !== undefined) {
-        payload.externalUrl = normalizeOptionalMetadataString({
-          value: input.externalUrl,
-        });
-      }
-      if (input.externalProjectId !== undefined) {
-        payload.externalProjectId = normalizeOptionalMetadataString({
-          value: input.externalProjectId,
-        });
-      }
-      if (input.externalProjectName !== undefined) {
-        payload.externalProjectName = normalizeOptionalMetadataString({
-          value: input.externalProjectName,
-        });
-      }
-      if (input.externalTeamId !== undefined) {
-        payload.externalTeamId = normalizeOptionalMetadataString({
-          value: input.externalTeamId,
-        });
-      }
 
-      if (Object.keys(payload).length > 0) {
+      if (Object.keys(updatePayload.payload).length > 0) {
         events.push(
           buildEvent({
             ticketId: input.ticketId,
             type: "ticket.updated",
-            payload,
+            payload: updatePayload.payload,
             actor: input.actor,
           })
         );
@@ -1117,41 +1051,14 @@ export function createTicketsStore(opts: {
         return { ok: false, error: `Ticket not found: ${input.ticketId}` };
       }
 
-      const provider = normalizeOptionalMetadataString({
-        value: input.provider,
-      });
-      if (!provider) {
-        return { ok: false, error: "Provider is required." };
+      const checkpoint = buildSyncCheckpointResult(input);
+      if (!checkpoint.ok) {
+        return checkpoint;
       }
-
-      const checkpointId = randomUUID();
-      const profileId = normalizeOptionalMetadataString({
-        value: input.profileId,
-      });
-      const direction = normalizeOptionalMetadataString({
-        value: input.direction,
-      });
-      const remoteCursor = normalizeOptionalMetadataString({
-        value: input.remoteCursor,
-      });
-      const remoteUpdatedAt = normalizeOptionalMetadataString({
-        value: input.remoteUpdatedAt,
-      });
-      const localUpdatedAt = normalizeOptionalMetadataString({
-        value: input.localUpdatedAt,
-      });
       const event = buildEvent({
         ticketId: input.ticketId,
         type: "ticket.sync_checkpoint_recorded",
-        payload: {
-          checkpointId,
-          provider,
-          ...(profileId ? { profileId } : {}),
-          ...(direction ? { direction } : {}),
-          ...(remoteCursor ? { remoteCursor } : {}),
-          ...(remoteUpdatedAt ? { remoteUpdatedAt } : {}),
-          ...(localUpdatedAt ? { localUpdatedAt } : {}),
-        },
+        payload: checkpoint.payload,
         ...(input.idempotencyKey
           ? { idempotencyKey: input.idempotencyKey }
           : {}),
@@ -1166,14 +1073,7 @@ export function createTicketsStore(opts: {
       return {
         ok: true,
         checkpoint: {
-          checkpointId,
-          ticketId: input.ticketId,
-          provider,
-          ...(profileId ? { profileId } : {}),
-          ...(direction ? { direction } : {}),
-          ...(remoteCursor ? { remoteCursor } : {}),
-          ...(remoteUpdatedAt ? { remoteUpdatedAt } : {}),
-          ...(localUpdatedAt ? { localUpdatedAt } : {}),
+          ...checkpoint.checkpoint,
           actor: event.actor,
           createdAt: event.tsIso,
         },
@@ -1186,42 +1086,14 @@ export function createTicketsStore(opts: {
         return { ok: false, error: `Ticket not found: ${input.ticketId}` };
       }
 
-      const provider = normalizeOptionalMetadataString({
-        value: input.provider,
-      });
-      if (!provider) {
-        return { ok: false, error: "Provider is required." };
-      }
-      const field = normalizeOptionalMetadataString({
-        value: input.field,
-      });
-      if (!field) {
-        return { ok: false, error: "Field is required." };
+      const conflict = buildSyncConflictResult(input);
+      if (!conflict.ok) {
+        return conflict;
       }
-
-      const conflictId = randomUUID();
-      const authority = normalizeOptionalMetadataString({
-        value: input.authority,
-      });
-      const summary = normalizeOptionalMetadataString({
-        value: input.summary,
-      });
       const event = buildEvent({
         ticketId: input.ticketId,
         type: "ticket.sync_conflict_recorded",
-        payload: {
-          conflictId,
-          provider,
-          field,
-          ...(authority ? { authority } : {}),
-          ...(summary ? { summary } : {}),
-          ...(input.localValue !== undefined
-            ? { localValue: input.localValue }
-            : {}),
-          ...(input.remoteValue !== undefined
-            ? { remoteValue: input.remoteValue }
-            : {}),
-        },
+        payload: conflict.payload,
         ...(input.idempotencyKey
           ? { idempotencyKey: input.idempotencyKey }
           : {}),
@@ -1236,19 +1108,7 @@ export function createTicketsStore(opts: {
       return {
         ok: true,
         conflict: {
-          conflictId,
-          ticketId: input.ticketId,
-          provider,
-          field,
-          status: "open",
-          ...(authority ? { authority } : {}),
-          ...(summary ? { summary } : {}),
-          ...(input.localValue !== undefined
-            ? { localValue: input.localValue }
-            : {}),
-          ...(input.remoteValue !== undefined
-            ? { remoteValue: input.remoteValue }
-            : {}),
+          ...conflict.conflict,
           createdAt: event.tsIso,
           updatedAt: event.tsIso,
         },
@@ -1583,55 +1443,67 @@ function applyTicketUpdatedEvent(input: {
     payload: input.event.payload,
     key: "externalTeamId",
   });
+  const next = {
+    ...current,
+    updatedAt: input.event.tsIso,
+  };
+
+  applyUpdateValue(title, (value) => {
+    next.title = value;
+  });
+  applyUpdateValue(body, (value) => {
+    next.body = value;
+  });
+  applyUpdateValue(dependsOn, (value) => {
+    next.dependsOn = value;
+  });
+  applyUpdateValue(blocks, (value) => {
+    next.blocks = value;
+  });
+  applyOptionalMetadataUpdate(owner, (value) => {
+    next.owner = normalizeOwnerOrSource({
+      value,
+      fallback: current.owner,
+    });
+  });
+  applyOptionalMetadataUpdate(source, (value) => {
+    next.source = normalizeOwnerOrSource({
+      value,
+      fallback: current.source,
+    });
+  });
+  applyOptionalMetadataUpdate(assignee, (value) => {
+    next.assignee = value;
+  });
+  applyUpdateValue(tags, (value) => {
+    next.tags = value;
+  });
+  applyOptionalMetadataUpdate(externalSystem, (value) => {
+    next.externalSystem = value;
+  });
+  applyOptionalMetadataUpdate(externalId, (value) => {
+    next.externalId = value;
+  });
+  applyOptionalMetadataUpdate(externalKey, (value) => {
+    next.externalKey = value;
+  });
+  applyOptionalMetadataUpdate(externalUrl, (value) => {
+    next.externalUrl = value;
+  });
+  applyOptionalMetadataUpdate(externalProjectId, (value) => {
+    next.externalProjectId = value;
+  });
+  applyOptionalMetadataUpdate(externalProjectName, (value) => {
+    next.externalProjectName = value;
+  });
+  applyOptionalMetadataUpdate(externalTeamId, (value) => {
+    next.externalTeamId = value;
+  });
 
   input.tickets.set(
     input.event.ticketId,
     normalizeTicketSummaryCompatibility({
-      ticket: {
-        ...current,
-        ...(title ? { title } : {}),
-        ...(body !== undefined ? { body } : {}),
-        ...(dependsOn !== null ? { dependsOn } : {}),
-        ...(blocks !== null ? { blocks } : {}),
-        ...(owner !== null
-          ? {
-              owner: normalizeOwnerOrSource({
-                value: owner,
-                fallback: current.owner,
-              }),
-            }
-          : {}),
-        ...(source !== null
-          ? {
-              source: normalizeOwnerOrSource({
-                value: source,
-                fallback: current.source,
-              }),
-            }
-          : {}),
-        ...(assignee !== null ? { assignee: assignee || undefined } : {}),
-        ...(tags !== null ? { tags } : {}),
-        ...(externalSystem !== null
-          ? { externalSystem: externalSystem || undefined }
-          : {}),
-        ...(externalId !== null ? { externalId: externalId || undefined } : {}),
-        ...(externalKey !== null
-          ? { externalKey: externalKey || undefined }
-          : {}),
-        ...(externalUrl !== null
-          ? { externalUrl: externalUrl || undefined }
-          : {}),
-        ...(externalProjectId !== null
-          ? { externalProjectId: externalProjectId || undefined }
-          : {}),
-        ...(externalProjectName !== null
-          ? { externalProjectName: externalProjectName || undefined }
-          : {}),
-        ...(externalTeamId !== null
-          ? { externalTeamId: externalTeamId || undefined }
-          : {}),
-        updatedAt: input.event.tsIso,
-      },
+      ticket: next,
     })
   );
 
@@ -2188,39 +2060,506 @@ function safeJsonParse(text: string): unknown {
   }
 }
 
+function normalizeTicketMetadata(input: {
+  readonly dependsOn?: readonly string[];
+  readonly blocks?: readonly string[];
+  readonly owner?: string;
+  readonly source?: string;
+  readonly assignee?: string;
+  readonly tags?: readonly string[];
+  readonly externalSystem?: string;
+  readonly externalId?: string;
+  readonly externalKey?: string;
+  readonly externalUrl?: string;
+  readonly externalProjectId?: string;
+  readonly externalProjectName?: string;
+  readonly externalTeamId?: string;
+  readonly ownerFallback: string;
+  readonly sourceFallback: string;
+}): NormalizedTicketMetadata {
+  const assignee = normalizeOptionalMetadataString({
+    value: input.assignee,
+  });
+  return {
+    dependsOn: normalizeTicketRefs(input.dependsOn ?? []),
+    blocks: normalizeTicketRefs(input.blocks ?? []),
+    owner: normalizeOwnerOrSource({
+      value: input.owner,
+      fallback: input.ownerFallback,
+    }),
+    source: normalizeOwnerOrSource({
+      value: input.source,
+      fallback: input.sourceFallback,
+    }),
+    ...(assignee ? { assignee } : {}),
+    tags: normalizeTags(input.tags ?? []),
+    ...readOptionalMetadataFields(input),
+  };
+}
+
+function readOptionalMetadataFields(input: {
+  readonly externalSystem?: string;
+  readonly externalId?: string;
+  readonly externalKey?: string;
+  readonly externalUrl?: string;
+  readonly externalProjectId?: string;
+  readonly externalProjectName?: string;
+  readonly externalTeamId?: string;
+}): Partial<NormalizedTicketMetadata> {
+  const externalSystem = normalizeOptionalMetadataString({
+    value: input.externalSystem,
+  });
+  const externalId = normalizeOptionalMetadataString({
+    value: input.externalId,
+  });
+  const externalKey = normalizeOptionalMetadataString({
+    value: input.externalKey,
+  });
+  const externalUrl = normalizeOptionalMetadataString({
+    value: input.externalUrl,
+  });
+  const externalProjectId = normalizeOptionalMetadataString({
+    value: input.externalProjectId,
+  });
+  const externalProjectName = normalizeOptionalMetadataString({
+    value: input.externalProjectName,
+  });
+  const externalTeamId = normalizeOptionalMetadataString({
+    value: input.externalTeamId,
+  });
+
+  return {
+    ...(externalSystem ? { externalSystem } : {}),
+    ...(externalId ? { externalId } : {}),
+    ...(externalKey ? { externalKey } : {}),
+    ...(externalUrl ? { externalUrl } : {}),
+    ...(externalProjectId ? { externalProjectId } : {}),
+    ...(externalProjectName ? { externalProjectName } : {}),
+    ...(externalTeamId ? { externalTeamId } : {}),
+  };
+}
+
+function buildTicketSummary(input: {
+  readonly ticketId: string;
+  readonly title: string;
+  readonly body?: string;
+  readonly status: TicketStatus;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly metadata: NormalizedTicketMetadata;
+  readonly projectId?: string;
+  readonly projectName?: string;
+}): TicketSummary {
+  return normalizeTicketSummaryCompatibility({
+    ticket: {
+      ticketId: input.ticketId,
+      title: input.title,
+      ...(input.body ? { body: input.body } : {}),
+      status: input.status,
+      createdAt: input.createdAt,
+      updatedAt: input.updatedAt,
+      dependsOn: input.metadata.dependsOn,
+      blocks: input.metadata.blocks,
+      owner: input.metadata.owner,
+      source: input.metadata.source,
+      ...(input.metadata.assignee ? { assignee: input.metadata.assignee } : {}),
+      tags: input.metadata.tags,
+      ...(input.metadata.externalSystem
+        ? { externalSystem: input.metadata.externalSystem }
+        : {}),
+      ...(input.metadata.externalId
+        ? { externalId: input.metadata.externalId }
+        : {}),
+      ...(input.metadata.externalKey
+        ? { externalKey: input.metadata.externalKey }
+        : {}),
+      ...(input.metadata.externalUrl
+        ? { externalUrl: input.metadata.externalUrl }
+        : {}),
+      ...(input.metadata.externalProjectId
+        ? { externalProjectId: input.metadata.externalProjectId }
+        : {}),
+      ...(input.metadata.externalProjectName
+        ? { externalProjectName: input.metadata.externalProjectName }
+        : {}),
+      ...(input.metadata.externalTeamId
+        ? { externalTeamId: input.metadata.externalTeamId }
+        : {}),
+      ...(input.projectId ? { projectId: input.projectId } : {}),
+      ...(input.projectName ? { projectName: input.projectName } : {}),
+    },
+  });
+}
+
+function appendTicketMetadataPayload(input: {
+  readonly payload: Record<string, unknown>;
+  readonly metadata: NormalizedTicketMetadata;
+}): void {
+  if (input.metadata.dependsOn.length > 0) {
+    input.payload.dependsOn = input.metadata.dependsOn;
+  }
+  if (input.metadata.blocks.length > 0) {
+    input.payload.blocks = input.metadata.blocks;
+  }
+  input.payload.owner = input.metadata.owner;
+  input.payload.source = input.metadata.source;
+  if (input.metadata.assignee) {
+    input.payload.assignee = input.metadata.assignee;
+  }
+  if (input.metadata.tags.length > 0) {
+    input.payload.tags = input.metadata.tags;
+  }
+  appendOptionalStringFields({
+    target: input.payload,
+    entries: [
+      ["externalSystem", input.metadata.externalSystem],
+      ["externalId", input.metadata.externalId],
+      ["externalKey", input.metadata.externalKey],
+      ["externalUrl", input.metadata.externalUrl],
+      ["externalProjectId", input.metadata.externalProjectId],
+      ["externalProjectName", input.metadata.externalProjectName],
+      ["externalTeamId", input.metadata.externalTeamId],
+    ],
+  });
+}
+
+function appendOptionalStringFields(input: {
+  readonly target: Record<string, unknown>;
+  readonly entries: readonly (readonly [string, string | undefined])[];
+}): void {
+  for (const [key, value] of input.entries) {
+    if (value) {
+      input.target[key] = value;
+    }
+  }
+}
+
+function buildTicketUpdatePayload(input: {
+  readonly title?: string;
+  readonly body?: string;
+  readonly dependsOn?: readonly string[];
+  readonly blocks?: readonly string[];
+  readonly owner?: string;
+  readonly source?: string;
+  readonly assignee?: string;
+  readonly tags?: readonly string[];
+  readonly externalSystem?: string;
+  readonly externalId?: string;
+  readonly externalKey?: string;
+  readonly externalUrl?: string;
+  readonly externalProjectId?: string;
+  readonly externalProjectName?: string;
+  readonly externalTeamId?: string;
+}): TicketUpdatePayloadResult {
+  const payload: Record<string, unknown> = {};
+  let documentContent: string | undefined;
+
+  if (input.title !== undefined) {
+    const title = input.title.trim();
+    if (!title) {
+      return { ok: false, error: "Title cannot be empty." };
+    }
+    payload.title = title;
+  }
+
+  if (input.body !== undefined) {
+    documentContent = input.body.trimEnd();
+    if (!documentContent) {
+      return { ok: false, error: "Body cannot be empty." };
+    }
+  }
+
+  appendUpdateField(payload, "dependsOn", () =>
+    input.dependsOn === undefined
+      ? undefined
+      : normalizeTicketRefs(input.dependsOn)
+  );
+  appendUpdateField(payload, "blocks", () =>
+    input.blocks === undefined ? undefined : normalizeTicketRefs(input.blocks)
+  );
+  appendUpdateField(payload, "owner", () =>
+    input.owner === undefined
+      ? undefined
+      : normalizeOwnerOrSource({
+          value: input.owner,
+          fallback: "hack",
+        })
+  );
+  appendUpdateField(payload, "source", () =>
+    input.source === undefined
+      ? undefined
+      : normalizeOwnerOrSource({
+          value: input.source,
+          fallback: "hack",
+        })
+  );
+  appendUpdateField(payload, "assignee", () =>
+    input.assignee === undefined
+      ? undefined
+      : (normalizeOptionalMetadataString({
+          value: input.assignee,
+        }) ?? null)
+  );
+  appendUpdateField(payload, "tags", () =>
+    input.tags === undefined ? undefined : normalizeTags(input.tags)
+  );
+
+  for (const key of [
+    "externalSystem",
+    "externalId",
+    "externalKey",
+    "externalUrl",
+    "externalProjectId",
+    "externalProjectName",
+    "externalTeamId",
+  ] as const) {
+    appendUpdateField(payload, key, () => {
+      const value = input[key];
+      if (value === undefined) {
+        return undefined;
+      }
+      return normalizeOptionalMetadataString({
+        value,
+      });
+    });
+  }
+
+  return { ok: true, payload, ...(documentContent ? { documentContent } : {}) };
+}
+
+function appendUpdateField(
+  payload: Record<string, unknown>,
+  key: string,
+  resolveValue: () => unknown
+): void {
+  const value = resolveValue();
+  if (value !== undefined) {
+    payload[key] = value;
+  }
+}
+
+function readStringField(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function readOptionalStringField(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function applyUpdateValue<T>(
+  value: T | null | undefined,
+  apply: (value: T) => void
+): void {
+  if (value !== null && value !== undefined) {
+    apply(value);
+  }
+}
+
+function applyOptionalMetadataUpdate(
+  value: string | null,
+  apply: (value: string | undefined) => void
+): void {
+  if (value !== null) {
+    apply(value || undefined);
+  }
+}
+
+function buildDocumentRecordedEvent(input: {
+  readonly buildEvent: (input: {
+    readonly ticketId: string;
+    readonly type: string;
+    readonly payload: Record<string, unknown>;
+    readonly actor?: string;
+    readonly occurredAt?: string;
+    readonly sourceSystem?: string;
+    readonly sourceOperation?: string;
+    readonly idempotencyKey?: string;
+    readonly causationId?: string;
+    readonly correlationId?: string;
+  }) => TicketEvent;
+  readonly ticketId: string;
+  readonly actor?: string;
+  readonly documentId: string;
+  readonly kind: TicketDocumentKind;
+  readonly role?: TicketDocumentRole;
+  readonly content: string;
+}): TicketEvent {
+  return input.buildEvent({
+    ticketId: input.ticketId,
+    type: "ticket.document_recorded",
+    payload: {
+      documentId: input.documentId,
+      kind: input.kind,
+      ...(input.role ? { role: input.role } : {}),
+      content: input.content,
+    },
+    actor: input.actor,
+  });
+}
+
+function buildSyncCheckpointResult(input: {
+  readonly ticketId: string;
+  readonly provider: string;
+  readonly profileId?: string;
+  readonly direction?: string;
+  readonly remoteCursor?: string;
+  readonly remoteUpdatedAt?: string;
+  readonly localUpdatedAt?: string;
+}): SyncCheckpointBuildResult {
+  const provider = normalizeOptionalMetadataString({
+    value: input.provider,
+  });
+  if (!provider) {
+    return { ok: false, error: "Provider is required." };
+  }
+
+  const checkpointId = randomUUID();
+  const profileId = normalizeOptionalMetadataString({
+    value: input.profileId,
+  });
+  const direction = normalizeOptionalMetadataString({
+    value: input.direction,
+  });
+  const remoteCursor = normalizeOptionalMetadataString({
+    value: input.remoteCursor,
+  });
+  const remoteUpdatedAt = normalizeOptionalMetadataString({
+    value: input.remoteUpdatedAt,
+  });
+  const localUpdatedAt = normalizeOptionalMetadataString({
+    value: input.localUpdatedAt,
+  });
+  const payload: Record<string, unknown> = {
+    checkpointId,
+    provider,
+  };
+  appendOptionalStringFields({
+    target: payload,
+    entries: [
+      ["profileId", profileId],
+      ["direction", direction],
+      ["remoteCursor", remoteCursor],
+      ["remoteUpdatedAt", remoteUpdatedAt],
+      ["localUpdatedAt", localUpdatedAt],
+    ],
+  });
+
+  return {
+    ok: true,
+    checkpointId,
+    provider,
+    payload,
+    checkpoint: {
+      checkpointId,
+      ticketId: input.ticketId,
+      provider,
+      ...(profileId ? { profileId } : {}),
+      ...(direction ? { direction } : {}),
+      ...(remoteCursor ? { remoteCursor } : {}),
+      ...(remoteUpdatedAt ? { remoteUpdatedAt } : {}),
+      ...(localUpdatedAt ? { localUpdatedAt } : {}),
+      actor: "",
+      createdAt: "",
+    },
+  };
+}
+
+function buildSyncConflictResult(input: {
+  readonly ticketId: string;
+  readonly provider: string;
+  readonly field: string;
+  readonly authority?: string;
+  readonly summary?: string;
+  readonly localValue?: TicketMetadataValue;
+  readonly remoteValue?: TicketMetadataValue;
+}): SyncConflictBuildResult {
+  const provider = normalizeOptionalMetadataString({
+    value: input.provider,
+  });
+  if (!provider) {
+    return { ok: false, error: "Provider is required." };
+  }
+  const field = normalizeOptionalMetadataString({
+    value: input.field,
+  });
+  if (!field) {
+    return { ok: false, error: "Field is required." };
+  }
+
+  const conflictId = randomUUID();
+  const authority = normalizeOptionalMetadataString({
+    value: input.authority,
+  });
+  const summary = normalizeOptionalMetadataString({
+    value: input.summary,
+  });
+  const payload: Record<string, unknown> = {
+    conflictId,
+    provider,
+    field,
+  };
+  appendOptionalStringFields({
+    target: payload,
+    entries: [
+      ["authority", authority],
+      ["summary", summary],
+    ],
+  });
+  if (input.localValue !== undefined) {
+    payload.localValue = input.localValue;
+  }
+  if (input.remoteValue !== undefined) {
+    payload.remoteValue = input.remoteValue;
+  }
+
+  return {
+    ok: true,
+    conflictId,
+    provider,
+    field,
+    payload,
+    conflict: {
+      conflictId,
+      ticketId: input.ticketId,
+      provider,
+      field,
+      status: "open",
+      ...(authority ? { authority } : {}),
+      ...(summary ? { summary } : {}),
+      ...(input.localValue !== undefined
+        ? { localValue: input.localValue }
+        : {}),
+      ...(input.remoteValue !== undefined
+        ? { remoteValue: input.remoteValue }
+        : {}),
+    },
+  };
+}
+
 function parseEvent(value: unknown): TicketEvent | null {
   if (!isRecord(value)) {
     return null;
   }
-  const eventId = typeof value.eventId === "string" ? value.eventId : "";
+  const eventId = readStringField(value.eventId);
   const schemaVersion =
     typeof value.schemaVersion === "number" ? value.schemaVersion : 0;
   const ts = typeof value.ts === "number" ? value.ts : Number.NaN;
   const tsIso = new Date(ts * 1000).toISOString();
-  const actor = typeof value.actor === "string" ? value.actor : "";
-  const eventTypeCandidate =
-    typeof value.eventType === "string" ? value.eventType : undefined;
-  const typeCandidate = typeof value.type === "string" ? value.type : undefined;
+  const actor = readStringField(value.actor);
+  const eventTypeCandidate = readOptionalStringField(value.eventType);
+  const typeCandidate = readOptionalStringField(value.type);
   const eventType = eventTypeCandidate ?? typeCandidate ?? "";
-  const occurredAt =
-    typeof value.occurredAt === "string" ? value.occurredAt : tsIso;
-  const recordedAt =
-    typeof value.recordedAt === "string" ? value.recordedAt : tsIso;
-  const orderKey =
-    typeof value.orderKey === "string" ? value.orderKey : undefined;
-  const sourceSystem =
-    typeof value.sourceSystem === "string" ? value.sourceSystem : "hack";
+  const occurredAt = readOptionalStringField(value.occurredAt) ?? tsIso;
+  const recordedAt = readOptionalStringField(value.recordedAt) ?? tsIso;
+  const orderKey = readOptionalStringField(value.orderKey);
+  const sourceSystem = readOptionalStringField(value.sourceSystem) ?? "hack";
   const sourceOperation =
-    typeof value.sourceOperation === "string"
-      ? value.sourceOperation
-      : eventType;
+    readOptionalStringField(value.sourceOperation) ?? eventType;
   const idempotencyKey =
-    typeof value.idempotencyKey === "string" ? value.idempotencyKey : eventId;
-  const causationId =
-    typeof value.causationId === "string" ? value.causationId : undefined;
-  const correlationId =
-    typeof value.correlationId === "string" ? value.correlationId : undefined;
-  const ticketId = typeof value.ticketId === "string" ? value.ticketId : "";
+    readOptionalStringField(value.idempotencyKey) ?? eventId;
+  const causationId = readOptionalStringField(value.causationId);
+  const correlationId = readOptionalStringField(value.correlationId);
+  const ticketId = readStringField(value.ticketId);
   const type = typeCandidate ?? eventType;
   const payload = isRecord(value.payload)
     ? (value.payload as Record<string, unknown>)
@@ -2232,10 +2571,8 @@ function parseEvent(value: unknown): TicketEvent | null {
     return null;
   }
 
-  const projectId =
-    typeof value.projectId === "string" ? value.projectId : undefined;
-  const projectName =
-    typeof value.projectName === "string" ? value.projectName : undefined;
+  const projectId = readOptionalStringField(value.projectId);
+  const projectName = readOptionalStringField(value.projectName);
 
   return {
     eventId,
diff --git a/src/control-plane/extensions/tickets/tickets-git-channel.ts b/src/control-plane/extensions/tickets/tickets-git-channel.ts
index cff02ff1b..3f9d00fc1 100644
--- a/src/control-plane/extensions/tickets/tickets-git-channel.ts
+++ b/src/control-plane/extensions/tickets/tickets-git-channel.ts
@@ -59,6 +59,21 @@ export type TicketsGitRepairResult =
     }
   | { readonly ok: false; readonly error: string };
 
+type ParsedJournalEvent = {
+  readonly eventId: string;
+  readonly idempotencyKey: string;
+  readonly ts: number;
+  readonly value: Record<string, unknown>;
+};
+
+type PushAttemptResult =
+  | { readonly ok: true; readonly didPush: boolean }
+  | {
+      readonly ok: false;
+      readonly error: string;
+      readonly hiddenRefRejected?: boolean;
+    };
+
 export function createGitTicketsChannel(opts: {
   readonly projectRoot: string;
   readonly config: TicketsGitConfig;
@@ -341,6 +356,72 @@ export function createGitTicketsChannel(opts: {
     return await fetchRemoteRefToTracking(ref, trackingRef);
   };
 
+  const buildHiddenRefPushError = (message: string): PushAttemptResult => {
+    return {
+      ok: false,
+      error: `git push failed: ${message}\nRemote rejected hidden refs. Set controlPlane.tickets.git.refMode to "heads" to use a branch ref.`,
+      hiddenRefRejected: true,
+    };
+  };
+
+  const pushCurrentBranch = async (input: {
+    readonly pushRef: string;
+  }): Promise<PushAttemptResult> => {
+    const push = await runGitDir({
+      args: ["push", "origin", `${localBranchRef}:${input.pushRef}`],
+    });
+    if (push.ok) {
+      return { ok: true, didPush: true };
+    }
+
+    const message = `${push.stderr}\n${push.stdout}`.trim();
+    if (refMode === "hidden" && isHiddenRefRejected(message)) {
+      return buildHiddenRefPushError(message);
+    }
+    return { ok: false, error: `git push failed: ${message}` };
+  };
+
+  const rewritePendingEventsAfterCheckout = async (input: {
+    readonly pendingEvents?: readonly Record<string, unknown>[];
+  }): Promise<
+    { readonly ok: true } | { readonly ok: false; readonly error: string }
+  > => {
+    if (!(input.pendingEvents && input.pendingEvents.length > 0)) {
+      return { ok: true };
+    }
+    return await writeEvents({ events: input.pendingEvents });
+  };
+
+  const pruneLegacyRemoteRefIfRequested = async (input: {
+    readonly pruneLegacyRef: boolean;
+    readonly remoteUrl: string | null;
+  }): Promise<{
+    readonly didPruneLegacy: boolean;
+    readonly pruneError?: string;
+  }> => {
+    if (!(input.pruneLegacyRef && legacyRemoteRef && input.remoteUrl)) {
+      return { didPruneLegacy: false };
+    }
+
+    const prunedLegacy = await runGitDir({
+      args: ["push", "origin", `:${legacyRemoteRef}`],
+    });
+    if (!prunedLegacy.ok) {
+      return {
+        didPruneLegacy: false,
+        pruneError: `${prunedLegacy.stderr}\n${prunedLegacy.stdout}`.trim(),
+      };
+    }
+
+    if (legacyTrackingRef) {
+      await runGitDir({
+        args: ["update-ref", "-d", legacyTrackingRef],
+      });
+    }
+
+    return { didPruneLegacy: true };
+  };
+
   const checkoutHead = async (input: {
     readonly remoteUrl: string | null;
   }): Promise<
@@ -630,41 +711,10 @@ export function createGitTicketsChannel(opts: {
       const existing = await Bun.file(path)
         .text()
         .catch(() => "");
-      const existingIds = new Set<string>();
-      const existingIdempotencyKeys = new Set<string>();
-      for (const line of existing.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-          continue;
-        }
-        const parsed = safeJsonParse(trimmed);
-        if (isRecord(parsed) && typeof parsed.eventId === "string") {
-          existingIds.add(parsed.eventId);
-          const idempotencyKey =
-            typeof parsed.idempotencyKey === "string"
-              ? parsed.idempotencyKey
-              : parsed.eventId;
-          existingIdempotencyKeys.add(idempotencyKey);
-        }
-      }
-
-      const lines: string[] = [];
-      const pendingIdempotencyKeys = new Set<string>();
-      for (const ev of events) {
-        const id = typeof ev.eventId === "string" ? ev.eventId : "";
-        const idempotencyKey =
-          typeof ev.idempotencyKey === "string" ? ev.idempotencyKey : id;
-        if (
-          !id ||
-          existingIds.has(id) ||
-          existingIdempotencyKeys.has(idempotencyKey) ||
-          pendingIdempotencyKeys.has(idempotencyKey)
-        ) {
-          continue;
-        }
-        pendingIdempotencyKeys.add(idempotencyKey);
-        lines.push(stableStringify(ev));
-      }
+      const lines = collectPendingSerializedEvents({
+        existingText: existing,
+        incomingEvents: events,
+      });
 
       if (lines.length > 0) {
         const prefix =
@@ -697,48 +747,11 @@ export function createGitTicketsChannel(opts: {
       const text = await Bun.file(path)
         .text()
         .catch(() => "");
-      const parsed: Record<string, unknown>[] = [];
-      const seen = new Set<string>();
-      const seenIdempotencyKeys = new Set<string>();
-
-      for (const line of text.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-          continue;
-        }
-        const value = safeJsonParse(trimmed);
-        if (!isRecord(value)) {
-          continue;
-        }
-        const eventId = typeof value.eventId === "string" ? value.eventId : "";
-        const idempotencyKey =
-          typeof value.idempotencyKey === "string"
-            ? value.idempotencyKey
-            : eventId;
-        const ts = typeof value.ts === "number" ? value.ts : Number.NaN;
-        if (!(eventId && Number.isFinite(ts))) {
-          continue;
-        }
-        if (seen.has(eventId) || seenIdempotencyKeys.has(idempotencyKey)) {
-          continue;
-        }
-        seen.add(eventId);
-        seenIdempotencyKeys.add(idempotencyKey);
-        parsed.push(value);
-      }
-
-      parsed.sort((a, b) => {
-        const aTs = typeof a.ts === "number" ? (a.ts as number) : 0;
-        const bTs = typeof b.ts === "number" ? (b.ts as number) : 0;
-        if (aTs !== bTs) {
-          return aTs - bTs;
-        }
-        const aId = typeof a.eventId === "string" ? (a.eventId as string) : "";
-        const bId = typeof b.eventId === "string" ? (b.eventId as string) : "";
-        return aId.localeCompare(bId);
-      });
-
-      const next = parsed.map((ev) => stableStringify(ev)).join("\n");
+      const next = collectUniqueJournalEvents({
+        texts: [text],
+      })
+        .map((event) => stableStringify(event.value))
+        .join("\n");
       const normalized = next.length > 0 ? `${next}\n` : "";
       if (normalized !== text) {
         await Bun.write(path, normalized);
@@ -786,23 +799,16 @@ export function createGitTicketsChannel(opts: {
       return { ok: true, didPush: false };
     }
 
-    const push = await runGitDir({
-      args: ["push", "origin", `${localBranchRef}:${input.pushRef}`],
-    });
+    const push = await pushCurrentBranch({ pushRef: input.pushRef });
     if (push.ok) {
-      return { ok: true, didPush: true };
+      return push;
     }
-
-    const pushMessage = `${push.stderr}\n${push.stdout}`.trim();
-    if (refMode === "hidden" && isHiddenRefRejected(pushMessage)) {
-      return {
-        ok: false,
-        error: `git push failed: ${pushMessage}\nRemote rejected hidden refs. Set controlPlane.tickets.git.refMode to "heads" to use a branch ref.`,
-      };
+    if (push.hiddenRefRejected) {
+      return push;
     }
 
     opts.logger.warn({
-      message: `git push failed, retrying after fetch: ${pushMessage}`,
+      message: `git push failed, retrying after fetch: ${push.error.replace("git push failed: ", "")}`,
     });
 
     const checkedOut = await checkoutHead({ remoteUrl: input.remoteUrl });
@@ -810,11 +816,11 @@ export function createGitTicketsChannel(opts: {
       return checkedOut;
     }
 
-    if (input.pendingEvents && input.pendingEvents.length > 0) {
-      const wrote = await writeEvents({ events: input.pendingEvents });
-      if (!wrote.ok) {
-        return wrote;
-      }
+    const rewrote = await rewritePendingEventsAfterCheckout({
+      pendingEvents: input.pendingEvents,
+    });
+    if (!rewrote.ok) {
+      return rewrote;
     }
 
     const committed = await commitAll("tickets: retry");
@@ -822,21 +828,8 @@ export function createGitTicketsChannel(opts: {
       return committed;
     }
 
-    const retry = await runGitDir({
-      args: ["push", "origin", `${localBranchRef}:${checkedOut.pushRef}`],
-    });
-    if (!retry.ok) {
-      const retryMessage = `${retry.stderr}\n${retry.stdout}`.trim();
-      if (refMode === "hidden" && isHiddenRefRejected(retryMessage)) {
-        return {
-          ok: false,
-          error: `git push failed: ${retryMessage}\nRemote rejected hidden refs. Set controlPlane.tickets.git.refMode to "heads" to use a branch ref.`,
-        };
-      }
-      return { ok: false, error: `git push failed: ${retryMessage}` };
-    }
-
-    return { ok: true, didPush: true };
+    const retry = await pushCurrentBranch({ pushRef: checkedOut.pushRef });
+    return retry;
   };
 
   const listTrackedPaths = async (): Promise<
@@ -1016,31 +1009,19 @@ export function createGitTicketsChannel(opts: {
       return pushed;
     }
 
-    let didPruneLegacy = false;
-    let pruneError: string | undefined;
-
-    if (input.pruneLegacyRef && legacyRemoteRef && checkedOut.remoteUrl) {
-      const prunedLegacy = await runGitDir({
-        args: ["push", "origin", `:${legacyRemoteRef}`],
-      });
-      if (prunedLegacy.ok) {
-        didPruneLegacy = true;
-        if (legacyTrackingRef) {
-          await runGitDir({
-            args: ["update-ref", "-d", legacyTrackingRef],
-          });
-        }
-      } else {
-        pruneError = `${prunedLegacy.stderr}\n${prunedLegacy.stdout}`.trim();
-      }
-    }
+    const prunedLegacy = await pruneLegacyRemoteRefIfRequested({
+      pruneLegacyRef: input.pruneLegacyRef,
+      remoteUrl: checkedOut.remoteUrl,
+    });
 
     return {
       ok: true,
       didCommit: committed.didCommit,
       didPush: pushed.didPush,
-      didPruneLegacy,
-      ...(pruneError ? { pruneError } : {}),
+      didPruneLegacy: prunedLegacy.didPruneLegacy,
+      ...(prunedLegacy.pruneError
+        ? { pruneError: prunedLegacy.pruneError }
+        : {}),
     };
   };
 
@@ -1197,51 +1178,111 @@ function mergeTicketEventLogs(input: {
   readonly existing: string;
   readonly incoming: string;
 }): string {
-  const parsed: Record<string, unknown>[] = [];
+  const next = collectUniqueJournalEvents({
+    texts: [input.existing, input.incoming],
+  })
+    .map((event) => stableStringify(event.value))
+    .join("\n");
+  return next ? `${next}\n` : "";
+}
+
+function collectPendingSerializedEvents(input: {
+  readonly existingText: string;
+  readonly incomingEvents: readonly Record<string, unknown>[];
+}): string[] {
+  const existingEvents = collectUniqueJournalEvents({
+    texts: [input.existingText],
+  });
+  const existingIds = new Set(existingEvents.map((event) => event.eventId));
+  const existingIdempotencyKeys = new Set(
+    existingEvents.map((event) => event.idempotencyKey)
+  );
+  const pendingIdempotencyKeys = new Set<string>();
+  const lines: string[] = [];
+
+  for (const event of input.incomingEvents) {
+    const parsed = parseJournalEvent(event);
+    if (!parsed) {
+      continue;
+    }
+    if (
+      existingIds.has(parsed.eventId) ||
+      existingIdempotencyKeys.has(parsed.idempotencyKey) ||
+      pendingIdempotencyKeys.has(parsed.idempotencyKey)
+    ) {
+      continue;
+    }
+    pendingIdempotencyKeys.add(parsed.idempotencyKey);
+    lines.push(stableStringify(event));
+  }
+
+  return lines;
+}
+
+function collectUniqueJournalEvents(input: {
+  readonly texts: readonly string[];
+}): ParsedJournalEvent[] {
+  const parsed: ParsedJournalEvent[] = [];
   const seen = new Set<string>();
   const seenIdempotencyKeys = new Set<string>();
 
-  for (const text of [input.existing, input.incoming]) {
+  for (const text of input.texts) {
     for (const line of text.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed) {
+      const event = parseJournalEventLine(line);
+      if (!event) {
         continue;
       }
-      const value = safeJsonParse(trimmed);
-      if (!isRecord(value)) {
-        continue;
-      }
-      const eventId = typeof value.eventId === "string" ? value.eventId : "";
-      const idempotencyKey =
-        typeof value.idempotencyKey === "string"
-          ? value.idempotencyKey
-          : eventId;
-      const ts = typeof value.ts === "number" ? value.ts : Number.NaN;
-      if (!(eventId && Number.isFinite(ts))) {
-        continue;
-      }
-      if (seen.has(eventId) || seenIdempotencyKeys.has(idempotencyKey)) {
+      if (
+        seen.has(event.eventId) ||
+        seenIdempotencyKeys.has(event.idempotencyKey)
+      ) {
         continue;
       }
-      seen.add(eventId);
-      seenIdempotencyKeys.add(idempotencyKey);
-      parsed.push(value);
+      seen.add(event.eventId);
+      seenIdempotencyKeys.add(event.idempotencyKey);
+      parsed.push(event);
     }
   }
 
-  parsed.sort((a, b) => {
-    const aTs = typeof a.ts === "number" ? (a.ts as number) : 0;
-    const bTs = typeof b.ts === "number" ? (b.ts as number) : 0;
-    if (aTs !== bTs) {
-      return aTs - bTs;
-    }
-    const aId = typeof a.eventId === "string" ? (a.eventId as string) : "";
-    const bId = typeof b.eventId === "string" ? (b.eventId as string) : "";
-    return aId.localeCompare(bId);
-  });
+  parsed.sort(compareParsedJournalEvents);
+  return parsed;
+}
 
-  const next = parsed.map((event) => stableStringify(event)).join("\n");
-  return next ? `${next}\n` : "";
+function parseJournalEventLine(line: string): ParsedJournalEvent | null {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return null;
+  }
+  return parseJournalEvent(safeJsonParse(trimmed));
+}
+
+function parseJournalEvent(value: unknown): ParsedJournalEvent | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const eventId = typeof value.eventId === "string" ? value.eventId : "";
+  const idempotencyKey =
+    typeof value.idempotencyKey === "string" ? value.idempotencyKey : eventId;
+  const ts = typeof value.ts === "number" ? value.ts : Number.NaN;
+  if (!(eventId && Number.isFinite(ts))) {
+    return null;
+  }
+  return {
+    eventId,
+    idempotencyKey,
+    ts,
+    value,
+  };
+}
+
+function compareParsedJournalEvents(
+  left: ParsedJournalEvent,
+  right: ParsedJournalEvent
+): number {
+  if (left.ts !== right.ts) {
+    return left.ts - right.ts;
+  }
+  return left.eventId.localeCompare(right.eventId);
 }
 
 function isRetryableTrackingRefLockFailure(input: {
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index 60cd4fab1..a2155b3b5 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -1098,6 +1098,164 @@ test("syncIssueFromLinearToTicket preserves hack authority, appends comments, an
   expect(updatedTickets[0]?.assignee).toBe("Remote Owner");
 });
 
+test("syncIssueFromLinearToTicket records review-required conflicts for dual-homed authority", async () => {
+  const recordedConflicts: Array<{
+    readonly field: string;
+    readonly authority?: string;
+  }> = [];
+  const updatedTickets: Record<string, unknown>[] = [];
+
+  const runtime = {
+    profileId: "default",
+    apiUrl: "https://api.linear.app/graphql",
+    projectBinding: {
+      additionalProjects: [],
+    },
+    tickets: {
+      listTickets: async () => [
+        {
+          ticketId: "T-00004",
+          title: "Local title",
+          body: "Local body",
+          status: "open" as const,
+          createdAt: "2026-03-05T10:00:00.000Z",
+          updatedAt: "2026-03-05T10:00:00.000Z",
+          dependsOn: [],
+          blocks: [],
+          owner: "hack",
+          source: "linear",
+          assignee: "Local Owner",
+          tags: [],
+          externalId: "issue-4",
+          externalKey: "ENG-444",
+          externalProjectId: "proj-local",
+        },
+      ],
+      updateTicket: async (input: Record<string, unknown>) => {
+        updatedTickets.push(input);
+        return { ok: true as const };
+      },
+      setStatus: async () => ({ ok: true as const }),
+      createTicket: async () => {
+        throw new Error("createTicket should not be called");
+      },
+      getTicket: async () => null,
+      getTicketDetail: async () => ({
+        ticket: null,
+        events: [],
+        comments: [],
+        reviewNotes: [],
+        syncCheckpoints: [],
+        conflicts: [],
+      }),
+      appendComment: async () => ({
+        ok: true as const,
+        comment: {
+          commentId: "comment-new",
+          ticketId: "T-00004",
+          body: "Fresh remote note",
+          source: "linear",
+          actor: "linear",
+          createdAt: "2026-03-05T10:05:00.000Z",
+        },
+      }),
+      recordSyncCheckpoint: async () => ({
+        ok: true as const,
+        checkpoint: {
+          checkpointId: "checkpoint-4",
+          ticketId: "T-00004",
+          provider: "linear",
+          direction: "linear_to_hack",
+          actor: "test",
+          createdAt: "2026-03-05T10:10:00.000Z",
+        },
+      }),
+      recordSyncConflict: async (input: {
+        readonly field: string;
+        readonly authority?: string;
+      }) => {
+        recordedConflicts.push(input);
+        return {
+          ok: true as const,
+          conflict: {
+            conflictId: `conflict-${input.field}`,
+            ticketId: "T-00004",
+            provider: "linear",
+            field: input.field,
+            status: "open" as const,
+            authority: input.authority,
+            createdAt: "2026-03-05T10:10:00.000Z",
+            updatedAt: "2026-03-05T10:10:00.000Z",
+          },
+        };
+      },
+    },
+    linear: {
+      getIssueById: async () => ({ ok: true as const, data: null }),
+      getIssueByIdentifier: async () => ({
+        ok: true as const,
+        data: {
+          id: "issue-4",
+          identifier: "ENG-444",
+          title: "Linear title",
+          description: "Linear body",
+          url: "https://linear.app/issue/ENG-444",
+          state: {
+            id: "state-1",
+            name: "Done",
+            type: "completed" as const,
+          },
+          teamId: "team-1",
+          projectId: "proj-remote",
+          projectName: "Remote Project",
+          assigneeDisplayName: "Remote Owner",
+          labels: [],
+        },
+      }),
+      listIssueComments: async () => ({
+        ok: true as const,
+        data: [
+          {
+            id: "linear-comment-4",
+            body: "Fresh remote note",
+            createdAt: "2026-03-05T09:10:00.000Z",
+            userDisplayName: "Remote Owner",
+          },
+        ],
+      }),
+    },
+  };
+
+  const result = await __testOnly.syncIssueFromLinearToTicket({
+    runtime,
+    issueIdentifier: "ENG-444",
+    syncToggles: {
+      labels: false,
+      statuses: true,
+      dependencies: false,
+      projects: true,
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(result.conflictsRecorded).toBe(4);
+  expect(recordedConflicts).toEqual([
+    expect.objectContaining({ field: "title", authority: "review_required" }),
+    expect.objectContaining({ field: "body", authority: "review_required" }),
+    expect.objectContaining({ field: "status", authority: "review_required" }),
+    expect.objectContaining({ field: "project", authority: "review_required" }),
+  ]);
+  expect(updatedTickets).toHaveLength(1);
+  expect(updatedTickets[0]?.title).toBeUndefined();
+  expect(updatedTickets[0]?.body).toBeUndefined();
+  expect(updatedTickets[0]?.owner).toBeUndefined();
+  expect(updatedTickets[0]?.source).toBeUndefined();
+});
+
 test("syncTicketToLinearIssue pushes missing local comments and records a checkpoint", async () => {
   const pushedBodies: string[] = [];
   const checkpoints: string[] = [];
diff --git a/tests/tickets-store.test.ts b/tests/tickets-store.test.ts
index 86c4baf20..db942bb90 100644
--- a/tests/tickets-store.test.ts
+++ b/tests/tickets-store.test.ts
@@ -235,7 +235,7 @@ test("tickets store materializes assignee, review notes, comments, checkpoints,
     sourceOperation: "local_command",
   });
   expect(events[0]?.idempotencyKey).toBe(events[0]?.eventId);
-}, 30_000);
+}, 60_000);
 
 test("tickets show json includes materialized sync metadata", async () => {
   const projectRoot = await createTempGitProject({
@@ -331,7 +331,7 @@ test("tickets show json includes materialized sync metadata", async () => {
   expect(
     payload.events.some((event) => event.type === "ticket.comment_appended")
   ).toBe(true);
-}, 20_000);
+}, 60_000);
 
 test("tickets store recovers from a stale tickets bare repo index.lock", async () => {
   const projectRoot = await createTempGitProject({
@@ -498,7 +498,7 @@ test("tickets store ignores duplicate sync checkpoints with the same idempotency
       (event) => event.type === "ticket.sync_checkpoint_recorded"
     )
   ).toHaveLength(1);
-});
+}, 20_000);
 
 test("tickets store records immutable documents and projects body from the active description", async () => {
   const projectRoot = await createTempGitProject({

From 7c8b4769c8ee626ac86055f8ba4f11fb0d4cec77 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:42:17 +0000
Subject: [PATCH 033/134] docs(tickets): harden projection replay design

---
 ...3-14-hack-tickets-sqlite-journal-design.md | 35 +++++++++++++++----
 ...-03-14-hack-tickets-sqlite-journal-plan.md |  6 +++-
 2 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
index 3602288ce..7d4984604 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
@@ -127,6 +127,7 @@ Required keys:
 - `schema_version`
 - `journal_format_version`
 - `projection_status` with values `ready` or `rebuilding`
+- `last_scan_completed_at`
 - `last_replayed_ts`
 - `last_replayed_order_key`
 - `last_replayed_event_id`
@@ -159,6 +160,18 @@ Indexes:
 
 This table is the durable idempotency fence and powers fast `show` queries without reparsing JSONL.
 
+### Segment scan inventory
+
+`journal_segments`
+
+- `segment_name TEXT PRIMARY KEY`
+- `content_hash TEXT NOT NULL`
+- `byte_size INTEGER NOT NULL`
+- `line_count INTEGER NOT NULL`
+- `scanned_at TEXT NOT NULL`
+
+This table tracks which journal segment bytes have already been scanned into the projection. Replay correctness must not rely on the last applied sort key alone because a merged segment can introduce older events that sort before the current replay cursor.
+
 ### Ticket projection
 
 `tickets`
@@ -288,21 +301,26 @@ Indexes:
 1. Open SQLite in WAL mode.
 2. Read `projection_meta`.
 3. If the file is missing, schema version is wrong, status is `rebuilding`, or SQLite reports corruption, delete and rebuild.
-4. Otherwise scan journal segments for new or changed lines after the last applied sort key.
+4. Otherwise compare the current segment inventory against `journal_segments` and fully rescan any segment whose bytes changed or that was not seen before.
+5. Combine all events from changed segments, sort them by canonical replay order, and rely on `journal_events` dedupe to skip events that were already applied.
 
 ### Incremental replay
 
-For each journal line in canonical order:
+Incremental replay works on candidate events gathered from changed segments, not only events after the current cursor. This preserves correctness when two machines append different events into the same monthly file and later merge through git.
+
+For each candidate journal line in canonical order:
 
 1. Parse and validate the event envelope.
 2. Start a transaction.
 3. Insert into `journal_events`.
 4. If the insert is a duplicate with the same hash, commit a no-op transaction.
 5. If it is new, apply the event to the relevant projection tables.
-6. Update `projection_meta` with the last applied sort key.
+6. Update `projection_meta` with the last applied sort key for diagnostics and crash resume.
 7. Commit.
 
-This keeps replay crash-safe and allows progress to resume from the last committed event.
+After a segment scan finishes, update `journal_segments` with the segment fingerprint in a separate transaction boundary only after all of that segment's candidate events were processed successfully.
+
+This keeps replay crash-safe, allows progress to resume from the last committed event, and ensures newly merged historical events are not skipped.
 
 ### Event application rules
 
@@ -328,7 +346,8 @@ Full rebuild is deterministic:
 2. Recreate schema.
 3. Mark `projection_status = rebuilding`.
 4. Replay every journal segment in canonical order.
-5. Mark `projection_status = ready`.
+5. Populate `journal_segments` for the scanned segment set.
+6. Mark `projection_status = ready`.
 
 Given the same journal bytes, rebuild produces the same projection rows and indexes every time.
 
@@ -339,6 +358,7 @@ Crash recovery relies on SQLite transactions and WAL:
 - a half-applied event rolls back automatically
 - committed events remain durable
 - the replay cursor only advances in the same transaction as the projection updates
+- `journal_segments` is only advanced after a successful segment scan
 
 If the process dies mid-rebuild, the next startup sees `projection_status = rebuilding` and starts a clean rebuild rather than trusting partial state.
 
@@ -364,6 +384,8 @@ The projection specifically accelerates:
 
 - `tickets list` by reading `tickets` plus indexed filters
 - `tickets show` by reading one ticket and its child tables
+- `tickets show --json` by reading the ticket projection, child projections, and `journal_events`
+- `tickets inspect` or equivalent health queries later by reading projection metadata instead of rescanning JSONL
 - external sync lookup by `external_system` and `external_id`
 - checkpoint lookup by provider and profile
 - conflict review queries such as open conflicts by provider, project, or ticket
@@ -373,7 +395,7 @@ The projection specifically accelerates:
 
 - Multiple machines can append semantically equivalent journals and later merge through git.
 - Normalization merges by `eventId` union, not by trusting file order.
-- Projection replay is safe after repeated fetch, merge, or sync because duplicate events are idempotent.
+- Projection replay is safe after repeated fetch, merge, or sync because changed segments are rescanned and duplicate events are idempotent.
 - Because SQLite is local-only, machines never need to coordinate projection files. They only need the same journal bytes.
 
 ## Implementation Notes
@@ -386,6 +408,7 @@ The projection specifically accelerates:
 
 - Rebuilding from the same journal twice yields byte-equivalent query results.
 - Reapplying the same merged journal does not duplicate comments, checkpoints, or conflicts.
+- Merging a segment that contains older events than the current replay cursor still converges because replay rescans the changed segment and deduplicates by `eventId`.
 - Deleting the SQLite file does not lose ticket history.
 - Sync-heavy reads stop scanning all JSONL files on each command.
 - Duplicate `eventId` with mismatched payload is detected as corruption.
diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
index 356f9efbb..d52efcc36 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
@@ -45,6 +45,7 @@ git commit -m "test(tickets): define projection replay contract"
 - Create schema helpers for:
   - `projection_meta`
   - `journal_events`
+  - `journal_segments`
   - `tickets`
   - `ticket_dependencies`
   - `ticket_blocks`
@@ -78,9 +79,11 @@ git commit -m "feat(tickets): add projection schema bootstrap"
 
 **Step 1: Write the replay engine**
 
-- Parse journal files in canonical order by `ts`, `orderKey`, `eventId`.
+- Detect new or changed journal segments by fingerprint, then rescan those segments fully.
+- Parse candidate events in canonical order by `ts`, `orderKey`, `eventId`.
 - Insert each event into `journal_events` before mutating read tables.
 - Compare payload hashes on duplicate `eventId`.
+- Advance `journal_segments` only after the segment scan succeeds.
 
 **Step 2: Implement event appliers**
 
@@ -177,6 +180,7 @@ git commit -m "feat(tickets): add projection rebuild recovery"
 
 - sync remote journal content into a local clone
 - replay merged logs with duplicate events
+- replay a merged monthly segment that introduces older events than the current replay cursor
 - confirm projection rows remain correct after repeated sync
 
 **Step 2: Run focused tests** Run: `bun test tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts` Expected: PASS

From ac10f030e86bc22d4ab0cc293e8fa458f13149cc Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:51:52 +0000
Subject: [PATCH 034/134] docs: surface admin trust boundaries

---
 docs/architecture.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 docs/env.md          | 24 ++++++++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/docs/architecture.md b/docs/architecture.md
index 765336650..1cbab5e05 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -68,6 +68,50 @@ graph LR
     - `.internal/extra-hosts.json` (user-managed extra_hosts merged into the override)
     - `.branch/compose.<branch>.override.yml` (branch builds)
 
+## Administrative trust boundary
+
+Hack remains local-first. Shared administration is an explicit escalation, not an ambient property of
+using the CLI.
+
+### Resource scopes
+
+- **Local project**: device-local project metadata and runtime state managed from `.hack/` without broker
+  dependency.
+- **Shared project**: broker-managed project metadata owned by a Hack team or organization.
+- **Organization**: top-level shared administrative boundary for teams and org-wide projects.
+- **Team**: collaboration boundary inside an organization; the default shared owner for most projects.
+- **Environment bundle**: a declared env contract plus an explicit sharing policy for metadata and values.
+
+### Ownership rules
+
+- Projects default to `local` ownership.
+- Promotion from `local` to shared ownership must be explicit.
+- Shared projects are managed by the broker; local projects are managed only from the local machine.
+- Project ownership and env value disclosure are separate decisions.
+- Team or org membership alone does not imply secret-value access.
+
+### Local-only operations
+
+- project init/up/down/restart/logs/open/session workflows
+- local tickets
+- local `.hack/.env` edits and local secret backend operations
+- local project owner inspection and local user ownership assignment
+
+### Broker-mediated operations
+
+- organization and team lifecycle
+- org/team membership changes
+- project transfer to team or organization ownership
+- shared project access grants
+- shared env grants, rotation, and encrypted value custody
+- audit logging for shared admin mutations
+
+### Boundary rule
+
+If an operation mutates shared identity, shared membership, shared project access, or shared secret
+custody, it must be broker-mediated and authenticated. If it only changes device-local runtime state,
+it stays local.
+
 
 ## Internal DNS + TLS (containers)
 
diff --git a/docs/env.md b/docs/env.md
index 3314d7971..0119b6d96 100644
--- a/docs/env.md
+++ b/docs/env.md
@@ -2,6 +2,25 @@
 
 hack supports a project-scoped env contract (shareable, no values) plus safe secret storage for local development.
 
+## Ownership and sharing policy
+
+Env management is separate from project ownership. A project can be shared while its env values remain
+local-only.
+
+### Sharing modes
+
+- `local_only`: contract and values stay on the local machine
+- `shared_metadata_only`: env contract metadata is shared, but values remain local
+- `shared_values`: encrypted values are broker-mediated and access-controlled
+
+### Secure-by-default rules
+
+- New projects start with local-only env custody.
+- Sharing a project must not silently share env values.
+- Project access does not automatically grant env value access.
+- Team membership does not automatically grant env administration.
+- Shared value disclosure must be checked independently from project access.
+
 ## Files and storage
 
 - `.hack/hack.env.json` (committed): declares env vars, required vs optional, per-service scope, and where values should come from.
@@ -109,6 +128,11 @@ Security posture:
 - Secret values are never written into `.hack/` YAML files.
 - Plain env values live in `.hack/.env` (expected to be gitignored in most repos).
 
+Planned shared-admin direction:
+- keep `hack env set` and `hack env unset` local by default
+- require explicit broker-mediated flows for shared env grants, rotation, and encrypted value custody
+- keep metadata sharing and value sharing as separate policy choices
+
 ## Remote node secret behavior
 
 Current behavior (today):

From 86870d682f08acc2f497916b20898321f9dad5c1 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:54:02 +0000
Subject: [PATCH 035/134] docs(tickets): tighten sqlite projection handoff docs

---
 .../2026-03-14-hack-tickets-sqlite-journal-design.md      | 5 +++++
 docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md | 8 --------
 2 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
index 7d4984604..670a22a3e 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
@@ -4,6 +4,11 @@
 
 Define a durable local storage architecture for Hack Tickets that keeps the git-backed JSONL journal as the canonical, portable source of truth while adding a deterministic SQLite projection for fast reads, sync queries, and repeated replay.
 
+## Inputs
+
+- Linear issue: `HACK-450`
+- Relevant spec: Tickets Normalization And Storage Spec
+
 ## Current Foundation
 
 - Ticket history is stored as append-only monthly JSONL segments in `.hack/tickets/events/events-YYYY-MM.jsonl`.
diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
index d52efcc36..978a7db4f 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
@@ -220,11 +220,3 @@ Expected: PASS
 git add docs/guides/tickets.md docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md tests/tickets-projection.test.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts tests/tickets-git-channel.test.ts src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/commands.ts
 git commit -m "feat(tickets): finish sqlite projection architecture"
 ```
-
-Plan complete and saved to `docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md`. Two execution options:
-
-**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
-
-**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
-
-Which approach?

From 9282a3c40c7cef80c500bc7aba341c1c40fda027 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:54:48 +0000
Subject: [PATCH 036/134] docs: clarify shared admin guidance

---
 docs/README.md |  8 ++++++--
 docs/cli.md    | 23 +++++++++++++++++++++++
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index e493be242..278fefff5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,9 +5,9 @@ This directory contains the public documentation for hack. Specs remain in `SPEC
 ## Core docs
 
 - [CLI reference](cli.md)
-- [Architecture](architecture.md)
+- [Architecture](architecture.md) - system model, trust boundaries, and local vs broker-mediated admin
 - [Sessions](sessions.md) - mux session management (tmux or zellij) + API
-- [Env & secrets](env.md) - env contract + `.hack/.env` + OS keychain secrets
+- [Env & secrets](env.md) - env contract, sharing policy, `.hack/.env`, and OS keychain secrets
 - [Lifecycle](lifecycle.md) - project startup hooks + managed host processes
 - [Gateway overview](gateway.md)
 - [Gateway API](gateway-api.md)
@@ -15,6 +15,10 @@ This directory contains the public documentation for hack. Specs remain in `SPEC
 - [Extensions](extensions.md)
 - [Control-plane SDK](sdk.md)
 
+Admin model reference:
+- See [Architecture](architecture.md) for the local-only vs broker-mediated admin boundary.
+- See [Env & secrets](env.md) for env ownership, sharing modes, and secure-by-default secret custody.
+
 Monorepo note:
 - Root scripts orchestrate workspace tasks through Turbo.
 - Package-local commands remain available via `bun run --cwd <workspace> <script>`.
diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..beeffda24 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -10,6 +10,22 @@ Run `hack help` or `hack help <command>` for interactive help.
 - `--profile` accepts comma-separated compose profiles.
 - Options marked repeatable can be passed multiple times.
 
+## Local vs broker-mediated administration
+
+This reference documents the commands that exist today. Hack stays local-first by default.
+
+- Local runtime and project operations do not require Hack account auth.
+- Shared administration is a separate trust boundary.
+- If an operation would mutate shared identity, membership, project ownership, access grants, or shared
+  secret custody, it should be broker-mediated and authenticated rather than silently falling back to a
+  local write.
+
+Current practical rule:
+- `hack up`, `hack down`, `hack logs`, `hack session`, `hack tickets`, and local `hack env` operations are
+  local-first surfaces.
+- The teams-and-organizations admin model is defined in `docs/architecture.md` and `docs/env.md` until the
+  corresponding shared-admin command surfaces land.
+
 ## Top-level commands
 
 | Command | Summary | Group |
@@ -476,6 +492,13 @@ Options:
 
 Usage: `hack env <subcommand>`
 
+Notes:
+
+- The current `hack env` surface is local-first.
+- `hack env set` and `hack env unset` manage local project env state and configured local secret backends.
+- Shared env grants, value custody, and rotation are planned as explicit broker-mediated flows rather than
+  implicit extensions of local env commands.
+
 Subcommands:
 
 | Subcommand | Summary |

From b35ac6f9fdd01f2f76f1af4b265e2aed78c80a2f Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:02:36 +0000
Subject: [PATCH 037/134] docs(tickets): clarify projection rebuild triggers

---
 docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md | 5 ++++-
 docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md   | 1 +
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
index 670a22a3e..4d1c961c0 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
@@ -107,6 +107,8 @@ Replay uses this total order:
 2. `orderKey` ascending when present
 3. `eventId` ascending
 
+Current writers already stamp `orderKey`, so same-second local writes preserve their original append sequence. The `eventId` fallback exists for legacy rows or any imported events that are missing `orderKey`.
+
 This order is deterministic across machines and rebuilds, even when segment files were merged from multiple writers. Segment filename and line number are recorded for diagnostics and incremental scanning, but they are not part of domain ordering.
 
 ### Idempotency rule
@@ -305,7 +307,7 @@ Indexes:
 
 1. Open SQLite in WAL mode.
 2. Read `projection_meta`.
-3. If the file is missing, schema version is wrong, status is `rebuilding`, or SQLite reports corruption, delete and rebuild.
+3. If the file is missing, `schema_version` is wrong, `journal_format_version` is wrong, status is `rebuilding`, or SQLite reports corruption, delete and rebuild.
 4. Otherwise compare the current segment inventory against `journal_segments` and fully rescan any segment whose bytes changed or that was not seen before.
 5. Combine all events from changed segments, sort them by canonical replay order, and rely on `journal_events` dedupe to skip events that were already applied.
 
@@ -373,6 +375,7 @@ Recoverable failures:
 
 - missing SQLite file
 - outdated projection schema
+- outdated journal format version
 - WAL or database corruption
 
 Unrecoverable without operator action:
diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
index 978a7db4f..9a924a793 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
@@ -152,6 +152,7 @@ git commit -m "feat(tickets): serve reads from sqlite projection"
 
 - missing database
 - schema version mismatch
+- journal format version mismatch
 - `projection_status = rebuilding`
 - SQLite open failure or corruption
 

From 8ae5759b3e169c0d462e997ee6043625850e24b7 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:06:04 +0000
Subject: [PATCH 038/134] docs(tickets): record journal projection architecture

---
 docs/architecture.md   |  1 +
 docs/guides/tickets.md | 13 +++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/docs/architecture.md b/docs/architecture.md
index 765336650..1f5f88055 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -201,6 +201,7 @@ extension manifests and exposes their APIs; the CLI dispatches extension command
 
 - **Gateway**: optional HTTP/WS access to `hackd` (localhost by default).
 - **Supervisor**: job execution + streaming for agents.
+- **Tickets**: git-backed append-only journal storage with a planned rebuildable local SQLite projection for fast reads and sync indexing.
 
 ```mermaid
 graph LR
diff --git a/docs/guides/tickets.md b/docs/guides/tickets.md
index 279f60a02..00de5d9ab 100644
--- a/docs/guides/tickets.md
+++ b/docs/guides/tickets.md
@@ -130,6 +130,17 @@ Tip: use `--body-stdin` for multi-line markdown.
 - Ticket writes automatically commit and push to the tickets ref when git sync is enabled and a remote exists.
 - `sync` normalizes the event logs, commits, and pushes the tickets ref.
 
+### Storage architecture
+
+The adopted storage model keeps git portability as the primary constraint:
+
+- The JSONL journal remains the only portable source of truth.
+- A local SQLite projection under `.hack/tickets/state/` is the planned read model for fast queries and sync lookups.
+- The projection is disposable local state, not a second authority. If it is missing, stale, or corrupted, it should be rebuilt from the journal.
+- Replay is deterministic and idempotent by ordering events on `ts`, `orderKey`, and `eventId`, then deduplicating by `eventId`.
+
+Until the SQLite projection lands in code, reads still materialize from JSONL directly. The detailed projection design lives in [`docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md`](../plans/2026-03-14-hack-tickets-sqlite-journal-design.md).
+
 ### Storage layout
 
 In your project repo:
@@ -137,6 +148,8 @@ In your project repo:
 - `.hack/tickets/events/events-YYYY-MM.jsonl` — event log segments (UTC month)
 - `.hack/tickets/git/bare.git` — a bare repo used to manage the tickets ref
 - `.hack/tickets/git/worktree` — a worktree used for reading/writing ticket data
+- `.hack/tickets/state/projection.sqlite` — planned local-only SQLite projection for indexed reads and replay state
+- `.hack/tickets/state/projection.sqlite-wal` / `.hack/tickets/state/projection.sqlite-shm` — planned SQLite companion files, safe to delete and rebuild
 
 ## Configuration
 

From 4ded32e5000fd0d792850f8a4552315e9938f7f1 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:12:42 +0000
Subject: [PATCH 039/134] feat: add explicit project ownership inspection

---
 src/cli/spec.ts                     |   2 +
 src/commands/project-admin.ts       | 123 +++++++++++++++++++++
 src/commands/projects.ts            |  17 +++
 src/lib/project-meta.ts             |  33 ++++--
 src/lib/project-views.ts            |  31 ++++--
 src/lib/project.ts                  |  87 ++++++++++++++-
 tests/cli-command.test.ts           |  11 ++
 tests/project-config.test.ts        |  24 +++++
 tests/project-owner-command.test.ts | 162 ++++++++++++++++++++++++++++
 tests/project-views.test.ts         |  43 ++++++++
 tests/runtime-cache.test.ts         |  13 +++
 11 files changed, 526 insertions(+), 20 deletions(-)
 create mode 100644 src/commands/project-admin.ts
 create mode 100644 tests/project-owner-command.test.ts

diff --git a/src/cli/spec.ts b/src/cli/spec.ts
index 079084d87..5beae77bd 100644
--- a/src/cli/spec.ts
+++ b/src/cli/spec.ts
@@ -26,6 +26,7 @@ import {
   runCommand,
   upCommand,
 } from "../commands/project.ts";
+import { projectCommand } from "../commands/project-admin.ts";
 import { projectsCommand, statusCommand } from "../commands/projects.ts";
 import { remoteCommand } from "../commands/remote.ts";
 import { secretsCommand } from "../commands/secrets.ts";
@@ -59,6 +60,7 @@ export const CLI_SPEC = defineCli({
     statusCommand,
     usageCommand,
     projectsCommand,
+    projectCommand,
     initCommand,
     upCommand,
     downCommand,
diff --git a/src/commands/project-admin.ts b/src/commands/project-admin.ts
new file mode 100644
index 000000000..9c06016b4
--- /dev/null
+++ b/src/commands/project-admin.ts
@@ -0,0 +1,123 @@
+import { resolve } from "node:path";
+import type { CommandHandlerFor } from "../cli/command.ts";
+import { CliUsageError, defineCommand, withHandler } from "../cli/command.ts";
+import { optJson, optPath, optProject } from "../cli/options.ts";
+import { HACK_PROJECT_DIR_PRIMARY } from "../constants.ts";
+import {
+  findProjectContext,
+  readProjectConfig,
+  sanitizeProjectSlug,
+} from "../lib/project.ts";
+import { resolveRegisteredProjectByName } from "../lib/projects-registry.ts";
+import { display } from "../ui/display.ts";
+
+const ownerShowOptions = [optPath, optProject, optJson] as const;
+
+const ownerShowSpec = defineCommand({
+  name: "show",
+  summary: "Show the explicit ownership for the current project",
+  group: "Project",
+  options: ownerShowOptions,
+  positionals: [],
+  subcommands: [],
+} as const);
+
+const ownerSpec = defineCommand({
+  name: "owner",
+  summary: "Inspect or manage project ownership",
+  group: "Project",
+  options: [],
+  positionals: [],
+  subcommands: [ownerShowSpec],
+} as const);
+
+const projectSpec = defineCommand({
+  name: "project",
+  summary: "Inspect or manage project metadata",
+  group: "Project",
+  options: [],
+  positionals: [],
+  subcommands: [ownerSpec],
+} as const);
+
+const handleOwnerShow: CommandHandlerFor<typeof ownerShowSpec> = async ({
+  ctx,
+  args,
+}): Promise<number> => {
+  const project = await resolveProjectTarget({
+    cwd: ctx.cwd,
+    pathOpt: args.options.path,
+    projectOpt: args.options.project,
+  });
+  const config = await readProjectConfig(project);
+  const payload = {
+    project_root: project.projectRoot,
+    ownership: {
+      mode: config.ownership.mode,
+      owner_type: config.ownership.ownerType,
+      owner_id: config.ownership.ownerId,
+      managed_by: config.ownership.managedBy,
+    },
+  };
+
+  if (args.options.json === true) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return 0;
+  }
+
+  await display.kv({
+    entries: [
+      ["Project root", payload.project_root],
+      ["Ownership mode", payload.ownership.mode],
+      ["Owner type", payload.ownership.owner_type],
+      ["Owner id", payload.ownership.owner_id ?? ""],
+      ["Managed by", payload.ownership.managed_by],
+    ],
+  });
+  return 0;
+};
+
+const ownerCommand = {
+  ...ownerSpec,
+  subcommands: [withHandler(ownerShowSpec, handleOwnerShow)],
+} as const;
+
+export const projectCommand = {
+  ...projectSpec,
+  subcommands: [ownerCommand],
+} as const;
+
+async function resolveProjectTarget(input: {
+  readonly cwd: string;
+  readonly pathOpt: string | undefined;
+  readonly projectOpt: string | undefined;
+}) {
+  if (input.pathOpt && input.projectOpt) {
+    throw new CliUsageError("Use either --path or --project (not both).");
+  }
+
+  if (input.projectOpt) {
+    const name = sanitizeProjectSlug(input.projectOpt);
+    if (name.length === 0) {
+      throw new CliUsageError("Invalid --project value.");
+    }
+    const project = await resolveRegisteredProjectByName({ name });
+    if (!project) {
+      throw new CliUsageError(
+        `Unknown project "${name}". Run 'hack init' in that repo (or run 'hack projects' to see registered projects).`
+      );
+    }
+    return project;
+  }
+
+  const startDir = input.pathOpt
+    ? resolve(input.cwd, input.pathOpt)
+    : input.cwd;
+  const project = await findProjectContext(startDir);
+  if (!project) {
+    throw new Error(
+      `No ${HACK_PROJECT_DIR_PRIMARY}/ (or legacy .dev/) found. Run: hack init`
+    );
+  }
+  return project;
+}
diff --git a/src/commands/projects.ts b/src/commands/projects.ts
index e48d0bcd1..d3c040cb6 100644
--- a/src/commands/projects.ts
+++ b/src/commands/projects.ts
@@ -391,6 +391,15 @@ async function renderProjectDetails(opts: {
   if (p.projectDir) {
     meta.push(["Project dir", p.projectDir]);
   }
+  if (p.ownership) {
+    meta.push([
+      "Ownership",
+      `${p.ownership.mode}:${p.ownership.ownerType}${
+        p.ownership.ownerId ? `:${p.ownership.ownerId}` : ""
+      }`,
+    ]);
+    meta.push(["Managed by", p.ownership.managedBy]);
+  }
   const mappedIp = await readInternalExtraHostsIp({ projectDir: p.projectDir });
   const caddySummary = formatCaddySummary({ caddyIp: opts.caddyIp, mappedIp });
   if (caddySummary) {
@@ -564,6 +573,14 @@ async function renderProjectMeta(opts: {
 }): Promise<void> {
   await display.section("Meta");
 
+  await display.kv({
+    entries: [
+      ["Ownership mode", opts.meta.ownership.mode],
+      ["Owner type", opts.meta.ownership.ownerType],
+      ["Owner id", opts.meta.ownership.ownerId ?? ""],
+      ["Managed by", opts.meta.ownership.managedBy],
+    ],
+  });
   await renderGitMeta({ git: opts.meta.git });
   await renderGitWorktrees({ worktrees: opts.meta.git.worktrees });
   await renderSessionsMeta({ sessions: opts.meta.sessions.sessions });
diff --git a/src/lib/project-meta.ts b/src/lib/project-meta.ts
index 3d571462a..538cccc78 100644
--- a/src/lib/project-meta.ts
+++ b/src/lib/project-meta.ts
@@ -9,6 +9,8 @@ import { pathExists, readTextFile } from "./fs.ts";
 import { isRecord } from "./guards.ts";
 import type { HackEnvSource } from "./hack-env.ts";
 import { resolveHackEnv } from "./hack-env.ts";
+import type { ProjectOwnershipConfig } from "./project.ts";
+import { readProjectConfig } from "./project.ts";
 import { exec } from "./shell.ts";
 
 export type GitWorktreeMeta = {
@@ -71,6 +73,7 @@ export type ComposeBuildMeta = {
 };
 
 export type ProjectMeta = {
+  readonly ownership: ProjectOwnershipConfig;
   readonly git: GitMeta;
   readonly hackBranches: HackBranchesMeta;
   readonly env: EnvMeta;
@@ -84,18 +87,28 @@ export async function resolveProjectMeta(opts: {
   readonly projectDir: string;
   readonly composeFile: string;
 }): Promise<ProjectMeta> {
-  const [git, hackBranches, env, sessions, composeBuild] = await Promise.all([
-    resolveGitMeta({ repoRoot: opts.repoRoot }),
-    resolveHackBranchesMeta({ projectDir: opts.projectDir }),
-    resolveEnvMeta({
-      projectDir: opts.projectDir,
-      projectName: opts.projectName,
-    }),
-    resolveSessionsMeta({ projectName: opts.projectName }),
-    resolveComposeBuildMeta({ composeFile: opts.composeFile }),
-  ]);
+  const [config, git, hackBranches, env, sessions, composeBuild] =
+    await Promise.all([
+      readProjectConfig({
+        projectRoot: opts.repoRoot,
+        projectDirName: ".hack",
+        projectDir: opts.projectDir,
+        composeFile: opts.composeFile,
+        envFile: resolve(opts.projectDir, "hack.env.json"),
+        configFile: resolve(opts.projectDir, "hack.config.json"),
+      }),
+      resolveGitMeta({ repoRoot: opts.repoRoot }),
+      resolveHackBranchesMeta({ projectDir: opts.projectDir }),
+      resolveEnvMeta({
+        projectDir: opts.projectDir,
+        projectName: opts.projectName,
+      }),
+      resolveSessionsMeta({ projectName: opts.projectName }),
+      resolveComposeBuildMeta({ composeFile: opts.composeFile }),
+    ]);
 
   return {
+    ownership: config.ownership,
     git,
     hackBranches,
     env,
diff --git a/src/lib/project-views.ts b/src/lib/project-views.ts
index d134753c9..6548b51dc 100644
--- a/src/lib/project-views.ts
+++ b/src/lib/project-views.ts
@@ -11,8 +11,10 @@ import { readControlPlaneConfig } from "../control-plane/sdk/config.ts";
 import { pathExists, readTextFile } from "./fs.ts";
 import { isRecord } from "./guards.ts";
 import {
+  type ProjectConfig,
   type ProjectLifecycleCommand,
   type ProjectLifecycleProcess,
+  type ProjectOwnershipConfig,
   readProjectConfig,
 } from "./project.ts";
 import type { RegisteredProject } from "./projects-registry.ts";
@@ -76,6 +78,7 @@ export type ProjectView = {
   readonly devHost: string | null;
   readonly repoRoot: string | null;
   readonly projectDir: string | null;
+  readonly ownership: ProjectOwnershipConfig | null;
   readonly definedServices: readonly string[] | null;
   readonly extensionsEnabled: readonly string[] | null;
   readonly features: readonly string[] | null;
@@ -259,11 +262,12 @@ async function buildRegisteredProjectView(opts: {
         projectDir: opts.registration.projectDir,
       })
     : null;
-  const lifecycle = projectDirOk
-    ? await resolveProjectLifecycleView({
+  const config = projectDirOk
+    ? await readRegisteredProjectConfig({
         registration: opts.registration,
       })
     : null;
+  const lifecycle = resolveProjectLifecycleView({ config });
 
   return {
     projectId: opts.registration.id,
@@ -271,6 +275,7 @@ async function buildRegisteredProjectView(opts: {
     devHost: opts.registration.devHost ?? null,
     repoRoot: opts.registration.repoRoot,
     projectDir: opts.registration.projectDir,
+    ownership: config?.ownership ?? null,
     definedServices,
     extensionsEnabled: extensions?.enabled ?? null,
     features: extensions?.features ?? null,
@@ -301,6 +306,7 @@ function buildUnregisteredProjectView(opts: {
     devHost: null,
     repoRoot: null,
     projectDir: null,
+    ownership: null,
     definedServices: null,
     extensionsEnabled: null,
     features: null,
@@ -325,6 +331,14 @@ export function serializeProjectView(
     dev_host: view.devHost ?? null,
     repo_root: view.repoRoot ?? null,
     project_dir: view.projectDir ?? null,
+    ownership: view.ownership
+      ? {
+          mode: view.ownership.mode,
+          owner_type: view.ownership.ownerType,
+          owner_id: view.ownership.ownerId,
+          managed_by: view.ownership.managedBy,
+        }
+      : null,
     defined_services: view.definedServices ?? null,
     extensions_enabled: view.extensionsEnabled ?? null,
     features: view.features ?? null,
@@ -388,10 +402,10 @@ export function serializeProjectView(
   };
 }
 
-async function resolveProjectLifecycleView(opts: {
+async function readRegisteredProjectConfig(opts: {
   readonly registration: RegisteredProject;
-}): Promise<ProjectLifecycleView | null> {
-  const config = await readProjectConfig({
+}): Promise<ProjectConfig> {
+  return await readProjectConfig({
     projectRoot: opts.registration.repoRoot,
     projectDirName: opts.registration.projectDirName,
     projectDir: opts.registration.projectDir,
@@ -402,7 +416,12 @@ async function resolveProjectLifecycleView(opts: {
     envFile: resolve(opts.registration.projectDir, PROJECT_ENV_FILENAME),
     configFile: resolve(opts.registration.projectDir, PROJECT_CONFIG_FILENAME),
   });
-  const lifecycle = config.lifecycle;
+}
+
+function resolveProjectLifecycleView(opts: {
+  readonly config: ProjectConfig | null;
+}): ProjectLifecycleView | null {
+  const lifecycle = opts.config?.lifecycle;
   if (!lifecycle) {
     return null;
   }
diff --git a/src/lib/project.ts b/src/lib/project.ts
index 13e056573..90b1317fe 100644
--- a/src/lib/project.ts
+++ b/src/lib/project.ts
@@ -129,10 +129,22 @@ export interface ProjectConfig {
   readonly internal?: ProjectInternalConfig;
   readonly sessions?: ProjectSessionsConfig;
   readonly lifecycle?: ProjectLifecycleConfig;
+  readonly ownership: ProjectOwnershipConfig;
   readonly configPath?: string;
   readonly parseError?: string;
 }
 
+export type ProjectOwnershipMode = "local" | "shared";
+export type ProjectOwnershipOwnerType = "user" | "team" | "organization";
+export type ProjectOwnershipManager = "local" | "broker";
+
+export interface ProjectOwnershipConfig {
+  readonly mode: ProjectOwnershipMode;
+  readonly ownerType: ProjectOwnershipOwnerType;
+  readonly ownerId: string | null;
+  readonly managedBy: ProjectOwnershipManager;
+}
+
 export interface ProjectSessionsConfig {
   /**
    * Mux backend for `hack session`.
@@ -268,7 +280,9 @@ export async function readProjectConfig(
     return parseProjectConfigToml({ text: tomlText, path: tomlPath });
   }
 
-  return {};
+  return {
+    ownership: defaultProjectOwnership(),
+  };
 }
 
 function parseProjectConfigJson(opts: {
@@ -280,7 +294,11 @@ function parseProjectConfigJson(opts: {
     parsed = JSON.parse(opts.text);
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : "Invalid JSON";
-    return { parseError: message, configPath: opts.path };
+    return {
+      parseError: message,
+      configPath: opts.path,
+      ownership: defaultProjectOwnership(),
+    };
   }
   return parseProjectConfigRecord(parsed, opts.path);
 }
@@ -294,14 +312,18 @@ function parseProjectConfigToml(opts: {
     parsed = Bun.TOML.parse(opts.text);
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : "Invalid TOML";
-    return { parseError: message, configPath: opts.path };
+    return {
+      parseError: message,
+      configPath: opts.path,
+      ownership: defaultProjectOwnership(),
+    };
   }
   return parseProjectConfigRecord(parsed, opts.path);
 }
 
 function parseProjectConfigRecord(value: unknown, path: string): ProjectConfig {
   if (!isRecord(value)) {
-    return { configPath: path };
+    return { configPath: path, ownership: defaultProjectOwnership() };
   }
 
   const name = getString(value, "name");
@@ -316,6 +338,7 @@ function parseProjectConfigRecord(value: unknown, path: string): ProjectConfig {
     lifecycle: lifecycleBase,
     startup,
   });
+  const ownership = parseProjectOwnership(getRecord(value, "ownership"));
 
   return {
     ...(name ? { name } : {}),
@@ -325,10 +348,66 @@ function parseProjectConfigRecord(value: unknown, path: string): ProjectConfig {
     ...(internal ? { internal } : {}),
     ...(sessions ? { sessions } : {}),
     ...(lifecycle ? { lifecycle } : {}),
+    ownership,
     configPath: path,
   };
 }
 
+export function defaultProjectOwnership(): ProjectOwnershipConfig {
+  return {
+    mode: "local",
+    ownerType: "user",
+    ownerId: null,
+    managedBy: "local",
+  };
+}
+
+function parseProjectOwnership(
+  value: Record<string, unknown> | undefined
+): ProjectOwnershipConfig {
+  const mode =
+    parseProjectOwnershipMode(value ? getString(value, "mode") : undefined) ??
+    "local";
+  if (mode === "local") {
+    return defaultProjectOwnership();
+  }
+
+  return {
+    mode: "shared",
+    ownerType:
+      parseProjectOwnershipOwnerType(
+        value ? getString(value, "owner_type") : undefined
+      ) ?? "team",
+    ownerId: normalizeProjectOwnerId(
+      value ? getString(value, "owner_id") : undefined
+    ),
+    managedBy: "broker",
+  };
+}
+
+function parseProjectOwnershipMode(
+  value: string | undefined
+): ProjectOwnershipMode | undefined {
+  if (value === "local" || value === "shared") {
+    return value;
+  }
+  return undefined;
+}
+
+function parseProjectOwnershipOwnerType(
+  value: string | undefined
+): ProjectOwnershipOwnerType | undefined {
+  if (value === "user" || value === "team" || value === "organization") {
+    return value;
+  }
+  return undefined;
+}
+
+function normalizeProjectOwnerId(value: string | undefined): string | null {
+  const trimmed = value?.trim() ?? "";
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 function parseStartupEntries(
   value: unknown
 ): readonly ProjectStartupEntry[] | undefined {
diff --git a/tests/cli-command.test.ts b/tests/cli-command.test.ts
index be68608ee..151973d74 100644
--- a/tests/cli-command.test.ts
+++ b/tests/cli-command.test.ts
@@ -60,3 +60,14 @@ test("resolveCommand finds crash-capture command", () => {
   ]);
   expect(resolved.remainingPositionals).toEqual([]);
 });
+
+test("resolveCommand finds nested project owner show command", () => {
+  const resolved = resolveCommand(CLI_SPEC, ["project", "owner", "show"]);
+  expect(resolved.command?.name).toBe("show");
+  expect(resolved.path.map((command) => command.name)).toEqual([
+    "project",
+    "owner",
+    "show",
+  ]);
+  expect(resolved.remainingPositionals).toEqual([]);
+});
diff --git a/tests/project-config.test.ts b/tests/project-config.test.ts
index c19d65549..6d5f59c7a 100644
--- a/tests/project-config.test.ts
+++ b/tests/project-config.test.ts
@@ -73,6 +73,11 @@ test("readProjectConfig parses json config fields", async () => {
             "db.example.com": "127.0.0.1",
           },
         },
+        ownership: {
+          mode: "shared",
+          owner_type: "team",
+          owner_id: "team_123",
+        },
       },
       null,
       2
@@ -93,6 +98,12 @@ test("readProjectConfig parses json config fields", async () => {
     "api.example.com": "host-gateway",
     "db.example.com": "127.0.0.1",
   });
+  expect(cfg.ownership).toEqual({
+    mode: "shared",
+    ownerType: "team",
+    ownerId: "team_123",
+    managedBy: "broker",
+  });
 });
 
 test("readProjectConfig captures parse errors", async () => {
@@ -102,6 +113,19 @@ test("readProjectConfig captures parse errors", async () => {
   expect(cfg.parseError).toBeTruthy();
 });
 
+test("readProjectConfig defaults ownership to local user scope", async () => {
+  const ctx = await createProjectDir();
+
+  const cfg = await readProjectConfig(ctx);
+
+  expect(cfg.ownership).toEqual({
+    mode: "local",
+    ownerType: "user",
+    ownerId: null,
+    managedBy: "local",
+  });
+});
+
 test("resolveProjectOauthTld falls back to default when enabled", () => {
   expect(resolveProjectOauthTld({ enabled: true, tld: "" })).toBe("gy");
   expect(resolveProjectOauthTld({ enabled: false })).toBeNull();
diff --git a/tests/project-owner-command.test.ts b/tests/project-owner-command.test.ts
new file mode 100644
index 000000000..7ff018788
--- /dev/null
+++ b/tests/project-owner-command.test.ts
@@ -0,0 +1,162 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  PROJECT_COMPOSE_FILENAME,
+  PROJECT_CONFIG_FILENAME,
+  PROJECT_ENV_FILENAME,
+} from "../src/constants.ts";
+
+type CapturedRunResult = {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+let tempDir: string | null = null;
+let originalSetupSyncMode: string | undefined;
+let originalLogger: string | undefined;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-project-owner-"));
+  originalSetupSyncMode = process.env.HACK_SETUP_SYNC_MODE;
+  originalLogger = process.env.HACK_LOGGER;
+  process.env.HACK_SETUP_SYNC_MODE = "off";
+  process.env.HACK_LOGGER = "console";
+});
+
+afterEach(async () => {
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true });
+    tempDir = null;
+  }
+  if (originalSetupSyncMode !== undefined) {
+    process.env.HACK_SETUP_SYNC_MODE = originalSetupSyncMode;
+  } else {
+    process.env.HACK_SETUP_SYNC_MODE = undefined;
+  }
+  if (originalLogger !== undefined) {
+    process.env.HACK_LOGGER = originalLogger;
+  } else {
+    process.env.HACK_LOGGER = undefined;
+  }
+});
+
+test("project owner show returns default local ownership as json", async () => {
+  const projectRoot = await createHackProject();
+
+  const result = await runCliWithCapturedOutput([
+    "project",
+    "owner",
+    "show",
+    "--path",
+    projectRoot,
+    "--json",
+  ]);
+
+  expect(result.exitCode).toBe(0);
+  expect(result.stderr.trim()).toBe("");
+  expect(JSON.parse(result.stdout)).toEqual({
+    project_root: projectRoot,
+    ownership: {
+      mode: "local",
+      owner_type: "user",
+      owner_id: null,
+      managed_by: "local",
+    },
+  });
+});
+
+test("project owner show returns explicit shared ownership as json", async () => {
+  const projectRoot = await createHackProject({
+    ownership: {
+      mode: "shared",
+      owner_type: "organization",
+      owner_id: "org_123",
+    },
+  });
+
+  const result = await runCliWithCapturedOutput([
+    "project",
+    "owner",
+    "show",
+    "--path",
+    projectRoot,
+    "--json",
+  ]);
+
+  expect(result.exitCode).toBe(0);
+  expect(result.stderr.trim()).toBe("");
+  expect(JSON.parse(result.stdout)).toEqual({
+    project_root: projectRoot,
+    ownership: {
+      mode: "shared",
+      owner_type: "organization",
+      owner_id: "org_123",
+      managed_by: "broker",
+    },
+  });
+});
+
+async function createHackProject(opts?: {
+  readonly ownership?: {
+    readonly mode: "local" | "shared";
+    readonly owner_type: "user" | "team" | "organization";
+    readonly owner_id?: string;
+  };
+}): Promise<string> {
+  if (!tempDir) {
+    throw new Error("Missing temp directory");
+  }
+
+  const projectRoot = join(tempDir, "repo");
+  const projectDir = join(projectRoot, ".hack");
+  await mkdir(projectDir, { recursive: true });
+  await writeFile(join(projectDir, PROJECT_COMPOSE_FILENAME), "services: {}\n");
+  await writeFile(join(projectDir, PROJECT_ENV_FILENAME), "");
+  await writeFile(
+    join(projectDir, PROJECT_CONFIG_FILENAME),
+    JSON.stringify(
+      opts?.ownership
+        ? {
+            ownership: opts.ownership,
+          }
+        : {},
+      null,
+      2
+    )
+  );
+
+  return projectRoot;
+}
+
+async function runCliWithCapturedOutput(
+  args: readonly string[]
+): Promise<CapturedRunResult> {
+  let stdout = "";
+  let stderr = "";
+  const originalStdoutWrite = process.stdout.write;
+  const originalStderrWrite = process.stderr.write;
+
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdout +=
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    return true;
+  }) as typeof process.stdout.write;
+
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderr +=
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    return true;
+  }) as typeof process.stderr.write;
+
+  try {
+    const { runCli } = await import("../src/cli/run.ts");
+    const exitCode = await runCli(args);
+    return { exitCode, stdout, stderr };
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+}
diff --git a/tests/project-views.test.ts b/tests/project-views.test.ts
index f0782c351..65a7e2928 100644
--- a/tests/project-views.test.ts
+++ b/tests/project-views.test.ts
@@ -185,6 +185,49 @@ test("buildProjectViews includes defined services and runtime status", async ()
   });
 });
 
+test("buildProjectViews includes explicit project ownership metadata", async () => {
+  const alpha = await createProject({
+    name: "alpha",
+    services: ["api"],
+    configJson: JSON.stringify(
+      {
+        ownership: {
+          mode: "shared",
+          owner_type: "team",
+          owner_id: "team_alpha",
+        },
+      },
+      null,
+      2
+    ),
+  });
+
+  const views = await buildProjectViews({
+    registryProjects: [alpha],
+    runtime: [],
+    runtimeOk: true,
+    filter: null,
+    includeUnregistered: false,
+    muxSessions: [],
+  });
+
+  const alphaView = views.find((view) => view.name === "alpha");
+  expect(alphaView?.ownership).toEqual({
+    mode: "shared",
+    ownerType: "team",
+    ownerId: "team_alpha",
+    managedBy: "broker",
+  });
+
+  const serialized = alphaView ? serializeProjectView(alphaView) : null;
+  expect(serialized?.ownership).toEqual({
+    mode: "shared",
+    owner_type: "team",
+    owner_id: "team_alpha",
+    managed_by: "broker",
+  });
+});
+
 test("buildProjectViews includes lifecycle and startup summaries", async () => {
   const lifecycleConfig = JSON.stringify(
     {
diff --git a/tests/runtime-cache.test.ts b/tests/runtime-cache.test.ts
index 97cc72ccf..fe2c96196 100644
--- a/tests/runtime-cache.test.ts
+++ b/tests/runtime-cache.test.ts
@@ -144,6 +144,7 @@ test("getProjectsPayload keeps working when resolveProjectMeta fails for one pro
     devHost: null,
     repoRoot: null,
     projectDir: null,
+    ownership: null,
     definedServices: null,
     extensionsEnabled: null,
     features: null,
@@ -168,6 +169,12 @@ test("getProjectsPayload keeps working when resolveProjectMeta fails for one pro
           throw new Error("boom");
         }
         const meta: ProjectMeta = {
+          ownership: {
+            mode: "local",
+            ownerType: "user",
+            ownerId: null,
+            managedBy: "local",
+          },
           git: {
             isRepo: false,
             head: null,
@@ -217,6 +224,12 @@ test("getProjectsPayload keeps working when resolveProjectMeta fails for one pro
         worktrees: null,
         error: null,
       },
+      ownership: {
+        mode: "local",
+        ownerType: "user",
+        ownerId: null,
+        managedBy: "local",
+      },
       hackBranches: { path: "", parseError: null, branches: [] },
       env: {
         contractPath: "",

From 63b832ae8ec069e5bd505b322dbc6e44fb30d6e2 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:15:24 +0000
Subject: [PATCH 040/134] feat: add linear project artifact workflows

---
 .../extensions/linear/commands.ts             | 1067 +++++++++++++++++
 .../extensions/linear/project-artifacts.ts    |  232 +++-
 tests/linear-commands.test.ts                 |  358 +++++-
 3 files changed, 1654 insertions(+), 3 deletions(-)

diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index 8be46f78d..4dcd7bb39 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -1,5 +1,7 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { mkdir, rm } from "node:fs/promises";
 import { hostname } from "node:os";
+import { dirname } from "node:path";
 
 import { secrets } from "bun";
 
@@ -34,10 +36,24 @@ import {
   createLinearClient,
   type LinearComment,
   type LinearIssue,
+  type LinearProjectDocument,
+  type LinearProjectMilestone,
+  type LinearProjectUpdate,
   type LinearUser,
   type LinearWorkflowState,
   type LinearWorkflowStateType,
 } from "./client.ts";
+import {
+  type LinearProjectArtifactFamily,
+  type LinearProjectArtifactSnapshot,
+  type LocalLinearProjectArtifact,
+  loadLocalLinearProjectArtifacts,
+  materializeLocalLinearProjectArtifact,
+  planLinearProjectArtifactChanges,
+  resolveLinearProjectArtifactPath,
+  serializeLinearProjectArtifactFile,
+  slugifyLinearProjectArtifactTitle,
+} from "./project-artifacts.ts";
 
 const EXTENSION_ID = "dance.hack.linear";
 const DEFAULT_OAUTH_AUTHORIZE_URL = "https://linear.app/oauth/authorize";
@@ -57,6 +73,7 @@ const OAUTH_TIMEOUT_MS = 5 * 60 * 1000;
 const OAUTH_POLL_INTERVAL_MS = 1000;
 const DEFAULT_PROJECT_SYNC_LIMIT = 100;
 const DEFAULT_DELIVERY_LIST_LIMIT = 50;
+const MARKDOWN_HEADING_PREFIX_REGEX = /^#+\s*/;
 const TRAILING_SLASH_REGEX = /\/+$/;
 
 export const LINEAR_COMMANDS: readonly ExtensionCommand[] = [
@@ -1135,6 +1152,45 @@ export const LINEAR_COMMANDS: readonly ExtensionCommand[] = [
       return removed ? 0 : 1;
     },
   },
+  {
+    name: "documents",
+    summary:
+      "List, pull, plan, and apply Hack-managed Linear project documents",
+    scope: "project",
+    allowWhenDisabled: true,
+    handler: async ({ ctx, args }) =>
+      await handleProjectArtifactFamilyCommand({
+        ctx,
+        args,
+        family: "documents",
+      }),
+  },
+  {
+    name: "milestones",
+    summary:
+      "List, pull, plan, and apply Hack-managed Linear project milestones",
+    scope: "project",
+    allowWhenDisabled: true,
+    handler: async ({ ctx, args }) =>
+      await handleProjectArtifactFamilyCommand({
+        ctx,
+        args,
+        family: "milestones",
+      }),
+  },
+  {
+    name: "status-updates",
+    summary:
+      "List, pull, plan, and publish Hack-managed Linear project status updates",
+    scope: "project",
+    allowWhenDisabled: true,
+    handler: async ({ ctx, args }) =>
+      await handleProjectArtifactFamilyCommand({
+        ctx,
+        args,
+        family: "status-updates",
+      }),
+  },
   {
     name: "sync-issue",
     summary:
@@ -2450,17 +2506,44 @@ type LinearSyncClient = Pick<
   ReturnType<typeof createLinearClient>,
   | "createComment"
   | "createIssue"
+  | "createProjectDocument"
+  | "createProjectMilestone"
+  | "createProjectUpdate"
   | "getIssueById"
   | "getIssueByIdentifier"
   | "getProject"
   | "listIssueComments"
+  | "listProjectDocuments"
   | "listProjectIssuesPage"
+  | "listProjectMilestones"
+  | "listProjectUpdates"
   | "listTeamLabels"
   | "listTeamStates"
   | "listTeamUsers"
+  | "updateProjectDocument"
+  | "updateProjectMilestone"
   | "updateIssue"
 >;
 
+type ProjectArtifactLinearClient = Pick<
+  ReturnType<typeof createLinearClient>,
+  | "createProjectDocument"
+  | "createProjectMilestone"
+  | "createProjectUpdate"
+  | "listProjectDocuments"
+  | "listProjectMilestones"
+  | "listProjectUpdates"
+  | "updateProjectDocument"
+  | "updateProjectMilestone"
+>;
+
+type ProjectArtifactRuntime = {
+  readonly linear: ProjectArtifactLinearClient;
+  readonly profileId: string;
+  readonly projectDir: string;
+  readonly projectId: string;
+};
+
 type SyncRuntime = {
   readonly tickets: TicketSyncStore;
   readonly linear: LinearSyncClient;
@@ -2692,6 +2775,989 @@ async function createSyncRuntime(input: {
   };
 }
 
+type ProjectArtifactCommandPayload = {
+  readonly artifacts?: readonly LinearProjectArtifactSnapshot[];
+  readonly changed?: number;
+  readonly errors?: readonly string[];
+  readonly family: LinearProjectArtifactFamily;
+  readonly movedPaths?: readonly {
+    readonly from: string;
+    readonly to: string;
+  }[];
+  readonly operation: "apply" | "list" | "plan" | "publish" | "pull";
+  readonly profileId: string;
+  readonly projectId: string;
+  readonly summary?: Record<string, number>;
+  readonly writtenPaths?: readonly string[];
+};
+
+async function handleProjectArtifactFamilyCommand(input: {
+  readonly ctx: ExtensionCommandContext;
+  readonly args: readonly string[];
+  readonly family: LinearProjectArtifactFamily;
+}): Promise<number> {
+  if (!input.ctx.project) {
+    input.ctx.logger.error({ message: "No project found. Run inside a repo." });
+    return 1;
+  }
+
+  const parsed = parseProjectArtifactFamilyArgs({
+    family: input.family,
+    args: input.args,
+  });
+  if (!parsed.ok) {
+    input.ctx.logger.error({ message: parsed.error });
+    return 1;
+  }
+
+  const binding = resolveProjectLinearBinding({
+    controlPlaneConfig: input.ctx.controlPlaneConfig,
+  });
+  const selectedTarget =
+    (parsed.value.projectId
+      ? findProjectBindingTarget({
+          binding,
+          projectId: parsed.value.projectId,
+        })
+      : null) ??
+    (binding.projectId
+      ? {
+          projectId: binding.projectId,
+          ...(binding.projectName ? { projectName: binding.projectName } : {}),
+          ...(binding.teamId ? { teamId: binding.teamId } : {}),
+          ...(binding.profileId ? { profileId: binding.profileId } : {}),
+        }
+      : null);
+  const projectId = parsed.value.projectId ?? selectedTarget?.projectId;
+  if (!projectId) {
+    input.ctx.logger.error({
+      message:
+        "Missing project id. Pass --project-id, bind a default project, or add additional linked projects first.",
+    });
+    return 1;
+  }
+
+  const runtime = await createSyncRuntime({
+    ctx: input.ctx,
+    profileId: parsed.value.profileId ?? selectedTarget?.profileId,
+  });
+  if (!runtime.ok) {
+    input.ctx.logger.error({ message: runtime.error });
+    return 1;
+  }
+
+  const result = await runProjectArtifactCommand({
+    family: input.family,
+    verb: parsed.value.verb,
+    path: parsed.value.path,
+    runtime: {
+      linear: runtime.value.linear,
+      profileId: runtime.value.profileId,
+      projectDir: input.ctx.project.projectDir,
+      projectId,
+    },
+  });
+  if (!result.ok) {
+    input.ctx.logger.error({ message: result.error });
+    return 1;
+  }
+
+  if (parsed.value.json) {
+    process.stdout.write(`${JSON.stringify(result.payload, null, 2)}\n`);
+    return 0;
+  }
+
+  await renderProjectArtifactCommandPayload({
+    payload: result.payload,
+  });
+  return 0;
+}
+
+function parseProjectArtifactFamilyArgs(input: {
+  readonly family: LinearProjectArtifactFamily;
+  readonly args: readonly string[];
+}):
+  | {
+      readonly ok: true;
+      readonly value:
+        | ProjectDocumentsArgs
+        | ProjectMilestonesArgs
+        | ProjectStatusUpdatesArgs;
+    }
+  | { readonly ok: false; readonly error: string } {
+  if (input.family === "documents") {
+    return parseProjectDocumentsArgs({ args: input.args });
+  }
+  if (input.family === "milestones") {
+    return parseProjectMilestonesArgs({ args: input.args });
+  }
+  return parseProjectStatusUpdatesArgs({ args: input.args });
+}
+
+async function runProjectArtifactCommand(input: {
+  readonly family: LinearProjectArtifactFamily;
+  readonly verb:
+    | ProjectDocumentsVerb
+    | ProjectMilestonesVerb
+    | ProjectStatusUpdatesVerb;
+  readonly runtime: ProjectArtifactRuntime;
+  readonly path?: string;
+}): Promise<
+  | { readonly ok: true; readonly payload: ProjectArtifactCommandPayload }
+  | { readonly ok: false; readonly error: string }
+> {
+  try {
+    if (input.verb === "archive") {
+      return {
+        ok: false,
+        error:
+          "Archive is not implemented yet for managed Linear project artifacts.",
+      };
+    }
+
+    if (input.verb === "list") {
+      const artifacts = await listRemoteProjectArtifacts({
+        family: input.family,
+        runtime: input.runtime,
+      });
+      if (!artifacts.ok) {
+        return artifacts;
+      }
+      return {
+        ok: true,
+        payload: {
+          operation: "list",
+          family: input.family,
+          profileId: input.runtime.profileId,
+          projectId: input.runtime.projectId,
+          artifacts: artifacts.data,
+        },
+      };
+    }
+
+    if (input.verb === "pull") {
+      const artifacts = await listRemoteProjectArtifacts({
+        family: input.family,
+        runtime: input.runtime,
+      });
+      if (!artifacts.ok) {
+        return artifacts;
+      }
+
+      let changed = 0;
+      const writtenPaths: string[] = [];
+      for (const artifact of artifacts.data) {
+        const localArtifact = materializeLocalLinearProjectArtifact({
+          projectDir: input.runtime.projectDir,
+          artifact,
+          ...(input.family === "status-updates"
+            ? { statusUpdateState: "published" as const }
+            : {}),
+        });
+        const wrote = await writeLocalLinearProjectArtifact({
+          artifact: localArtifact,
+        });
+        if (!wrote) {
+          continue;
+        }
+        changed += 1;
+        writtenPaths.push(localArtifact.path);
+      }
+
+      return {
+        ok: true,
+        payload: {
+          operation: "pull",
+          family: input.family,
+          profileId: input.runtime.profileId,
+          projectId: input.runtime.projectId,
+          changed,
+          writtenPaths,
+        },
+      };
+    }
+
+    if (input.verb === "plan") {
+      const remoteArtifacts = await listRemoteProjectArtifacts({
+        family: input.family,
+        runtime: input.runtime,
+      });
+      if (!remoteArtifacts.ok) {
+        return remoteArtifacts;
+      }
+      const localArtifacts = await loadManagedProjectArtifacts({
+        family: input.family,
+        runtime: input.runtime,
+        path: input.path,
+      });
+      if (!localArtifacts.ok) {
+        return localArtifacts;
+      }
+
+      const plan = planLinearProjectArtifactChanges({
+        localArtifacts: localArtifacts.data,
+        remoteArtifacts: remoteArtifacts.data,
+      });
+      return {
+        ok: true,
+        payload: {
+          operation: "plan",
+          family: input.family,
+          profileId: input.runtime.profileId,
+          projectId: input.runtime.projectId,
+          errors: plan.errors,
+          summary: {
+            create: plan.create.length,
+            update: plan.update.length,
+            noop: plan.noop.length,
+            remoteOnly: plan.remoteOnly.length,
+            errors: plan.errors.length,
+          },
+        },
+      };
+    }
+
+    if (input.verb === "apply") {
+      if (input.family === "status-updates") {
+        return {
+          ok: false,
+          error:
+            "Status updates are append-only. Use `hack linear status-updates publish` instead.",
+        };
+      }
+
+      const remoteArtifacts = await listRemoteProjectArtifacts({
+        family: input.family,
+        runtime: input.runtime,
+      });
+      if (!remoteArtifacts.ok) {
+        return remoteArtifacts;
+      }
+      const localArtifacts = await loadManagedProjectArtifacts({
+        family: input.family,
+        runtime: input.runtime,
+        path: input.path,
+      });
+      if (!localArtifacts.ok) {
+        return localArtifacts;
+      }
+
+      const plan = planLinearProjectArtifactChanges({
+        localArtifacts: localArtifacts.data,
+        remoteArtifacts: remoteArtifacts.data,
+      });
+      if (plan.errors.length > 0) {
+        return {
+          ok: false,
+          error: plan.errors.join("\n"),
+        };
+      }
+
+      const writtenPaths: string[] = [];
+      for (const artifact of plan.create) {
+        const saved = await applyManagedProjectArtifactCreate({
+          family: input.family,
+          runtime: input.runtime,
+          artifact,
+        });
+        if (!saved.ok) {
+          return saved;
+        }
+        const wrote = await writeLocalLinearProjectArtifact({
+          artifact: {
+            ...saved.data,
+            path: artifact.path,
+          },
+        });
+        if (wrote) {
+          writtenPaths.push(artifact.path);
+        }
+      }
+
+      for (const entry of plan.update) {
+        const saved = await applyManagedProjectArtifactUpdate({
+          family: input.family,
+          runtime: input.runtime,
+          artifact: entry.local,
+        });
+        if (!saved.ok) {
+          return saved;
+        }
+        const wrote = await writeLocalLinearProjectArtifact({
+          artifact: {
+            ...saved.data,
+            path: entry.local.path,
+          },
+        });
+        if (wrote) {
+          writtenPaths.push(entry.local.path);
+        }
+      }
+
+      return {
+        ok: true,
+        payload: {
+          operation: "apply",
+          family: input.family,
+          profileId: input.runtime.profileId,
+          projectId: input.runtime.projectId,
+          writtenPaths,
+          summary: {
+            created: plan.create.length,
+            updated: plan.update.length,
+            noop: plan.noop.length,
+            remoteOnly: plan.remoteOnly.length,
+            errors: 0,
+          },
+        },
+      };
+    }
+
+    if (input.family !== "status-updates") {
+      return {
+        ok: false,
+        error: `Invalid ${input.family} verb: ${input.verb}.`,
+      };
+    }
+
+    const localArtifacts = await loadManagedProjectArtifacts({
+      family: input.family,
+      runtime: input.runtime,
+      path: input.path,
+    });
+    if (!localArtifacts.ok) {
+      return localArtifacts;
+    }
+
+    const drafts = localArtifacts.data.filter(
+      (artifact) =>
+        artifact.kind === "linear-project-status-update" &&
+        isDraftStatusUpdatePath({ path: artifact.path }) &&
+        !artifact.linearId
+    );
+
+    const movedPaths: Array<{ from: string; to: string }> = [];
+    for (const artifact of drafts) {
+      const published = await publishManagedProjectStatusUpdate({
+        runtime: input.runtime,
+        artifact,
+      });
+      if (!published.ok) {
+        return published;
+      }
+      movedPaths.push({
+        from: artifact.path,
+        to: published.data.path,
+      });
+    }
+
+    return {
+      ok: true,
+      payload: {
+        operation: "publish",
+        family: input.family,
+        profileId: input.runtime.profileId,
+        projectId: input.runtime.projectId,
+        movedPaths,
+        summary: {
+          published: movedPaths.length,
+        },
+      },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+async function listRemoteProjectArtifacts(input: {
+  readonly family: LinearProjectArtifactFamily;
+  readonly runtime: ProjectArtifactRuntime;
+}): Promise<
+  | {
+      readonly ok: true;
+      readonly data: readonly LinearProjectArtifactSnapshot[];
+    }
+  | { readonly ok: false; readonly error: string }
+> {
+  if (input.family === "documents") {
+    const documents = await input.runtime.linear.listProjectDocuments({
+      projectId: input.runtime.projectId,
+    });
+    if (!documents.ok) {
+      return {
+        ok: false,
+        error: documents.error,
+      };
+    }
+    return {
+      ok: true,
+      data: documents.data.map((document) =>
+        projectDocumentToArtifactSnapshot({
+          document,
+          projectId: input.runtime.projectId,
+        })
+      ),
+    };
+  }
+
+  if (input.family === "milestones") {
+    const milestones = await input.runtime.linear.listProjectMilestones({
+      projectId: input.runtime.projectId,
+    });
+    if (!milestones.ok) {
+      return {
+        ok: false,
+        error: milestones.error,
+      };
+    }
+    return {
+      ok: true,
+      data: milestones.data.map((milestone) =>
+        projectMilestoneToArtifactSnapshot({
+          milestone,
+          projectId: input.runtime.projectId,
+        })
+      ),
+    };
+  }
+
+  const updates = await input.runtime.linear.listProjectUpdates({
+    projectId: input.runtime.projectId,
+  });
+  if (!updates.ok) {
+    return {
+      ok: false,
+      error: updates.error,
+    };
+  }
+  return {
+    ok: true,
+    data: updates.data.map((update) =>
+      projectUpdateToArtifactSnapshot({
+        update,
+        projectId: input.runtime.projectId,
+      })
+    ),
+  };
+}
+
+async function loadManagedProjectArtifacts(input: {
+  readonly family: LinearProjectArtifactFamily;
+  readonly runtime: ProjectArtifactRuntime;
+  readonly path?: string;
+}): Promise<
+  | { readonly ok: true; readonly data: readonly LocalLinearProjectArtifact[] }
+  | { readonly ok: false; readonly error: string }
+> {
+  try {
+    return {
+      ok: true,
+      data: await loadLocalLinearProjectArtifacts({
+        family: input.family,
+        linearProjectId: input.runtime.projectId,
+        path: input.path,
+        projectDir: input.runtime.projectDir,
+      }),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+async function applyManagedProjectArtifactCreate(input: {
+  readonly family: "documents" | "milestones";
+  readonly runtime: ProjectArtifactRuntime;
+  readonly artifact: LocalLinearProjectArtifact;
+}): Promise<
+  | { readonly ok: true; readonly data: LinearProjectArtifactSnapshot }
+  | { readonly ok: false; readonly error: string }
+> {
+  if (input.family === "documents") {
+    if (input.artifact.kind !== "linear-project-document") {
+      return {
+        ok: false,
+        error: `Expected a document artifact at ${input.artifact.path}.`,
+      };
+    }
+    const created = await input.runtime.linear.createProjectDocument({
+      projectId: input.runtime.projectId,
+      title: input.artifact.title,
+      ...(input.artifact.body ? { content: input.artifact.body } : {}),
+      ...(input.artifact.icon ? { icon: input.artifact.icon } : {}),
+      ...(input.artifact.sortOrder !== undefined
+        ? { sortOrder: input.artifact.sortOrder }
+        : {}),
+    });
+    if (!created.ok) {
+      return {
+        ok: false,
+        error: created.error,
+      };
+    }
+    return {
+      ok: true,
+      data: projectDocumentToArtifactSnapshot({
+        document: created.data,
+        projectId: input.runtime.projectId,
+      }),
+    };
+  }
+
+  if (input.artifact.kind !== "linear-project-milestone") {
+    return {
+      ok: false,
+      error: `Expected a milestone artifact at ${input.artifact.path}.`,
+    };
+  }
+  const created = await input.runtime.linear.createProjectMilestone({
+    projectId: input.runtime.projectId,
+    title: input.artifact.title,
+    ...(input.artifact.body ? { description: input.artifact.body } : {}),
+    ...(input.artifact.targetDate
+      ? { targetDate: input.artifact.targetDate }
+      : {}),
+    ...(input.artifact.sortOrder !== undefined
+      ? { sortOrder: input.artifact.sortOrder }
+      : {}),
+  });
+  if (!created.ok) {
+    return {
+      ok: false,
+      error: created.error,
+    };
+  }
+  return {
+    ok: true,
+    data: projectMilestoneToArtifactSnapshot({
+      milestone: created.data,
+      projectId: input.runtime.projectId,
+    }),
+  };
+}
+
+async function applyManagedProjectArtifactUpdate(input: {
+  readonly family: "documents" | "milestones";
+  readonly runtime: ProjectArtifactRuntime;
+  readonly artifact: LocalLinearProjectArtifact;
+}): Promise<
+  | { readonly ok: true; readonly data: LinearProjectArtifactSnapshot }
+  | { readonly ok: false; readonly error: string }
+> {
+  if (input.family === "documents") {
+    if (
+      input.artifact.kind !== "linear-project-document" ||
+      !input.artifact.linearId
+    ) {
+      return {
+        ok: false,
+        error: `Expected a managed document with linearId at ${input.artifact.path}.`,
+      };
+    }
+    const updated = await input.runtime.linear.updateProjectDocument({
+      documentId: input.artifact.linearId,
+      title: input.artifact.title,
+      ...(input.artifact.body ? { content: input.artifact.body } : {}),
+      ...(input.artifact.icon ? { icon: input.artifact.icon } : {}),
+      ...(input.artifact.sortOrder !== undefined
+        ? { sortOrder: input.artifact.sortOrder }
+        : {}),
+    });
+    if (!updated.ok) {
+      return {
+        ok: false,
+        error: updated.error,
+      };
+    }
+    return {
+      ok: true,
+      data: projectDocumentToArtifactSnapshot({
+        document: updated.data,
+        projectId: input.runtime.projectId,
+      }),
+    };
+  }
+
+  if (
+    input.artifact.kind !== "linear-project-milestone" ||
+    !input.artifact.linearId
+  ) {
+    return {
+      ok: false,
+      error: `Expected a managed milestone with linearId at ${input.artifact.path}.`,
+    };
+  }
+  const updated = await input.runtime.linear.updateProjectMilestone({
+    milestoneId: input.artifact.linearId,
+    title: input.artifact.title,
+    ...(input.artifact.body ? { description: input.artifact.body } : {}),
+    ...(input.artifact.targetDate
+      ? { targetDate: input.artifact.targetDate }
+      : {}),
+    ...(input.artifact.sortOrder !== undefined
+      ? { sortOrder: input.artifact.sortOrder }
+      : {}),
+    ...(input.artifact.state ? { status: input.artifact.state } : {}),
+  });
+  if (!updated.ok) {
+    return {
+      ok: false,
+      error: updated.error,
+    };
+  }
+  return {
+    ok: true,
+    data: projectMilestoneToArtifactSnapshot({
+      milestone: updated.data,
+      projectId: input.runtime.projectId,
+    }),
+  };
+}
+
+async function publishManagedProjectStatusUpdate(input: {
+  readonly runtime: ProjectArtifactRuntime;
+  readonly artifact: Extract<
+    LocalLinearProjectArtifact,
+    { readonly kind: "linear-project-status-update" }
+  >;
+}): Promise<
+  | {
+      readonly ok: true;
+      readonly data: Extract<
+        LocalLinearProjectArtifact,
+        { readonly kind: "linear-project-status-update" }
+      >;
+    }
+  | { readonly ok: false; readonly error: string }
+> {
+  const created = await input.runtime.linear.createProjectUpdate({
+    projectId: input.runtime.projectId,
+    body: input.artifact.body,
+    ...(input.artifact.health ? { health: input.artifact.health } : {}),
+  });
+  if (!created.ok) {
+    return {
+      ok: false,
+      error: created.error,
+    };
+  }
+
+  const nextArtifact = {
+    ...projectUpdateToArtifactSnapshot({
+      update: created.data,
+      projectId: input.runtime.projectId,
+      fallbackDate: input.artifact.date,
+      fallbackSlug: input.artifact.slug,
+      fallbackTitle: input.artifact.title,
+    }),
+    path: resolveLinearProjectArtifactPath({
+      projectDir: input.runtime.projectDir,
+      artifact: {
+        ...projectUpdateToArtifactSnapshot({
+          update: created.data,
+          projectId: input.runtime.projectId,
+          fallbackDate: input.artifact.date,
+          fallbackSlug: input.artifact.slug,
+          fallbackTitle: input.artifact.title,
+        }),
+      },
+      statusUpdateState: "published",
+    }),
+  } satisfies Extract<
+    LocalLinearProjectArtifact,
+    { readonly kind: "linear-project-status-update" }
+  >;
+
+  await writeLocalLinearProjectArtifact({
+    artifact: nextArtifact,
+  });
+  if (input.artifact.path !== nextArtifact.path) {
+    await removeFileIfExists({
+      path: input.artifact.path,
+    });
+  }
+
+  return {
+    ok: true,
+    data: nextArtifact,
+  };
+}
+
+function projectDocumentToArtifactSnapshot(input: {
+  readonly document: LinearProjectDocument;
+  readonly projectId: string;
+}): Extract<
+  LinearProjectArtifactSnapshot,
+  { readonly kind: "linear-project-document" }
+> {
+  return {
+    kind: "linear-project-document",
+    linearProjectId: input.document.projectId ?? input.projectId,
+    title: input.document.title,
+    linearId: input.document.id,
+    ...(input.document.slugId ? { slug: input.document.slugId } : {}),
+    archived: input.document.archived,
+    ...(input.document.updatedAt
+      ? { updatedAt: input.document.updatedAt }
+      : {}),
+    body: input.document.content ?? "",
+    ...(input.document.sortOrder !== undefined
+      ? { sortOrder: input.document.sortOrder }
+      : {}),
+    ...(input.document.icon ? { icon: input.document.icon } : {}),
+  };
+}
+
+function projectMilestoneToArtifactSnapshot(input: {
+  readonly milestone: LinearProjectMilestone;
+  readonly projectId: string;
+}): Extract<
+  LinearProjectArtifactSnapshot,
+  { readonly kind: "linear-project-milestone" }
+> {
+  return {
+    kind: "linear-project-milestone",
+    linearProjectId: input.milestone.projectId ?? input.projectId,
+    title: input.milestone.title,
+    linearId: input.milestone.id,
+    slug: slugifyLinearProjectArtifactTitle({
+      title: input.milestone.title,
+    }),
+    archived: input.milestone.archived,
+    ...(input.milestone.updatedAt
+      ? { updatedAt: input.milestone.updatedAt }
+      : {}),
+    body: input.milestone.description ?? "",
+    ...(input.milestone.targetDate
+      ? { targetDate: input.milestone.targetDate }
+      : {}),
+    ...(input.milestone.status ? { state: input.milestone.status } : {}),
+    ...(input.milestone.sortOrder !== undefined
+      ? { sortOrder: input.milestone.sortOrder }
+      : {}),
+  };
+}
+
+function projectUpdateToArtifactSnapshot(input: {
+  readonly update: LinearProjectUpdate;
+  readonly projectId: string;
+  readonly fallbackDate?: string;
+  readonly fallbackSlug?: string;
+  readonly fallbackTitle?: string;
+}): Extract<
+  LinearProjectArtifactSnapshot,
+  { readonly kind: "linear-project-status-update" }
+> {
+  const date =
+    input.fallbackDate ?? input.update.createdAt.slice(0, 10) ?? undefined;
+  const title =
+    input.fallbackTitle ??
+    readProjectUpdateHeading({ body: input.update.body }) ??
+    humanizeArtifactSlug({
+      slug: input.fallbackSlug ?? input.update.slugId,
+    }) ??
+    (date ? `Status update ${date}` : "Status update");
+  const slug =
+    input.fallbackSlug ??
+    input.update.slugId ??
+    slugifyLinearProjectArtifactTitle({
+      title,
+    });
+
+  return {
+    kind: "linear-project-status-update",
+    linearProjectId: input.update.projectId ?? input.projectId,
+    title,
+    linearId: input.update.id,
+    slug,
+    archived: false,
+    ...(input.update.updatedAt ? { updatedAt: input.update.updatedAt } : {}),
+    body: input.update.body,
+    ...(date ? { date } : {}),
+    ...(input.update.health ? { health: input.update.health } : {}),
+  };
+}
+
+function readProjectUpdateHeading(input: {
+  readonly body: string;
+}): string | null {
+  for (const line of input.body.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    if (trimmed.startsWith("#")) {
+      const heading = trimmed.replace(MARKDOWN_HEADING_PREFIX_REGEX, "").trim();
+      return heading || null;
+    }
+    break;
+  }
+  return null;
+}
+
+function humanizeArtifactSlug(input: {
+  readonly slug?: string;
+}): string | null {
+  const slug = input.slug?.trim();
+  if (!slug) {
+    return null;
+  }
+  return slug
+    .split(/[-_]+/g)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+async function writeLocalLinearProjectArtifact(input: {
+  readonly artifact: LocalLinearProjectArtifact;
+}): Promise<boolean> {
+  const text = serializeLinearProjectArtifactFile({
+    artifact: input.artifact,
+  });
+  const existing = await readFileIfExists({
+    path: input.artifact.path,
+  });
+  if (existing === text) {
+    return false;
+  }
+  await mkdir(dirname(input.artifact.path), { recursive: true });
+  await Bun.write(input.artifact.path, text);
+  return true;
+}
+
+async function readFileIfExists(input: {
+  readonly path: string;
+}): Promise<string | null> {
+  const file = Bun.file(input.path);
+  if (!(await file.exists())) {
+    return null;
+  }
+  return await file.text();
+}
+
+async function removeFileIfExists(input: {
+  readonly path: string;
+}): Promise<void> {
+  await rm(input.path, { force: true });
+}
+
+function isDraftStatusUpdatePath(input: { readonly path: string }): boolean {
+  return input.path.replaceAll("\\", "/").includes("/status-updates/drafts/");
+}
+
+async function renderProjectArtifactCommandPayload(input: {
+  readonly payload: ProjectArtifactCommandPayload;
+}): Promise<void> {
+  const title = `Linear ${input.payload.family}`;
+  if (input.payload.operation === "list") {
+    const artifacts = input.payload.artifacts ?? [];
+    await display.kv({
+      title,
+      entries: [
+        ["profile", input.payload.profileId],
+        ["project_id", input.payload.projectId],
+        ["count", String(artifacts.length)],
+      ],
+    });
+    if (artifacts.length === 0) {
+      return;
+    }
+    await display.table({
+      columns: listProjectArtifactColumns({
+        family: input.payload.family,
+      }),
+      rows: artifacts.map((artifact) =>
+        listProjectArtifactRow({
+          artifact,
+        })
+      ),
+    });
+    return;
+  }
+
+  if (input.payload.operation === "pull") {
+    await display.kv({
+      title: `${title} pulled`,
+      entries: [
+        ["profile", input.payload.profileId],
+        ["project_id", input.payload.projectId],
+        ["changed", String(input.payload.changed ?? 0)],
+        ["written", String(input.payload.writtenPaths?.length ?? 0)],
+      ],
+    });
+    return;
+  }
+
+  if (input.payload.operation === "publish") {
+    await display.kv({
+      title: `${title} published`,
+      entries: [
+        ["profile", input.payload.profileId],
+        ["project_id", input.payload.projectId],
+        ["published", String(input.payload.summary?.published ?? 0)],
+      ],
+    });
+    return;
+  }
+
+  await display.kv({
+    title: `${title} ${input.payload.operation}`,
+    entries: [
+      ["profile", input.payload.profileId],
+      ["project_id", input.payload.projectId],
+      ...Object.entries(input.payload.summary ?? {}).map(([key, value]) => [
+        key,
+        String(value),
+      ]),
+    ],
+  });
+}
+
+function listProjectArtifactColumns(input: {
+  readonly family: LinearProjectArtifactFamily;
+}): string[] {
+  if (input.family === "documents") {
+    return ["Document ID", "Title", "Slug", "Updated At"];
+  }
+  if (input.family === "milestones") {
+    return ["Milestone ID", "Title", "Target Date", "State"];
+  }
+  return ["Update ID", "Title", "Date", "Health"];
+}
+
+function listProjectArtifactRow(input: {
+  readonly artifact: LinearProjectArtifactSnapshot;
+}): string[] {
+  if (input.artifact.kind === "linear-project-document") {
+    return [
+      input.artifact.linearId ?? "",
+      input.artifact.title,
+      input.artifact.slug ?? "",
+      input.artifact.updatedAt ?? "",
+    ];
+  }
+  if (input.artifact.kind === "linear-project-milestone") {
+    return [
+      input.artifact.linearId ?? "",
+      input.artifact.title,
+      input.artifact.targetDate ?? "",
+      input.artifact.state ?? "",
+    ];
+  }
+  return [
+    input.artifact.linearId ?? "",
+    input.artifact.title,
+    input.artifact.date ?? "",
+    input.artifact.health ?? "",
+  ];
+}
+
 function resolveSelectedLinearProfileId(input: {
   readonly controlPlaneConfig: ExtensionCommandContext["controlPlaneConfig"];
   readonly profileId?: string;
@@ -8450,6 +9516,7 @@ export const __testOnly = {
   parseProjectsArgs,
   parseRemoveAssigneeMappingArgs,
   parseRemoveAutosyncSubscriptionArgs,
+  runProjectArtifactCommand,
   resolveProjectLinearBinding,
   resolveProjectPullTargets,
   resolveOAuthBrokerRuntimeConfig,
diff --git a/src/control-plane/extensions/linear/project-artifacts.ts b/src/control-plane/extensions/linear/project-artifacts.ts
index 3e5f0217b..672a381f2 100644
--- a/src/control-plane/extensions/linear/project-artifacts.ts
+++ b/src/control-plane/extensions/linear/project-artifacts.ts
@@ -1,4 +1,5 @@
-import { join } from "node:path";
+import { readdir, stat } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
 import { YAML } from "bun";
 
 import { isRecord } from "../../../lib/guards.ts";
@@ -8,6 +9,13 @@ export type LinearProjectArtifactKind =
   | "linear-project-milestone"
   | "linear-project-status-update";
 
+export type LinearProjectArtifactFamily =
+  | "documents"
+  | "milestones"
+  | "status-updates";
+
+export type LinearProjectStatusUpdateState = "draft" | "published";
+
 type LinearProjectArtifactBase = {
   readonly kind: LinearProjectArtifactKind;
   readonly linearProjectId: string;
@@ -67,6 +75,21 @@ export const resolveLinearProjectArtifactsRoot = ({
   readonly linearProjectId: string;
 }): string => join(projectDir, ".hack/linear/projects", linearProjectId);
 
+/** Resolve the canonical directory for a specific Linear project artifact family. */
+export const resolveLinearProjectArtifactsFamilyRoot = ({
+  projectDir,
+  linearProjectId,
+  family,
+}: {
+  readonly projectDir: string;
+  readonly linearProjectId: string;
+  readonly family: LinearProjectArtifactFamily;
+}): string =>
+  join(
+    resolveLinearProjectArtifactsRoot({ projectDir, linearProjectId }),
+    family
+  );
+
 /** Parse a repo-managed Markdown artifact into a normalized record for planning and sync. */
 export const parseLinearProjectArtifactFile = ({
   filePath,
@@ -228,6 +251,126 @@ export const planLinearProjectArtifactChanges = ({
   };
 };
 
+/** Load repo-managed Linear project artifacts from a file or directory target. */
+export const loadLocalLinearProjectArtifacts = async ({
+  projectDir,
+  linearProjectId,
+  family,
+  path,
+}: {
+  readonly projectDir: string;
+  readonly linearProjectId: string;
+  readonly family: LinearProjectArtifactFamily;
+  readonly path?: string;
+}): Promise<readonly LocalLinearProjectArtifact[]> => {
+  const targetPath =
+    resolveArtifactInputPath({
+      projectDir,
+      linearProjectId,
+      family,
+      path,
+    }) ??
+    resolveLinearProjectArtifactsFamilyRoot({
+      projectDir,
+      linearProjectId,
+      family,
+    });
+
+  const targetStat = await safeStat(targetPath);
+  if (!targetStat) {
+    return [];
+  }
+
+  const markdownPaths = targetStat.isFile()
+    ? [targetPath]
+    : await collectMarkdownFiles(targetPath);
+  const loaded: LocalLinearProjectArtifact[] = [];
+
+  for (const filePath of markdownPaths.sort((left, right) =>
+    left.localeCompare(right)
+  )) {
+    const text = await Bun.file(filePath).text();
+    const artifact = parseLinearProjectArtifactFile({ filePath, text });
+    if (artifact.linearProjectId !== linearProjectId) {
+      continue;
+    }
+    if (resolveArtifactFamily({ kind: artifact.kind }) !== family) {
+      continue;
+    }
+    loaded.push(artifact);
+  }
+
+  return loaded;
+};
+
+/** Convert a snapshot into a local repo-managed artifact with a canonical file path. */
+export const materializeLocalLinearProjectArtifact = ({
+  projectDir,
+  artifact,
+  statusUpdateState,
+}: {
+  readonly projectDir: string;
+  readonly artifact: LinearProjectArtifactSnapshot;
+  readonly statusUpdateState?: LinearProjectStatusUpdateState;
+}): LocalLinearProjectArtifact => ({
+  ...artifact,
+  path: resolveLinearProjectArtifactPath({
+    projectDir,
+    artifact,
+    statusUpdateState,
+  }),
+});
+
+/** Resolve a canonical artifact file path for a local snapshot. */
+export const resolveLinearProjectArtifactPath = ({
+  projectDir,
+  artifact,
+  statusUpdateState,
+}: {
+  readonly projectDir: string;
+  readonly artifact: LinearProjectArtifactSnapshot;
+  readonly statusUpdateState?: LinearProjectStatusUpdateState;
+}): string => {
+  if (artifact.kind === "linear-project-status-update") {
+    const datePart =
+      artifact.date ?? artifact.updatedAt?.slice(0, 10) ?? "undated";
+    const slug = normalizeArtifactSlug({
+      slug: artifact.slug,
+      title: artifact.title,
+    });
+    const state = statusUpdateState ?? "published";
+    return join(
+      resolveLinearProjectArtifactsFamilyRoot({
+        projectDir,
+        linearProjectId: artifact.linearProjectId,
+        family: "status-updates",
+      }),
+      state === "draft" ? "drafts" : "published",
+      `${datePart}-${slug}.md`
+    );
+  }
+
+  const family = resolveArtifactFamily({ kind: artifact.kind });
+  return join(
+    resolveLinearProjectArtifactsFamilyRoot({
+      projectDir,
+      linearProjectId: artifact.linearProjectId,
+      family,
+    }),
+    `${normalizeArtifactSlug({
+      slug: artifact.slug,
+      title: artifact.title,
+    })}.md`
+  );
+};
+
+/** Normalize an artifact title into a stable repo filename slug. */
+export const slugifyLinearProjectArtifactTitle = ({
+  title,
+}: {
+  readonly title: string;
+}): string => normalizeArtifactSlug({ title });
+
 const parseKind = (
   value: unknown,
   filePath: string
@@ -242,6 +385,93 @@ const parseKind = (
   throw new Error(`Invalid or missing kind in ${filePath}`);
 };
 
+const resolveArtifactFamily = ({
+  kind,
+}: {
+  readonly kind: LinearProjectArtifactKind;
+}): LinearProjectArtifactFamily => {
+  if (kind === "linear-project-document") {
+    return "documents";
+  }
+  if (kind === "linear-project-milestone") {
+    return "milestones";
+  }
+  return "status-updates";
+};
+
+const normalizeArtifactSlug = ({
+  slug,
+  title,
+}: {
+  readonly slug?: string;
+  readonly title: string;
+}): string => {
+  const raw = (slug?.trim() || title.trim()).toLowerCase();
+  const normalized = raw
+    .replaceAll(/[^a-z0-9]+/g, "-")
+    .replaceAll(/^-+|-+$/g, "")
+    .replaceAll(/-{2,}/g, "-");
+  return normalized || "untitled";
+};
+
+const resolveArtifactInputPath = ({
+  projectDir,
+  linearProjectId,
+  family,
+  path,
+}: {
+  readonly projectDir: string;
+  readonly linearProjectId: string;
+  readonly family: LinearProjectArtifactFamily;
+  readonly path?: string;
+}): string | null => {
+  const candidate = path?.trim();
+  if (!candidate) {
+    return null;
+  }
+  if (isAbsolute(candidate)) {
+    return candidate;
+  }
+  if (candidate.startsWith(".hack/")) {
+    return resolve(projectDir, candidate);
+  }
+  return resolve(
+    resolveLinearProjectArtifactsFamilyRoot({
+      projectDir,
+      linearProjectId,
+      family,
+    }),
+    candidate
+  );
+};
+
+const safeStat = async (
+  path: string
+): Promise<Awaited<ReturnType<typeof stat>> | null> => {
+  try {
+    return await stat(path);
+  } catch {
+    return null;
+  }
+};
+
+const collectMarkdownFiles = async (root: string): Promise<string[]> => {
+  const entries = await readdir(root, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const absolutePath = join(root, entry.name);
+      if (entry.isDirectory()) {
+        return await collectMarkdownFiles(absolutePath);
+      }
+      if (entry.isFile() && absolutePath.endsWith(".md")) {
+        return [absolutePath];
+      }
+      return [];
+    })
+  );
+  return nested.flat();
+};
+
 const readRequiredString = ({
   value,
   key,
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index f6a3ff448..3f0519682 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -1,7 +1,26 @@
-import { expect, test } from "bun:test";
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
 
 import { resolveLinearToken } from "../src/control-plane/extensions/linear/auth.ts";
-import { __testOnly } from "../src/control-plane/extensions/linear/commands.ts";
+import {
+  __testOnly,
+  LINEAR_COMMANDS,
+} from "../src/control-plane/extensions/linear/commands.ts";
+
+let tempDir: string | null = null;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(resolve(tmpdir(), "hack-linear-artifacts-"));
+});
+
+afterEach(async () => {
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+  tempDir = null;
+});
 
 const minimalLinearBindingConfig = {
   routing: {
@@ -1553,3 +1572,338 @@ test("parseProjectDocumentsArgs rejects unsupported verbs", () => {
 
   expect(parsed.error).toContain("Expected list|pull|plan|apply|archive");
 });
+
+test("LINEAR_COMMANDS registers project artifact command families", () => {
+  const names = LINEAR_COMMANDS.map((command) => command.name);
+
+  expect(names).toContain("documents");
+  expect(names).toContain("milestones");
+  expect(names).toContain("status-updates");
+});
+
+test("runProjectArtifactCommand pulls project documents into repo state", async () => {
+  const projectDir = ensureTempDir();
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "documents",
+    verb: "pull",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectDocuments: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "doc_123",
+              title: "Launch plan",
+              content: "# Launch plan\n",
+              slugId: "launch-plan",
+              sortOrder: 1,
+              icon: "rocket",
+              archived: false,
+              updatedAt: "2026-03-14T10:00:00.000Z",
+            },
+          ],
+        }),
+      },
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(result.payload.changed).toBe(1);
+  expect(result.payload.writtenPaths).toEqual([
+    resolve(
+      projectDir,
+      ".hack/linear/projects/proj_123/documents/launch-plan.md"
+    ),
+  ]);
+
+  const file = await Bun.file(result.payload.writtenPaths[0] ?? "").text();
+  expect(file).toContain("kind: linear-project-document");
+  expect(file).toContain("linearId: doc_123");
+  expect(file).toContain("icon: rocket");
+});
+
+test("runProjectArtifactCommand plans create update noop and remote-only documents", async () => {
+  const projectDir = ensureTempDir();
+  const documentsDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/documents"
+  );
+  await mkdir(documentsDir, { recursive: true });
+  await writeFile(
+    resolve(documentsDir, "create-me.md"),
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: Create me
+slug: create-me
+archived: false
+---
+# Create me
+`
+  );
+  await writeFile(
+    resolve(documentsDir, "update-me.md"),
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: Update me
+linearId: doc_update
+slug: update-me
+archived: false
+---
+# Updated body
+`
+  );
+  await writeFile(
+    resolve(documentsDir, "noop-me.md"),
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: No-op me
+linearId: doc_noop
+slug: noop-me
+archived: false
+---
+# No changes
+`
+  );
+
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "documents",
+    verb: "plan",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectDocuments: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "doc_update",
+              title: "Update me",
+              content: "# Old body\n",
+              slugId: "update-me",
+              archived: false,
+            },
+            {
+              id: "doc_noop",
+              title: "No-op me",
+              content: "# No changes\n",
+              slugId: "noop-me",
+              archived: false,
+            },
+            {
+              id: "doc_remote",
+              title: "Remote only",
+              content: "# Remote only\n",
+              slugId: "remote-only",
+              archived: false,
+            },
+          ],
+        }),
+      },
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(result.payload.summary).toEqual({
+    create: 1,
+    update: 1,
+    noop: 1,
+    remoteOnly: 1,
+    errors: 0,
+  });
+});
+
+test("runProjectArtifactCommand applies document upserts and writes back linear ids", async () => {
+  const projectDir = ensureTempDir();
+  const documentsDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/documents"
+  );
+  await mkdir(documentsDir, { recursive: true });
+  await writeFile(
+    resolve(documentsDir, "create-me.md"),
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: Create me
+slug: create-me
+archived: false
+---
+# Create me
+`
+  );
+  await writeFile(
+    resolve(documentsDir, "update-me.md"),
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: Update me
+linearId: doc_update
+slug: update-me
+archived: false
+---
+# Updated body
+`
+  );
+
+  const createCalls: string[] = [];
+  const updateCalls: string[] = [];
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "documents",
+    verb: "apply",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectDocuments: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "doc_update",
+              title: "Update me",
+              content: "# Old body\n",
+              slugId: "update-me",
+              archived: false,
+            },
+          ],
+        }),
+        createProjectDocument: async ({ title }) => {
+          createCalls.push(title);
+          return {
+            ok: true as const,
+            data: {
+              id: "doc_create",
+              title,
+              content: "# Create me\n",
+              slugId: "create-me",
+              archived: false,
+              updatedAt: "2026-03-15T09:00:00.000Z",
+            },
+          };
+        },
+        updateProjectDocument: async ({ documentId, title }) => {
+          updateCalls.push(`${documentId}:${title ?? ""}`);
+          return {
+            ok: true as const,
+            data: {
+              id: documentId,
+              title: title ?? "Update me",
+              content: "# Updated body\n",
+              slugId: "update-me",
+              archived: false,
+              updatedAt: "2026-03-15T10:00:00.000Z",
+            },
+          };
+        },
+      },
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(createCalls).toEqual(["Create me"]);
+  expect(updateCalls).toEqual(["doc_update:Update me"]);
+  expect(result.payload.summary.created).toBe(1);
+  expect(result.payload.summary.updated).toBe(1);
+
+  const createdText = await Bun.file(
+    resolve(documentsDir, "create-me.md")
+  ).text();
+  expect(createdText).toContain("linearId: doc_create");
+  expect(createdText).toContain("updatedAt: 2026-03-15T09:00:00.000Z");
+});
+
+test("runProjectArtifactCommand publishes draft status updates and moves them to published", async () => {
+  const projectDir = ensureTempDir();
+  const draftsDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/status-updates/drafts"
+  );
+  await mkdir(draftsDir, { recursive: true });
+  await writeFile(
+    resolve(draftsDir, "2026-03-14-weekly.md"),
+    `---
+kind: linear-project-status-update
+linearProjectId: proj_123
+title: Weekly update
+slug: weekly
+archived: false
+date: 2026-03-14
+health: onTrack
+---
+Still on track for dogfooding.
+`
+  );
+
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "status-updates",
+    verb: "publish",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        createProjectUpdate: async ({ body, health }) => ({
+          ok: true as const,
+          data: {
+            id: "update_123",
+            body,
+            health,
+            slugId: "weekly",
+            createdAt: "2026-03-14T10:00:00.000Z",
+            updatedAt: "2026-03-14T10:15:00.000Z",
+            projectId: "proj_123",
+            projectName: "Dogfood",
+          },
+        }),
+      },
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(result.payload.summary.published).toBe(1);
+  expect(result.payload.movedPaths).toEqual([
+    {
+      from: resolve(draftsDir, "2026-03-14-weekly.md"),
+      to: resolve(
+        projectDir,
+        ".hack/linear/projects/proj_123/status-updates/published/2026-03-14-weekly.md"
+      ),
+    },
+  ]);
+
+  const publishedText = await Bun.file(
+    result.payload.movedPaths[0]?.to ?? ""
+  ).text();
+  expect(publishedText).toContain("linearId: update_123");
+  expect(publishedText).toContain("updatedAt: 2026-03-14T10:15:00.000Z");
+});
+
+function ensureTempDir(): string {
+  if (!tempDir) {
+    throw new Error("Missing temp dir");
+  }
+  return tempDir;
+}

From 474f1dd92c0bdddd446a7054de1f4e88c6889d52 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:15:29 +0000
Subject: [PATCH 041/134] docs(tickets): resolve projection design review

---
 docs/guides/tickets.md                        |  4 ++--
 ...3-14-hack-tickets-sqlite-journal-design.md | 24 ++++++++++++-------
 ...-03-14-hack-tickets-sqlite-journal-plan.md |  2 ++
 3 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/docs/guides/tickets.md b/docs/guides/tickets.md
index 00de5d9ab..b9594fed9 100644
--- a/docs/guides/tickets.md
+++ b/docs/guides/tickets.md
@@ -137,7 +137,7 @@ The adopted storage model keeps git portability as the primary constraint:
 - The JSONL journal remains the only portable source of truth.
 - A local SQLite projection under `.hack/tickets/state/` is the planned read model for fast queries and sync lookups.
 - The projection is disposable local state, not a second authority. If it is missing, stale, or corrupted, it should be rebuilt from the journal.
-- Replay is deterministic and idempotent by ordering events on `ts`, `orderKey`, and `eventId`, then deduplicating by `eventId`.
+- The projection design orders replay by `ts`, `orderKey`, and `eventId`. Until that lands, the current JSONL path still materializes directly from the journal and the normalizer continues to sort more simply by `ts` and `eventId`.
 
 Until the SQLite projection lands in code, reads still materialize from JSONL directly. The detailed projection design lives in [`docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md`](../plans/2026-03-14-hack-tickets-sqlite-journal-design.md).
 
@@ -145,9 +145,9 @@ Until the SQLite projection lands in code, reads still materialize from JSONL di
 
 In your project repo:
 
-- `.hack/tickets/events/events-YYYY-MM.jsonl` — event log segments (UTC month)
 - `.hack/tickets/git/bare.git` — a bare repo used to manage the tickets ref
 - `.hack/tickets/git/worktree` — a worktree used for reading/writing ticket data
+- `.hack/tickets/git/worktree/.hack/tickets/events/events-YYYY-MM.jsonl` — current event log segments (UTC month) inside the synced tickets worktree
 - `.hack/tickets/state/projection.sqlite` — planned local-only SQLite projection for indexed reads and replay state
 - `.hack/tickets/state/projection.sqlite-wal` / `.hack/tickets/state/projection.sqlite-shm` — planned SQLite companion files, safe to delete and rebuild
 
diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
index 4d1c961c0..2ea528898 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
@@ -11,7 +11,7 @@ Define a durable local storage architecture for Hack Tickets that keeps the git-
 
 ## Current Foundation
 
-- Ticket history is stored as append-only monthly JSONL segments in `.hack/tickets/events/events-YYYY-MM.jsonl`.
+- Ticket history is stored as append-only monthly JSONL segments in `.hack/tickets/git/worktree/.hack/tickets/events/events-YYYY-MM.jsonl`.
 - The tickets ref is transported through git, so the system already has good offline and multi-machine portability.
 - Reads currently parse the full journal and materialize ticket state in memory on demand.
 - Sync-oriented reads such as external id lookup, conflict lookup, and checkpoint lookup are derived by replaying every event.
@@ -51,7 +51,7 @@ This avoids a new storage layer, but it does not materially improve cold-start r
 
 Keep the existing git-backed journal layout inside the tickets ref worktree:
 
-- `.hack/tickets/events/events-YYYY-MM.jsonl`
+- `.hack/tickets/git/worktree/.hack/tickets/events/events-YYYY-MM.jsonl`
 
 Each line remains one immutable event envelope:
 
@@ -107,9 +107,11 @@ Replay uses this total order:
 2. `orderKey` ascending when present
 3. `eventId` ascending
 
-Current writers already stamp `orderKey`, so same-second local writes preserve their original append sequence. The `eventId` fallback exists for legacy rows or any imported events that are missing `orderKey`.
+Current writers already stamp `orderKey`, so the projection can preserve same-second local append sequence once it owns replay ordering. The `eventId` fallback exists for legacy rows or any imported events that are missing `orderKey`.
 
-This order is deterministic across machines and rebuilds, even when segment files were merged from multiple writers. Segment filename and line number are recorded for diagnostics and incremental scanning, but they are not part of domain ordering.
+Today’s JSONL normalizer still rewrites files by `ts` and `eventId`. Part of this projection work is to make replay and future normalization agree on the stronger `ts` / `orderKey` / `eventId` ordering.
+
+This order is deterministic across machines and rebuilds once the projection exists, even when segment files were merged from multiple writers. Segment filename and line number are recorded for diagnostics and incremental scanning, but they are not part of domain ordering.
 
 ### Idempotency rule
 
@@ -309,11 +311,13 @@ Indexes:
 2. Read `projection_meta`.
 3. If the file is missing, `schema_version` is wrong, `journal_format_version` is wrong, status is `rebuilding`, or SQLite reports corruption, delete and rebuild.
 4. Otherwise compare the current segment inventory against `journal_segments` and fully rescan any segment whose bytes changed or that was not seen before.
-5. Combine all events from changed segments, sort them by canonical replay order, and rely on `journal_events` dedupe to skip events that were already applied.
+5. Inspect newly discovered events from those segments in canonical replay order.
+6. If every new event sorts strictly after the current replay cursor, append incrementally.
+7. If any new event sorts at or before the current replay cursor, rebuild instead of trying to patch mutable state out of order.
 
 ### Incremental replay
 
-Incremental replay works on candidate events gathered from changed segments, not only events after the current cursor. This preserves correctness when two machines append different events into the same monthly file and later merge through git.
+Incremental replay is only valid for monotonic tail growth. It works when new events gathered from changed segments all sort strictly after the current replay cursor.
 
 For each candidate journal line in canonical order:
 
@@ -327,7 +331,9 @@ For each candidate journal line in canonical order:
 
 After a segment scan finishes, update `journal_segments` with the segment fingerprint in a separate transaction boundary only after all of that segment's candidate events were processed successfully.
 
-This keeps replay crash-safe, allows progress to resume from the last committed event, and ensures newly merged historical events are not skipped.
+If a changed segment introduces a newly discovered event that sorts before already applied mutable events, replay must not rely on `journal_events` dedupe alone. In that case the correct behavior is to rebuild from journal bytes rather than apply the older event after newer state mutations.
+
+This keeps replay crash-safe, allows progress to resume from the last committed event, and avoids converging to the wrong state after multi-machine merges.
 
 ### Event application rules
 
@@ -403,7 +409,7 @@ The projection specifically accelerates:
 
 - Multiple machines can append semantically equivalent journals and later merge through git.
 - Normalization merges by `eventId` union, not by trusting file order.
-- Projection replay is safe after repeated fetch, merge, or sync because changed segments are rescanned and duplicate events are idempotent.
+- Projection replay is safe after repeated fetch, merge, or sync because tail-only additions replay incrementally while historical insertions force rebuild instead of out-of-order mutation.
 - Because SQLite is local-only, machines never need to coordinate projection files. They only need the same journal bytes.
 
 ## Implementation Notes
@@ -416,7 +422,7 @@ The projection specifically accelerates:
 
 - Rebuilding from the same journal twice yields byte-equivalent query results.
 - Reapplying the same merged journal does not duplicate comments, checkpoints, or conflicts.
-- Merging a segment that contains older events than the current replay cursor still converges because replay rescans the changed segment and deduplicates by `eventId`.
+- Merging a segment that contains older events than the current replay cursor still converges because the projection detects the historical insertion and rebuilds instead of applying it out of order.
 - Deleting the SQLite file does not lose ticket history.
 - Sync-heavy reads stop scanning all JSONL files on each command.
 - Duplicate `eventId` with mismatched payload is detected as corruption.
diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
index 9a924a793..d18df0a18 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
@@ -81,6 +81,8 @@ git commit -m "feat(tickets): add projection schema bootstrap"
 
 - Detect new or changed journal segments by fingerprint, then rescan those segments fully.
 - Parse candidate events in canonical order by `ts`, `orderKey`, `eventId`.
+- If every new event sorts after the replay cursor, append incrementally.
+- If any newly discovered event sorts at or before the replay cursor, trigger rebuild instead of out-of-order patch replay.
 - Insert each event into `journal_events` before mutating read tables.
 - Compare payload hashes on duplicate `eventId`.
 - Advance `journal_segments` only after the segment scan succeeds.

From c3b78476e266dcea6705e8511e60ecb360df60a8 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:16:57 +0000
Subject: [PATCH 042/134] fix: restore crash recovery inference

---
 src/commands/crash-capture.ts     | 345 ++++++++++++++++++++++++++++--
 src/commands/recovery-guidance.ts |  88 ++++++++
 tests/crash-capture.test.ts       | 251 +++++++++++++++++++---
 3 files changed, 636 insertions(+), 48 deletions(-)

diff --git a/src/commands/crash-capture.ts b/src/commands/crash-capture.ts
index 5b10e1476..f9816002b 100644
--- a/src/commands/crash-capture.ts
+++ b/src/commands/crash-capture.ts
@@ -11,6 +11,13 @@ import {
 import { findProjectContext, readProjectConfig } from "../lib/project.ts";
 import { exec } from "../lib/shell.ts";
 import { display } from "../ui/display.ts";
+import {
+  buildDoctorRecoveryGuidance,
+  buildRecoveryNextSteps,
+  type DoctorRecoveryGuidance,
+  type RecoveryCheckResult,
+  scopeDoctorRecoveryGuidance,
+} from "./recovery-guidance.ts";
 
 const DEFAULT_LOG_WINDOW = "45m";
 const DEFAULT_DOCKER_LOG_LINES = 300;
@@ -62,6 +69,7 @@ type CrashCaptureSummary = {
   readonly failureCount: number;
   readonly failedCommands: readonly string[];
   readonly errors: readonly string[];
+  readonly recovery: DoctorRecoveryGuidance;
   readonly nextSteps: readonly string[];
 };
 
@@ -183,7 +191,7 @@ const handleCrashCapture: CommandHandlerFor<typeof crashCaptureSpec> = async ({
     },
   });
 
-  const summary = buildCrashCaptureSummary({
+  const summary = await buildCrashCaptureSummary({
     captureRoot,
     projectRoot: project?.projectRoot ?? null,
     results,
@@ -198,6 +206,7 @@ const handleCrashCapture: CommandHandlerFor<typeof crashCaptureSpec> = async ({
     renderCrashCaptureReadme({
       captureRoot,
       projectRoot: project?.projectRoot ?? null,
+      recovery: summary.recovery,
       failedCommands: summary.failedCommands,
     }),
     { createPath: true }
@@ -539,15 +548,18 @@ async function writeJsonFile(input: {
   });
 }
 
-export function buildCrashCaptureSummary(input: {
+export async function buildCrashCaptureSummary(input: {
   readonly captureRoot: string;
   readonly projectRoot: string | null;
   readonly results: readonly CaptureCommandResult[];
   readonly errors: readonly string[];
-}): CrashCaptureSummary {
+}): Promise<CrashCaptureSummary> {
   const failedCommands = input.results
     .filter((result) => result.exitCode !== 0)
     .map((result) => result.name);
+  const recovery = buildDoctorRecoveryGuidance({
+    results: await inferRecoveryCheckResults({ results: input.results }),
+  });
 
   return {
     captureRoot: input.captureRoot,
@@ -556,27 +568,276 @@ export function buildCrashCaptureSummary(input: {
     failureCount: failedCommands.length,
     failedCommands,
     errors: input.errors,
-    nextSteps: buildCrashCaptureNextSteps({
+    recovery,
+    nextSteps: buildRecoveryNextSteps({
+      guidance: recovery,
       projectRoot: input.projectRoot,
+      includeClassifyStep: true,
     }),
   };
 }
 
-function buildCrashCaptureNextSteps(input: {
-  readonly projectRoot: string | null;
+async function inferRecoveryCheckResults(input: {
+  readonly results: readonly CaptureCommandResult[];
+}): Promise<readonly RecoveryCheckResult[]> {
+  const inferred: RecoveryCheckResult[] = [];
+  const seen = new Set<string>();
+
+  for (const result of input.results) {
+    if (!shouldInferRecoveryFromResult({ result })) {
+      continue;
+    }
+
+    const checkResults = await inferRecoveryCheckResult({ result });
+    for (const checkResult of checkResults) {
+      pushRecoveryCheckResult({
+        target: inferred,
+        seen,
+        result: checkResult,
+      });
+    }
+  }
+
+  return inferred;
+}
+
+async function inferRecoveryCheckResult(input: {
+  readonly result: CaptureCommandResult;
+}): Promise<readonly RecoveryCheckResult[]> {
+  const inferred: RecoveryCheckResult[] = [];
+  const seen = new Set<string>();
+  const output = await readCaptureOutput({
+    path: input.result.file,
+  });
+
+  if (output) {
+    pushRecoveryCheckResults({
+      target: inferred,
+      seen,
+      results: inferRecoveryCheckResultsFromOutput({ output }),
+    });
+  }
+
+  if (
+    input.result.name === "hack_global_status" &&
+    input.result.exitCode !== 0 &&
+    inferred.length === 0
+  ) {
+    pushRecoveryCheckResult({
+      target: inferred,
+      seen,
+      result: buildRecoveryFollowUpResult({
+        name: "hack global status",
+        logFile: "hack_global_status.log",
+      }),
+    });
+  }
+
+  if (
+    input.result.name === "hack_daemon_status" &&
+    input.result.exitCode !== 0 &&
+    inferred.length === 0
+  ) {
+    pushRecoveryCheckResult({
+      target: inferred,
+      seen,
+      result: buildRecoveryFollowUpResult({
+        name: "hack daemon status",
+        logFile: "hack_daemon_status.log",
+      }),
+    });
+  }
+
+  if (
+    input.result.name === "hack_doctor_project" &&
+    input.result.exitCode !== 0 &&
+    inferred.length === 0
+  ) {
+    pushRecoveryCheckResult({
+      target: inferred,
+      seen,
+      result: buildRecoveryFollowUpResult({
+        name: "doctor",
+        logFile: "hack_doctor_project.log",
+      }),
+    });
+  }
+
+  return inferred;
+}
+
+async function readCaptureOutput(input: {
+  readonly path: string;
+}): Promise<string | null> {
+  try {
+    return await Bun.file(input.path).text();
+  } catch {
+    return null;
+  }
+}
+
+function shouldInferRecoveryFromResult(input: {
+  readonly result: CaptureCommandResult;
+}): boolean {
+  if (input.result.name === "hack_doctor_project") {
+    return true;
+  }
+
+  return input.result.exitCode !== 0;
+}
+
+function inferRecoveryCheckResultsFromOutput(input: {
+  readonly output: string;
+}): readonly RecoveryCheckResult[] {
+  const inferred: RecoveryCheckResult[] = [];
+
+  if (input.output.includes("hack global up")) {
+    inferred.push({
+      name: "proxy ports",
+      status: "warn",
+      message: "Captured recovery guidance (run: hack global up)",
+    });
+  }
+
+  if (input.output.includes("hack restart")) {
+    inferred.push({
+      name: "caddy hosts",
+      status: "warn",
+      message: "Captured recovery guidance (run: hack restart)",
+    });
+  }
+
+  if (input.output.includes("hack daemon clear")) {
+    inferred.push({
+      name: "daemon",
+      status: "warn",
+      message: "Captured daemon status failure (run: hack daemon clear)",
+    });
+  } else if (input.output.includes("hack daemon start")) {
+    inferred.push({
+      name: "daemon",
+      status: "warn",
+      message: "Captured daemon status failure (run: hack daemon start)",
+    });
+  }
+
+  if (input.output.includes("hack doctor --fix")) {
+    inferred.push({
+      name: "coredns forwarding",
+      status: "warn",
+      message:
+        "Captured configuration repair guidance (run: hack doctor --fix)",
+    });
+  }
+
+  for (const item of extractManualFollowUpItems({ output: input.output })) {
+    const followUp = parseManualFollowUpItem({ item });
+    inferred.push({
+      name: followUp.name,
+      status: "warn",
+      message: followUp.message,
+    });
+  }
+
+  return inferred;
+}
+
+function extractManualFollowUpItems(input: {
+  readonly output: string;
 }): readonly string[] {
-  const projectRoot = input.projectRoot ?? "<repo>";
-  return [
-    `Run \`hack doctor --path ${projectRoot}\` to classify restart versus repair work.`,
-    "If global proxy/runtime is down, run `hack global up`.",
-    `If project host mappings are stale, run \`hack restart --path ${projectRoot}\`.`,
-    `If doctor reports DNS/network/CA drift, run \`hack doctor --fix --path ${projectRoot}\`.`,
-  ];
+  const lines = input.output.split("\n");
+  const items: string[] = [];
+  let inManualFollowUp = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed === "Manual follow-up:") {
+      inManualFollowUp = true;
+      continue;
+    }
+
+    if (!inManualFollowUp) {
+      continue;
+    }
+
+    if (trimmed.length === 0) {
+      break;
+    }
+
+    if (trimmed.endsWith(":") && !trimmed.startsWith("- ")) {
+      break;
+    }
+
+    if (trimmed.startsWith("- ")) {
+      items.push(trimmed.slice(2));
+    }
+  }
+
+  return items;
+}
+
+function parseManualFollowUpItem(input: { readonly item: string }): {
+  readonly name: string;
+  readonly message: string;
+} {
+  const separatorIndex = input.item.indexOf(": ");
+  if (separatorIndex === -1) {
+    return {
+      name: "doctor follow-up",
+      message: input.item,
+    };
+  }
+
+  return {
+    name: input.item.slice(0, separatorIndex),
+    message: input.item.slice(separatorIndex + 2),
+  };
+}
+
+function buildRecoveryFollowUpResult(input: {
+  readonly name: string;
+  readonly logFile: string;
+}): RecoveryCheckResult {
+  return {
+    name: input.name,
+    status: "warn",
+    message: `Review ${input.logFile} for detailed recovery guidance`,
+  };
+}
+
+function pushRecoveryCheckResults(input: {
+  readonly target: RecoveryCheckResult[];
+  readonly seen: Set<string>;
+  readonly results: readonly RecoveryCheckResult[];
+}): void {
+  for (const result of input.results) {
+    pushRecoveryCheckResult({
+      target: input.target,
+      seen: input.seen,
+      result,
+    });
+  }
+}
+
+function pushRecoveryCheckResult(input: {
+  readonly target: RecoveryCheckResult[];
+  readonly seen: Set<string>;
+  readonly result: RecoveryCheckResult;
+}): void {
+  const key = `${input.result.name}\u0000${input.result.message}`;
+  if (input.seen.has(key)) {
+    return;
+  }
+
+  input.seen.add(key);
+  input.target.push(input.result);
 }
 
 export function renderCrashCaptureReadme(input: {
   readonly captureRoot: string;
   readonly projectRoot: string | null;
+  readonly recovery: DoctorRecoveryGuidance;
   readonly failedCommands: readonly string[];
 }): string {
   const projectRoot = input.projectRoot ?? "<repo>";
@@ -600,9 +861,59 @@ export function renderCrashCaptureReadme(input: {
     ...failedCommands,
     "",
     "Suggested recovery flow:",
-    `1. hack doctor --path ${projectRoot}`,
-    "2. hack global up",
-    `3. hack restart --path ${projectRoot}`,
-    `4. hack doctor --fix --path ${projectRoot}`,
+    ...renderRecoveryWorkflow({
+      guidance: input.recovery,
+      projectRoot: input.projectRoot,
+    }),
   ].join("\n");
 }
+
+function renderRecoveryWorkflow(input: {
+  readonly guidance: DoctorRecoveryGuidance;
+  readonly projectRoot: string | null;
+}): readonly string[] {
+  const scoped = scopeDoctorRecoveryGuidance({
+    guidance: input.guidance,
+    projectRoot: input.projectRoot,
+  });
+  const projectRoot = input.projectRoot ?? "<repo>";
+  const lines = ["1. Classify:", `   - \`hack doctor --path ${projectRoot}\``];
+  let stepNumber = 2;
+
+  if (scoped.temporaryBreakage.length > 0) {
+    lines.push(`${stepNumber}. Temporary breakage:`);
+    for (const command of scoped.temporaryBreakage) {
+      lines.push(`   - \`${command}\``);
+    }
+    stepNumber += 1;
+  }
+
+  if (scoped.configurationRepair.length > 0) {
+    lines.push(`${stepNumber}. Configuration repair:`);
+    for (const command of scoped.configurationRepair) {
+      lines.push(`   - \`${command}\``);
+    }
+    stepNumber += 1;
+  }
+
+  if (scoped.followUp.length > 0) {
+    lines.push(`${stepNumber}. Manual follow-up:`);
+    for (const item of scoped.followUp) {
+      lines.push(`   - ${item}`);
+    }
+    stepNumber += 1;
+  }
+
+  lines.push(`${stepNumber}. Verify:`);
+  for (const command of scoped.verify) {
+    lines.push(`   - \`${command}\``);
+  }
+  stepNumber += 1;
+
+  lines.push(`${stepNumber}. If it still fails:`);
+  for (const command of scoped.capture) {
+    lines.push(`   - \`${command}\``);
+  }
+
+  return lines;
+}
diff --git a/src/commands/recovery-guidance.ts b/src/commands/recovery-guidance.ts
index 8d31f9315..6b90dccae 100644
--- a/src/commands/recovery-guidance.ts
+++ b/src/commands/recovery-guidance.ts
@@ -92,3 +92,91 @@ export function buildDoctorRecoveryGuidance(input: {
     capture: ["hack crash-capture --path <repo>"],
   };
 }
+
+export function scopeDoctorRecoveryGuidance(input: {
+  readonly guidance: DoctorRecoveryGuidance;
+  readonly projectRoot: string | null;
+}): DoctorRecoveryGuidance {
+  return {
+    temporaryBreakage: input.guidance.temporaryBreakage.map((command) =>
+      scopeRecoveryCommand({ command, projectRoot: input.projectRoot })
+    ),
+    configurationRepair: input.guidance.configurationRepair.map((command) =>
+      scopeRecoveryCommand({ command, projectRoot: input.projectRoot })
+    ),
+    followUp: [...input.guidance.followUp],
+    verify: input.guidance.verify.map((command) =>
+      scopeRecoveryCommand({ command, projectRoot: input.projectRoot })
+    ),
+    capture: input.guidance.capture.map((command) =>
+      scopeRecoveryCommand({ command, projectRoot: input.projectRoot })
+    ),
+  };
+}
+
+export function buildRecoveryNextSteps(input: {
+  readonly guidance: DoctorRecoveryGuidance;
+  readonly projectRoot: string | null;
+  readonly includeClassifyStep?: boolean;
+}): readonly string[] {
+  const scoped = scopeDoctorRecoveryGuidance({
+    guidance: input.guidance,
+    projectRoot: input.projectRoot,
+  });
+  const projectRoot = input.projectRoot ?? "<repo>";
+  const nextSteps: string[] = [];
+
+  if (input.includeClassifyStep ?? false) {
+    nextSteps.push(
+      `Run \`hack doctor --path ${projectRoot}\` to classify restart versus repair work.`
+    );
+  }
+
+  for (const command of scoped.temporaryBreakage) {
+    nextSteps.push(`Temporary breakage: \`${command}\`.`);
+  }
+
+  for (const command of scoped.configurationRepair) {
+    nextSteps.push(`Configuration repair: \`${command}\`.`);
+  }
+
+  for (const item of scoped.followUp) {
+    nextSteps.push(`Manual follow-up: ${item}`);
+  }
+
+  for (const command of scoped.verify) {
+    nextSteps.push(`Verify with \`${command}\`.`);
+  }
+
+  if (scoped.capture[0]) {
+    nextSteps.push(
+      `If it still fails, run \`${scoped.capture[0]}\` again after the next repro.`
+    );
+  }
+
+  return nextSteps;
+}
+
+function scopeRecoveryCommand(input: {
+  readonly command: string;
+  readonly projectRoot: string | null;
+}): string {
+  const projectRoot = input.projectRoot?.trim();
+  if (!projectRoot) {
+    return input.command;
+  }
+
+  if (input.command === "hack doctor") {
+    return `hack doctor --path ${projectRoot}`;
+  }
+
+  if (input.command === "hack doctor --fix") {
+    return `hack doctor --fix --path ${projectRoot}`;
+  }
+
+  if (input.command === "hack restart") {
+    return `hack restart --path ${projectRoot}`;
+  }
+
+  return input.command.replace("<repo>", projectRoot);
+}
diff --git a/tests/crash-capture.test.ts b/tests/crash-capture.test.ts
index 2f0a0b3b1..cf8dfac15 100644
--- a/tests/crash-capture.test.ts
+++ b/tests/crash-capture.test.ts
@@ -1,4 +1,7 @@
 import { expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
 
 import {
   buildBaseCaptureCommands,
@@ -28,44 +31,205 @@ test("crash capture includes doctor and proxy-relevant diagnostics", () => {
   expect(processSnapshot?.cmd.join(" ")).not.toContain("rg ");
 });
 
-test("crash capture summary reports failures and ordered next steps", () => {
-  const summary = buildCrashCaptureSummary({
-    captureRoot: "/tmp/demo/.tmp/crash-capture-1",
-    projectRoot: "/tmp/demo",
-    results: [
-      {
-        name: "hack_doctor_project",
-        cmd: ["hack", "doctor", "--path", "/tmp/demo"],
-        exitCode: 1,
-        file: "/tmp/demo/.tmp/crash-capture-1/hack_doctor_project.log",
-        bytes: 120,
-      },
-      {
-        name: "hack_global_status",
-        cmd: ["hack", "global", "status", "--json"],
-        exitCode: 0,
-        file: "/tmp/demo/.tmp/crash-capture-1/hack_global_status.log",
-        bytes: 80,
-      },
-    ],
-    errors: ["hack_doctor_project failed (1)"],
-  });
+test("crash capture summary restores doctor recovery guidance from warning-only doctor logs", async () => {
+  const captureRoot = await mkdtemp(resolve(tmpdir(), "hack-crash-capture-"));
+  const doctorLog = resolve(captureRoot, "hack_doctor_project.log");
+  await Bun.write(
+    doctorLog,
+    [
+      "$ hack doctor --path /tmp/demo",
+      "exit_code=1",
+      "",
+      "Temporary breakage:",
+      "- hack restart",
+      "",
+      "Configuration repair:",
+      "- hack doctor --fix",
+      "",
+      "Manual follow-up:",
+      "- gateway tokens: No active tokens (run: hack x gateway token-create)",
+    ].join("\n")
+  );
+
+  try {
+    const summary = await buildCrashCaptureSummary({
+      captureRoot,
+      projectRoot: "/tmp/demo",
+      results: [
+        {
+          name: "hack_doctor_project",
+          cmd: ["hack", "doctor", "--path", "/tmp/demo"],
+          exitCode: 0,
+          file: doctorLog,
+          bytes: 120,
+        },
+        {
+          name: "hack_global_status",
+          cmd: ["hack", "global", "status", "--json"],
+          exitCode: 0,
+          file: resolve(captureRoot, "hack_global_status.log"),
+          bytes: 80,
+        },
+      ],
+      errors: ["hack_doctor_project failed (1)"],
+    });
+
+    expect(summary.commandCount).toBe(2);
+    expect(summary.failureCount).toBe(0);
+    expect(summary.failedCommands).toEqual([]);
+    expect(summary.recovery.temporaryBreakage).toEqual(["hack restart"]);
+    expect(summary.recovery.configurationRepair).toEqual(["hack doctor --fix"]);
+    expect(summary.recovery.followUp).toEqual([
+      "gateway tokens: No active tokens (run: hack x gateway token-create)",
+    ]);
+    expect(summary.nextSteps).toEqual([
+      "Run `hack doctor --path /tmp/demo` to classify restart versus repair work.",
+      "Temporary breakage: `hack restart --path /tmp/demo`.",
+      "Configuration repair: `hack doctor --fix --path /tmp/demo`.",
+      "Manual follow-up: gateway tokens: No active tokens (run: hack x gateway token-create)",
+      "Verify with `hack doctor --path /tmp/demo`.",
+      "If it still fails, run `hack crash-capture --path /tmp/demo` again after the next repro.",
+    ]);
+  } finally {
+    await rm(captureRoot, { force: true, recursive: true });
+  }
+});
+
+test("crash capture summary infers stale daemon recovery from captured failures", async () => {
+  const captureRoot = await mkdtemp(resolve(tmpdir(), "hack-crash-capture-"));
+  const globalStatusLog = resolve(captureRoot, "hack_global_status.log");
+  const daemonLog = resolve(captureRoot, "hack_daemon_status.log");
+  await Bun.write(
+    globalStatusLog,
+    [
+      "$ hack global status --json",
+      "exit_code=1",
+      "",
+      "Caddy not reachable (run: hack global up)",
+    ].join("\n")
+  );
+  await Bun.write(
+    daemonLog,
+    [
+      "$ hack daemon status",
+      "exit_code=1",
+      "",
+      "hackd not running (stale pid/socket; run: hack daemon clear)",
+    ].join("\n")
+  );
+
+  try {
+    const summary = await buildCrashCaptureSummary({
+      captureRoot,
+      projectRoot: "/tmp/demo",
+      results: [
+        {
+          name: "hack_global_status",
+          cmd: ["hack", "global", "status", "--json"],
+          exitCode: 1,
+          file: globalStatusLog,
+          bytes: 80,
+        },
+        {
+          name: "hack_daemon_status",
+          cmd: ["hack", "daemon", "status"],
+          exitCode: 1,
+          file: daemonLog,
+          bytes: 80,
+        },
+      ],
+      errors: [],
+    });
+
+    expect(summary.recovery.temporaryBreakage).toEqual([
+      "hack global up",
+      "hack daemon clear",
+      "hack daemon start",
+    ]);
+    expect(summary.recovery.configurationRepair).toEqual([]);
+    expect(summary.nextSteps).toEqual([
+      "Run `hack doctor --path /tmp/demo` to classify restart versus repair work.",
+      "Temporary breakage: `hack global up`.",
+      "Temporary breakage: `hack daemon clear`.",
+      "Temporary breakage: `hack daemon start`.",
+      "Verify with `hack doctor --path /tmp/demo`.",
+      "If it still fails, run `hack crash-capture --path /tmp/demo` again after the next repro.",
+    ]);
+  } finally {
+    await rm(captureRoot, { force: true, recursive: true });
+  }
+});
+
+test("crash capture keeps unknown status failures as manual follow-up", async () => {
+  const captureRoot = await mkdtemp(resolve(tmpdir(), "hack-crash-capture-"));
+  const globalStatusLog = resolve(captureRoot, "hack_global_status.log");
+  const daemonLog = resolve(captureRoot, "hack_daemon_status.log");
+  await Bun.write(
+    globalStatusLog,
+    [
+      "$ hack global status --json",
+      "exit_code=1",
+      "",
+      "permission denied",
+    ].join("\n")
+  );
+  await Bun.write(
+    daemonLog,
+    ["$ hack daemon status", "exit_code=1", "", "internal rpc error"].join("\n")
+  );
+
+  try {
+    const summary = await buildCrashCaptureSummary({
+      captureRoot,
+      projectRoot: "/tmp/demo",
+      results: [
+        {
+          name: "hack_global_status",
+          cmd: ["hack", "global", "status", "--json"],
+          exitCode: 1,
+          file: globalStatusLog,
+          bytes: 32,
+        },
+        {
+          name: "hack_daemon_status",
+          cmd: ["hack", "daemon", "status"],
+          exitCode: 1,
+          file: daemonLog,
+          bytes: 24,
+        },
+      ],
+      errors: [],
+    });
 
-  expect(summary.commandCount).toBe(2);
-  expect(summary.failureCount).toBe(1);
-  expect(summary.failedCommands).toEqual(["hack_doctor_project"]);
-  expect(summary.nextSteps).toEqual([
-    "Run `hack doctor --path /tmp/demo` to classify restart versus repair work.",
-    "If global proxy/runtime is down, run `hack global up`.",
-    "If project host mappings are stale, run `hack restart --path /tmp/demo`.",
-    "If doctor reports DNS/network/CA drift, run `hack doctor --fix --path /tmp/demo`.",
-  ]);
+    expect(summary.recovery.temporaryBreakage).toEqual([]);
+    expect(summary.recovery.configurationRepair).toEqual([]);
+    expect(summary.recovery.followUp).toEqual([
+      "hack global status: Review hack_global_status.log for detailed recovery guidance",
+      "hack daemon status: Review hack_daemon_status.log for detailed recovery guidance",
+    ]);
+    expect(summary.nextSteps).toEqual([
+      "Run `hack doctor --path /tmp/demo` to classify restart versus repair work.",
+      "Manual follow-up: hack global status: Review hack_global_status.log for detailed recovery guidance",
+      "Manual follow-up: hack daemon status: Review hack_daemon_status.log for detailed recovery guidance",
+      "Verify with `hack doctor --path /tmp/demo`.",
+      "If it still fails, run `hack crash-capture --path /tmp/demo` again after the next repro.",
+    ]);
+  } finally {
+    await rm(captureRoot, { force: true, recursive: true });
+  }
 });
 
 test("crash capture readme points operators to the summary and raw logs", () => {
   const text = renderCrashCaptureReadme({
     captureRoot: "/tmp/demo/.tmp/crash-capture-1",
     projectRoot: "/tmp/demo",
+    recovery: {
+      temporaryBreakage: [],
+      configurationRepair: [],
+      followUp: [],
+      verify: ["hack doctor"],
+      capture: ["hack crash-capture --path <repo>"],
+    },
     failedCommands: ["hack_doctor_project", "hack_daemon_logs"],
   });
 
@@ -75,4 +239,29 @@ test("crash capture readme points operators to the summary and raw logs", () =>
   expect(text).toContain("hack_doctor_project");
   expect(text).toContain("hack_daemon_logs");
   expect(text).toContain("hack doctor --path /tmp/demo");
+  expect(text).toContain("Verify:");
+  expect(text).toContain("- `hack doctor --path /tmp/demo`");
+  expect(text).toContain("If it still fails:");
+  expect(text).toContain("- `hack crash-capture --path /tmp/demo`");
+});
+
+test("crash capture readme groups inferred restart actions into sections", () => {
+  const text = renderCrashCaptureReadme({
+    captureRoot: "/tmp/demo/.tmp/crash-capture-1",
+    projectRoot: "/tmp/demo",
+    recovery: {
+      temporaryBreakage: ["hack global up", "hack daemon start"],
+      configurationRepair: [],
+      followUp: [],
+      verify: ["hack doctor"],
+      capture: ["hack crash-capture --path <repo>"],
+    },
+    failedCommands: ["hack_global_status", "hack_daemon_status"],
+  });
+
+  expect(text).toContain("Temporary breakage:");
+  expect(text).toContain("- `hack global up`");
+  expect(text).toContain("- `hack daemon start`");
+  expect(text).toContain("Verify:");
+  expect(text).toContain("If it still fails:");
 });

From cafe775b86a950041eedd67532268ef60ae6d90e Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:27:04 +0000
Subject: [PATCH 043/134] docs: surface linear project artifact workflows

---
 docs/cli.md                                    |  8 +++++++-
 docs/extensions.md                             |  2 +-
 docs/guides/linear-integration-architecture.md | 15 +++++++--------
 src/commands/linear.ts                         |  6 +++++-
 tests/cli-command.test.ts                      | 14 ++++++++++++++
 5 files changed, 34 insertions(+), 11 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..c63bfea3f 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -28,7 +28,7 @@ Run `hack help` or `hack help <command>` for interactive help.
 | `hack open` | Open a URL for the project (default: https://<project>.hack) | Project |
 | `hack tui` | Open the project TUI (services + logs) | Project |
 | `hack branch` | Manage branch aliases for a project | Project |
-| `hack linear` | Linear account connection and ticket sync | Project |
+| `hack linear` | Linear account connection, issue sync, and project artifact management | Project |
 | `hack config` | Read/write hack.config.json values | Project |
 | `hack env` | Manage project environment variables and secrets | Project |
 | `hack session` | Manage terminal sessions for hack projects | Project |
@@ -656,6 +656,12 @@ Usage: `hack linear <args...>`
 `hack linear` is a convenience alias for the Linear extension (`hack x linear ...`).
 Run `hack linear` with no args to see available subcommands.
 
+Examples:
+
+- `hack linear documents pull`
+- `hack linear milestones plan`
+- `hack linear status-updates publish --path .hack/linear/projects/<project-id>/status-updates/drafts/<yyyy-mm-dd>-<slug>.md`
+
 ## Internal commands
 
 ### hack internal
diff --git a/docs/extensions.md b/docs/extensions.md
index 543df7263..516835a38 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -323,7 +323,7 @@ Notes:
   - `dependencies` (default `true`)
   - `projects` (default `true`)
 - Architecture + rollout guide: `docs/guides/linear-integration-architecture.md`.
-- Planned managed project artifacts (documents, milestones, status updates):
+- Managed project artifacts (documents, milestones, status updates) are documented in:
   `docs/plans/2026-03-14-linear-project-artifacts-design.md`.
 
 #### job-show
diff --git a/docs/guides/linear-integration-architecture.md b/docs/guides/linear-integration-architecture.md
index f89266bfe..14a3ec219 100644
--- a/docs/guides/linear-integration-architecture.md
+++ b/docs/guides/linear-integration-architecture.md
@@ -69,21 +69,20 @@ This guarantees filtering by local-only, Linear-only, or mixed sets without ambi
 1. Phase 1 (current): manual sync only, explicit one-off operations.
 2. Phase 2: webhook-driven candidate updates (still gated/manual apply).
 3. Phase 3: selective autosync per project/profile with conflict policies.
-4. Phase 4 (planned): repo-managed project documents, milestones, and status updates.
+4. Phase 4: repo-managed project documents, milestones, and status updates.
 
-## Planned Project Artifact Layer
+## Project Artifact Layer
 
-The next Linear planning slice should extend the existing project binding model with repo-managed
-project artifacts:
+Hack now extends the existing project binding model with repo-managed project artifacts:
 
 - documents
 - milestones
 - status updates
 
-These artifacts should not live in `hack.config.json` blobs or direct one-shot CLI flags. They
-should live in a dedicated repo tree under `.hack/linear/projects/<project-id>/` and use explicit
-`pull`, `plan`, and `apply`/`publish` workflows.
+These artifacts do not live in `hack.config.json` blobs or direct one-shot CLI flags. They live in
+a dedicated repo tree under `.hack/linear/projects/<project-id>/` and use explicit `pull`, `plan`,
+and `apply`/`publish` workflows.
 
-Detailed design:
+Design + implementation details:
 - `docs/plans/2026-03-14-linear-project-artifacts-design.md`
 - `docs/plans/2026-03-14-linear-project-artifacts-plan.md`
diff --git a/src/commands/linear.ts b/src/commands/linear.ts
index 7c3426f9c..b928aabd5 100644
--- a/src/commands/linear.ts
+++ b/src/commands/linear.ts
@@ -13,7 +13,8 @@ import { logger } from "../ui/logger.ts";
  */
 const linearSpec = defineCommand({
   name: "linear",
-  summary: "Linear account connection and ticket sync",
+  summary:
+    "Linear account connection, issue sync, and project artifact management",
   description: [
     "Usage:",
     "  hack linear status",
@@ -24,6 +25,9 @@ const linearSpec = defineCommand({
     "  hack linear sync-issue --from linear --issue ENG-123",
     "  hack linear sync-issue --from hack --ticket T-00001",
     "  hack linear sync-project --from linear --project-id <linear-project-id>",
+    "  hack linear documents pull",
+    "  hack linear milestones plan",
+    "  hack linear status-updates publish --path .hack/linear/projects/<project-id>/status-updates/drafts/<yyyy-mm-dd>-<slug>.md",
     "",
     "Alias for `hack x linear <command>`. Requires extension enabled.",
   ].join("\n"),
diff --git a/tests/cli-command.test.ts b/tests/cli-command.test.ts
index be68608ee..4d0a8fff3 100644
--- a/tests/cli-command.test.ts
+++ b/tests/cli-command.test.ts
@@ -60,3 +60,17 @@ test("resolveCommand finds crash-capture command", () => {
   ]);
   expect(resolved.remainingPositionals).toEqual([]);
 });
+
+test("linear command metadata advertises project artifact workflows", () => {
+  const resolved = resolveCommand(CLI_SPEC, ["linear"]);
+  expect(resolved.command?.summary).toBe(
+    "Linear account connection, issue sync, and project artifact management"
+  );
+  expect(resolved.command?.description).toContain("hack linear documents pull");
+  expect(resolved.command?.description).toContain(
+    "hack linear milestones plan"
+  );
+  expect(resolved.command?.description).toContain(
+    "hack linear status-updates publish"
+  );
+});

From 4d8af4c20914e0921c2514d667a67d066084daa1 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:30:45 +0000
Subject: [PATCH 044/134] fix: hide unsupported linear archive verbs

---
 .../extensions/linear/commands.ts             | 14 +++-----------
 tests/linear-commands.test.ts                 | 19 ++++++++++++++++---
 2 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index 4dcd7bb39..6793bbc1a 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -2590,7 +2590,7 @@ type ProjectArtifactArgsBase = {
   json: boolean;
 };
 
-type ProjectDocumentsVerb = "list" | "pull" | "plan" | "apply" | "archive";
+type ProjectDocumentsVerb = "list" | "pull" | "plan" | "apply";
 type ProjectMilestonesVerb = ProjectDocumentsVerb;
 type ProjectStatusUpdatesVerb = "list" | "pull" | "plan" | "publish";
 
@@ -2907,14 +2907,6 @@ async function runProjectArtifactCommand(input: {
   | { readonly ok: false; readonly error: string }
 > {
   try {
-    if (input.verb === "archive") {
-      return {
-        ok: false,
-        error:
-          "Archive is not implemented yet for managed Linear project artifacts.",
-      };
-    }
-
     if (input.verb === "list") {
       const artifacts = await listRemoteProjectArtifacts({
         family: input.family,
@@ -9359,7 +9351,7 @@ function parseProjectDocumentsArgs(input: {
   | { readonly ok: false; readonly error: string } {
   return parseProjectArtifactArgs({
     args: input.args,
-    allowedVerbs: ["list", "pull", "plan", "apply", "archive"],
+    allowedVerbs: ["list", "pull", "plan", "apply"],
   }) as
     | { readonly ok: true; readonly value: ProjectDocumentsArgs }
     | { readonly ok: false; readonly error: string };
@@ -9372,7 +9364,7 @@ function parseProjectMilestonesArgs(input: {
   | { readonly ok: false; readonly error: string } {
   return parseProjectArtifactArgs({
     args: input.args,
-    allowedVerbs: ["list", "pull", "plan", "apply", "archive"],
+    allowedVerbs: ["list", "pull", "plan", "apply"],
   }) as
     | { readonly ok: true; readonly value: ProjectMilestonesArgs }
     | { readonly ok: false; readonly error: string };
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index 3f0519682..58e66b10a 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -1560,9 +1560,9 @@ test("parseProjectStatusUpdatesArgs parses publish verbs", () => {
   });
 });
 
-test("parseProjectDocumentsArgs rejects unsupported verbs", () => {
+test("parseProjectDocumentsArgs rejects archive until destructive flows are implemented", () => {
   const parsed = __testOnly.parseProjectDocumentsArgs({
-    args: ["publish"],
+    args: ["archive"],
   });
 
   expect(parsed.ok).toBe(false);
@@ -1570,7 +1570,20 @@ test("parseProjectDocumentsArgs rejects unsupported verbs", () => {
     return;
   }
 
-  expect(parsed.error).toContain("Expected list|pull|plan|apply|archive");
+  expect(parsed.error).toContain("Expected list|pull|plan|apply");
+});
+
+test("parseProjectMilestonesArgs rejects archive until destructive flows are implemented", () => {
+  const parsed = __testOnly.parseProjectMilestonesArgs({
+    args: ["archive"],
+  });
+
+  expect(parsed.ok).toBe(false);
+  if (parsed.ok) {
+    return;
+  }
+
+  expect(parsed.error).toContain("Expected list|pull|plan|apply");
 });
 
 test("LINEAR_COMMANDS registers project artifact command families", () => {

From 9650f1779bd10b79d373597233b4db9f521adcad Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:32:44 +0000
Subject: [PATCH 045/134] docs: align linear artifact design with shipped verbs

---
 docs/plans/2026-03-14-linear-project-artifacts-design.md | 7 +++----
 docs/plans/2026-03-14-linear-project-artifacts-plan.md   | 2 +-
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/docs/plans/2026-03-14-linear-project-artifacts-design.md b/docs/plans/2026-03-14-linear-project-artifacts-design.md
index 42dee4eff..10c0c6398 100644
--- a/docs/plans/2026-03-14-linear-project-artifacts-design.md
+++ b/docs/plans/2026-03-14-linear-project-artifacts-design.md
@@ -188,14 +188,12 @@ Documents:
 - `pull`
 - `plan`
 - `apply`
-- `archive`
 
 Milestones:
 - `list`
 - `pull`
 - `plan`
 - `apply`
-- `archive`
 
 Status updates:
 - `list`
@@ -207,6 +205,7 @@ Reasoning:
 - `plan` is the non-mutating diff/preflight verb across all families.
 - `apply` is correct for upsertable artifacts.
 - `publish` is clearer than `apply` for append-only status updates.
+- destructive archive flows should ship later, after the base upsert/publish path proves stable
 
 ### Shared targeting flags
 All three families should accept the same routing flags:
@@ -224,7 +223,7 @@ Resolution order:
 
 ### UX rules
 1. No remote writes on plain `list` or `pull`.
-2. `plan` is required for safe review and should show create/update/archive counts before `apply` or `publish`.
+2. `plan` is required for safe review and should show create/update/noop/remote-only counts before `apply` or `publish`.
 3. `apply` and `publish` must be explicit; no autosync for planning artifacts in this slice.
 4. Missing project binding should fail with the same pattern as existing project-bound commands and suggest `hack linear project-bind`.
 5. `--json` output must be stable and structured so desktop/MCP clients can adopt the same surface later.
@@ -242,7 +241,7 @@ Resolution order:
 
 ### Plan
 - Compare local files and remote artifacts.
-- Categorize results as `create`, `update`, `archive`, `noop`, `conflict`.
+- Categorize results as `create`, `update`, `noop`, `remoteOnly`, `conflict`.
 - Exit non-zero only for hard resolution failures, not for pending work.
 
 ### Apply
diff --git a/docs/plans/2026-03-14-linear-project-artifacts-plan.md b/docs/plans/2026-03-14-linear-project-artifacts-plan.md
index 68d8b7c8f..0c8766c5b 100644
--- a/docs/plans/2026-03-14-linear-project-artifacts-plan.md
+++ b/docs/plans/2026-03-14-linear-project-artifacts-plan.md
@@ -260,8 +260,8 @@ Expected: FAIL because the planner does not yet compute a complete action set.
 Implement a planner that returns:
 - `creates`
 - `updates`
-- `archives`
 - `noops`
+- `remoteOnly`
 - `conflicts`
 
 Render human output with existing `display.table` / `display.kv` helpers and structured JSON for machine use.

From 2cdd09661a3995a5ed34fa5b64c7f92ae87d09d9 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:33:50 +0000
Subject: [PATCH 046/134] docs(tickets): close projection design review gaps

---
 ...3-14-hack-tickets-sqlite-journal-design.md | 19 ++++++++++++++----
 ...-03-14-hack-tickets-sqlite-journal-plan.md | 20 +++++++++++++++++--
 2 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
index 2ea528898..16caa7d50 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md
@@ -179,7 +179,7 @@ This table is the durable idempotency fence and powers fast `show` queries witho
 - `line_count INTEGER NOT NULL`
 - `scanned_at TEXT NOT NULL`
 
-This table tracks which journal segment bytes have already been scanned into the projection. Replay correctness must not rely on the last applied sort key alone because a merged segment can introduce older events that sort before the current replay cursor.
+This table tracks which journal segment bytes have already been scanned into the projection. Replay correctness must not rely on the last applied sort key alone because a merged segment can introduce older events that sort before the current replay cursor. If the current journal inventory ever drops a segment that was previously scanned, startup must treat that as source-of-truth drift and rebuild from the remaining journal bytes so removed history does not linger in SQLite.
 
 ### Ticket projection
 
@@ -238,6 +238,13 @@ Indexes:
 - `ticket_blocks_blocks_idx (blocks_ticket_id, ticket_id)`
 - `ticket_tags_tag_idx (tag, ticket_id)`
 
+`ticket_blocks` stores the effective blocker edges exposed by reads, not just the explicit `blocks` payload field. To preserve current ticket semantics, replay must materialize `ticket.blocks` as the union of:
+
+- explicit `blocks` values written on that ticket
+- reverse `dependsOn` edges from other tickets that depend on this ticket
+
+That matches the current in-memory materializer, where blockers are derived from both direct `blocks` fields and reverse dependencies.
+
 ### Append-only child entities
 
 `ticket_comments`
@@ -310,7 +317,7 @@ Indexes:
 1. Open SQLite in WAL mode.
 2. Read `projection_meta`.
 3. If the file is missing, `schema_version` is wrong, `journal_format_version` is wrong, status is `rebuilding`, or SQLite reports corruption, delete and rebuild.
-4. Otherwise compare the current segment inventory against `journal_segments` and fully rescan any segment whose bytes changed or that was not seen before.
+4. Otherwise compare the current segment inventory against `journal_segments`. If any previously scanned segment is now missing, rebuild from scratch. Fully rescan any segment whose bytes changed or that was not seen before.
 5. Inspect newly discovered events from those segments in canonical replay order.
 6. If every new event sorts strictly after the current replay cursor, append incrementally.
 7. If any new event sorts at or before the current replay cursor, rebuild instead of trying to patch mutable state out of order.
@@ -337,8 +344,8 @@ This keeps replay crash-safe, allows progress to resume from the last committed
 
 ### Event application rules
 
-- `ticket.created`: insert a row into `tickets`, replace dependency/block/tag sets from payload, set `created_at` and `updated_at` from the event timestamp.
-- `ticket.updated`: patch only provided fields, replace dependency/block/tag sets only when they appear in payload, set `updated_at`.
+- `ticket.created`: insert a row into `tickets`, replace dependency/tag sets from payload, recompute effective blocker rows for the touched ticket and any tickets referenced by its dependency edges, and set `created_at` and `updated_at` from the event timestamp.
+- `ticket.updated`: patch only provided fields, replace dependency/tag sets only when they appear in payload, recompute effective blocker rows whenever explicit `blocks` or dependency edges change, and set `updated_at`.
 - `ticket.status_changed`: update `status` and `updated_at`.
 - `ticket.comment_appended`: insert into `ticket_comments`.
 - `ticket.comment_linked`: patch `external_id` and `external_url` for the existing comment row.
@@ -409,6 +416,7 @@ The projection specifically accelerates:
 
 - Multiple machines can append semantically equivalent journals and later merge through git.
 - Normalization merges by `eventId` union, not by trusting file order.
+- Journal normalization and projection replay must use the same `ts` / `orderKey` / `eventId` ordering so same-second events do not materialize differently before and after `sync`.
 - Projection replay is safe after repeated fetch, merge, or sync because tail-only additions replay incrementally while historical insertions force rebuild instead of out-of-order mutation.
 - Because SQLite is local-only, machines never need to coordinate projection files. They only need the same journal bytes.
 
@@ -423,8 +431,11 @@ The projection specifically accelerates:
 - Rebuilding from the same journal twice yields byte-equivalent query results.
 - Reapplying the same merged journal does not duplicate comments, checkpoints, or conflicts.
 - Merging a segment that contains older events than the current replay cursor still converges because the projection detects the historical insertion and rebuilds instead of applying it out of order.
+- Removing or replacing a scanned segment converges because startup treats missing segment inventory as a rebuild trigger.
 - Deleting the SQLite file does not lose ticket history.
 - Sync-heavy reads stop scanning all JSONL files on each command.
+- Tickets that are only blocked through reverse `dependsOn` edges still surface the same effective `blocks` list after reads move to SQLite.
+- `ticket.status_changed` continues to drive the visible ticket status and `updated_at` once reads are served from the projection.
 - Duplicate `eventId` with mismatched payload is detected as corruption.
 
 ## Recommendation
diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
index d18df0a18..b5dd5524a 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
@@ -22,6 +22,7 @@
 - Add a test that rebuilds from a fixed journal and asserts ticket, comment, checkpoint, and conflict rows are present in the projection.
 - Add a test that replays the same event stream twice and asserts child rows are not duplicated.
 - Add a test that feeds the same `eventId` with different payloads and asserts replay fails with a corruption error.
+- Add a test that applies `ticket.status_changed` and asserts the projected `status` and `updated_at` match the journal.
 
 **Step 2: Run focused tests to verify failure** Run: `bun test tests/tickets-projection.test.ts tests/tickets-store.test.ts` Expected: FAIL because no projection module or corruption checks exist yet.
 
@@ -75,17 +76,21 @@ git commit -m "feat(tickets): add projection schema bootstrap"
 
 - Modify: `src/control-plane/extensions/tickets/projection.ts`
 - Modify: `src/control-plane/extensions/tickets/store.ts`
+- Modify: `src/control-plane/extensions/tickets/tickets-git-channel.ts`
 - Test: `tests/tickets-projection.test.ts`
+- Test: `tests/tickets-git-channel.test.ts`
 
 **Step 1: Write the replay engine**
 
 - Detect new or changed journal segments by fingerprint, then rescan those segments fully.
+- Trigger rebuild when a previously scanned segment is missing from the current journal inventory.
 - Parse candidate events in canonical order by `ts`, `orderKey`, `eventId`.
 - If every new event sorts after the replay cursor, append incrementally.
 - If any newly discovered event sorts at or before the replay cursor, trigger rebuild instead of out-of-order patch replay.
 - Insert each event into `journal_events` before mutating read tables.
 - Compare payload hashes on duplicate `eventId`.
 - Advance `journal_segments` only after the segment scan succeeds.
+- Update journal normalization helpers so `sync` and merge repair sort by the same `ts`, `orderKey`, `eventId` order used by replay.
 
 **Step 2: Implement event appliers**
 
@@ -99,12 +104,14 @@ git commit -m "feat(tickets): add projection schema bootstrap"
 - `ticket.sync_conflict_recorded`
 - `ticket.sync_conflict_resolved`
 
+Preserve current `blocks` semantics by recomputing effective blocker rows as the union of explicit `blocks` fields and reverse `dependsOn` edges.
+
 **Step 3: Run focused tests** Run: `bun test tests/tickets-projection.test.ts` Expected: PASS
 
 **Step 4: Commit**
 
 ```bash
-git add src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts tests/tickets-projection.test.ts
+git add src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/tickets-git-channel.ts tests/tickets-projection.test.ts tests/tickets-git-channel.test.ts
 git commit -m "feat(tickets): replay journal into sqlite projection"
 ```
 
@@ -126,6 +133,7 @@ git commit -m "feat(tickets): replay journal into sqlite projection"
 - any sync lookup helpers added during implementation
 
 These reads should prefer SQLite and only trigger replay or rebuild when projection state is missing or stale.
+Add assertions that `tickets list`, `tickets show`, and `tickets status` still expose the correct status, `updated_at`, and effective blocker set once reads come from SQLite.
 
 **Step 2: Preserve write path semantics**
 
@@ -184,6 +192,8 @@ git commit -m "feat(tickets): add projection rebuild recovery"
 - sync remote journal content into a local clone
 - replay merged logs with duplicate events
 - replay a merged monthly segment that introduces older events than the current replay cursor
+- remove or replace a previously scanned segment and confirm startup rebuilds instead of serving orphaned rows
+- normalize same-second events with distinct `orderKey` values and confirm replay order matches post-sync order
 - confirm projection rows remain correct after repeated sync
 
 **Step 2: Run focused tests** Run: `bun test tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts` Expected: PASS
@@ -217,7 +227,13 @@ bun run check
 
 Expected: PASS
 
-**Step 3: Commit**
+**Step 3: Land the session-close workflow**
+
+- File follow-up tickets for anything discovered during implementation that should not block merge.
+- Update the local tracking state for this work item and any spawned follow-up tickets.
+- Leave a concise next-session handoff that names the projection state, remaining risks, and exact commands/tests already verified.
+
+**Step 4: Commit**
 
 ```bash
 git add docs/guides/tickets.md docs/plans/2026-03-14-hack-tickets-sqlite-journal-design.md docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md tests/tickets-projection.test.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts tests/tickets-git-channel.test.ts src/control-plane/extensions/tickets/projection.ts src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/commands.ts

From 1018d15fee886b4ad966277a9a7a6c17c24ee7f8 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:39:43 +0000
Subject: [PATCH 047/134] fix: harden recovery guidance inference

---
 src/commands/crash-capture.ts     | 81 +++++++++++++++++++++++++++++--
 src/commands/recovery-guidance.ts | 59 +++++++++++-----------
 tests/crash-capture.test.ts       | 56 +++++++++++++++++++--
 tests/doctor-command.test.ts      | 60 ++++++++++++++++++++++-
 4 files changed, 219 insertions(+), 37 deletions(-)

diff --git a/src/commands/crash-capture.ts b/src/commands/crash-capture.ts
index f9816002b..a4e5caaab 100644
--- a/src/commands/crash-capture.ts
+++ b/src/commands/crash-capture.ts
@@ -17,6 +17,7 @@ import {
   type DoctorRecoveryGuidance,
   type RecoveryCheckResult,
   scopeDoctorRecoveryGuidance,
+  scopeRecoveryCommand,
 } from "./recovery-guidance.ts";
 
 const DEFAULT_LOG_WINDOW = "45m";
@@ -616,6 +617,14 @@ async function inferRecoveryCheckResult(input: {
       seen,
       results: inferRecoveryCheckResultsFromOutput({ output }),
     });
+
+    if (input.result.name === "hack_global_status") {
+      pushRecoveryCheckResults({
+        target: inferred,
+        seen,
+        results: inferRecoveryCheckResultsFromGlobalStatus({ output }),
+      });
+    }
   }
 
   if (
@@ -679,7 +688,10 @@ async function readCaptureOutput(input: {
 function shouldInferRecoveryFromResult(input: {
   readonly result: CaptureCommandResult;
 }): boolean {
-  if (input.result.name === "hack_doctor_project") {
+  if (
+    input.result.name === "hack_doctor_project" ||
+    input.result.name === "hack_global_status"
+  ) {
     return true;
   }
 
@@ -742,6 +754,24 @@ function inferRecoveryCheckResultsFromOutput(input: {
   return inferred;
 }
 
+function inferRecoveryCheckResultsFromGlobalStatus(input: {
+  readonly output: string;
+}): readonly RecoveryCheckResult[] {
+  const payload = extractJsonStdoutPayload({ output: input.output });
+  if (!payload || isGlobalStatusHealthy(payload)) {
+    return [];
+  }
+
+  return [
+    {
+      name: "global status",
+      status: "warn",
+      message:
+        "Captured global status reports unhealthy global runtime (run: hack global up)",
+    },
+  ];
+}
+
 function extractManualFollowUpItems(input: {
   readonly output: string;
 }): readonly string[] {
@@ -795,6 +825,46 @@ function parseManualFollowUpItem(input: { readonly item: string }): {
   };
 }
 
+function extractJsonStdoutPayload(input: {
+  readonly output: string;
+}): unknown | null {
+  const stdoutMarker = "## stdout\n";
+  const stdoutIndex = input.output.indexOf(stdoutMarker);
+  if (stdoutIndex === -1) {
+    return null;
+  }
+
+  const contentStart = stdoutIndex + stdoutMarker.length;
+  const stderrIndex = input.output.indexOf("\n\n## stderr", contentStart);
+  const rawJson =
+    stderrIndex === -1
+      ? input.output.slice(contentStart)
+      : input.output.slice(contentStart, stderrIndex);
+  const text = rawJson.trim();
+  if (text.length === 0) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function isGlobalStatusHealthy(payload: unknown): boolean {
+  if (!payload || typeof payload !== "object") {
+    return true;
+  }
+
+  const summary = Reflect.get(payload, "summary");
+  if (!summary || typeof summary !== "object") {
+    return true;
+  }
+
+  return Reflect.get(summary, "ok") === true;
+}
+
 function buildRecoveryFollowUpResult(input: {
   readonly name: string;
   readonly logFile: string;
@@ -876,8 +946,13 @@ function renderRecoveryWorkflow(input: {
     guidance: input.guidance,
     projectRoot: input.projectRoot,
   });
-  const projectRoot = input.projectRoot ?? "<repo>";
-  const lines = ["1. Classify:", `   - \`hack doctor --path ${projectRoot}\``];
+  const lines = [
+    "1. Classify:",
+    `   - \`${scopeRecoveryCommand({
+      command: "hack doctor",
+      projectRoot: input.projectRoot,
+    })}\``,
+  ];
   let stepNumber = 2;
 
   if (scoped.temporaryBreakage.length > 0) {
diff --git a/src/commands/recovery-guidance.ts b/src/commands/recovery-guidance.ts
index 6b90dccae..161de4f9b 100644
--- a/src/commands/recovery-guidance.ts
+++ b/src/commands/recovery-guidance.ts
@@ -14,13 +14,8 @@ export type DoctorRecoveryGuidance = {
   readonly capture: readonly string[];
 };
 
-const FIX_CHECKS = new Set([
-  "caddy local ca",
-  "coredns forwarding",
-  "dns:hack",
-  "dns:hack.gy",
-  "dnsmasq:53",
-]);
+const FIX_CHECKS = new Set(["caddy local ca", "dns:hack", "dns:hack.gy"]);
+const SAFE_SHELL_ARG_PATTERN = /^[A-Za-z0-9_./:-]+$/u;
 
 function pushUnique(target: string[], value: string): void {
   if (!target.includes(value)) {
@@ -40,39 +35,32 @@ export function buildDoctorRecoveryGuidance(input: {
       continue;
     }
 
-    if (
-      result.name === "proxy ports" &&
-      result.message.includes("hack global up")
-    ) {
+    if (result.message.includes("hack global up")) {
       pushUnique(temporaryBreakage, "hack global up");
       continue;
     }
 
-    if (
-      result.name === "caddy hosts" &&
-      result.message.includes("hack restart")
-    ) {
+    if (result.message.includes("hack restart")) {
       pushUnique(temporaryBreakage, "hack restart");
       continue;
     }
 
-    if (
-      result.name === "daemon" &&
-      result.message.includes("hack daemon clear")
-    ) {
+    if (result.message.includes("hack daemon clear")) {
       pushUnique(temporaryBreakage, "hack daemon clear");
       pushUnique(temporaryBreakage, "hack daemon start");
       continue;
     }
 
-    if (
-      result.name === "daemon" &&
-      result.message.includes("hack daemon start")
-    ) {
+    if (result.message.includes("hack daemon start")) {
       pushUnique(temporaryBreakage, "hack daemon start");
       continue;
     }
 
+    if (result.message.includes("sudo brew services restart dnsmasq")) {
+      pushUnique(temporaryBreakage, "sudo brew services restart dnsmasq");
+      continue;
+    }
+
     if (
       FIX_CHECKS.has(result.name) ||
       result.message.includes("hack doctor --fix")
@@ -123,12 +111,14 @@ export function buildRecoveryNextSteps(input: {
     guidance: input.guidance,
     projectRoot: input.projectRoot,
   });
-  const projectRoot = input.projectRoot ?? "<repo>";
   const nextSteps: string[] = [];
 
   if (input.includeClassifyStep ?? false) {
     nextSteps.push(
-      `Run \`hack doctor --path ${projectRoot}\` to classify restart versus repair work.`
+      `Run \`${scopeRecoveryCommand({
+        command: "hack doctor",
+        projectRoot: input.projectRoot,
+      })}\` to classify restart versus repair work.`
     );
   }
 
@@ -157,7 +147,7 @@ export function buildRecoveryNextSteps(input: {
   return nextSteps;
 }
 
-function scopeRecoveryCommand(input: {
+export function scopeRecoveryCommand(input: {
   readonly command: string;
   readonly projectRoot: string | null;
 }): string {
@@ -165,18 +155,27 @@ function scopeRecoveryCommand(input: {
   if (!projectRoot) {
     return input.command;
   }
+  const quotedProjectRoot = quoteShellArg(projectRoot);
 
   if (input.command === "hack doctor") {
-    return `hack doctor --path ${projectRoot}`;
+    return `hack doctor --path ${quotedProjectRoot}`;
   }
 
   if (input.command === "hack doctor --fix") {
-    return `hack doctor --fix --path ${projectRoot}`;
+    return `hack doctor --fix --path ${quotedProjectRoot}`;
   }
 
   if (input.command === "hack restart") {
-    return `hack restart --path ${projectRoot}`;
+    return `hack restart --path ${quotedProjectRoot}`;
+  }
+
+  return input.command.replace("<repo>", quotedProjectRoot);
+}
+
+function quoteShellArg(value: string): string {
+  if (SAFE_SHELL_ARG_PATTERN.test(value)) {
+    return value;
   }
 
-  return input.command.replace("<repo>", projectRoot);
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
diff --git a/tests/crash-capture.test.ts b/tests/crash-capture.test.ts
index cf8dfac15..7ab13059f 100644
--- a/tests/crash-capture.test.ts
+++ b/tests/crash-capture.test.ts
@@ -103,9 +103,39 @@ test("crash capture summary infers stale daemon recovery from captured failures"
     globalStatusLog,
     [
       "$ hack global status --json",
-      "exit_code=1",
+      "exit_code=0",
       "",
-      "Caddy not reachable (run: hack global up)",
+      "## stdout",
+      JSON.stringify({
+        caddy: { ok: false, error: "caddy down", services: [] },
+        logging: { ok: true, error: null, services: [] },
+        networks: { ok: true, missing: [], networks: [] },
+        gateway: {
+          gateway_enabled: false,
+          warnings: [],
+          exposures: [],
+          tokens: [],
+          tokens_active: 0,
+          tokens_revoked: 0,
+          tokens_write: 0,
+          tokens_read: 0,
+          config_path: "/tmp/global.json",
+          gateway_url: "http://127.0.0.1:7777",
+          gateway_bind: "127.0.0.1",
+          gateway_port: 7777,
+          allow_writes: false,
+          gateway_projects_enabled: 0,
+        },
+        summary: {
+          ok: false,
+          caddy_ok: false,
+          logging_ok: true,
+          networks_ok: true,
+          gateway_enabled: false,
+        },
+      }),
+      "",
+      "## stderr",
     ].join("\n")
   );
   await Bun.write(
@@ -126,7 +156,7 @@ test("crash capture summary infers stale daemon recovery from captured failures"
         {
           name: "hack_global_status",
           cmd: ["hack", "global", "status", "--json"],
-          exitCode: 1,
+          exitCode: 0,
           file: globalStatusLog,
           bytes: 80,
         },
@@ -265,3 +295,23 @@ test("crash capture readme groups inferred restart actions into sections", () =>
   expect(text).toContain("Verify:");
   expect(text).toContain("If it still fails:");
 });
+
+test("crash capture readme quotes repo paths in recovery commands", () => {
+  const text = renderCrashCaptureReadme({
+    captureRoot: "/tmp/demo/.tmp/crash-capture-1",
+    projectRoot: "/tmp/work repo",
+    recovery: {
+      temporaryBreakage: ["hack restart"],
+      configurationRepair: ["hack doctor --fix"],
+      followUp: [],
+      verify: ["hack doctor"],
+      capture: ["hack crash-capture --path <repo>"],
+    },
+    failedCommands: [],
+  });
+
+  expect(text).toContain("`hack doctor --path '/tmp/work repo'`");
+  expect(text).toContain("`hack restart --path '/tmp/work repo'`");
+  expect(text).toContain("`hack doctor --fix --path '/tmp/work repo'`");
+  expect(text).toContain("`hack crash-capture --path '/tmp/work repo'`");
+});
diff --git a/tests/doctor-command.test.ts b/tests/doctor-command.test.ts
index bc9d8aa66..ff5323ac8 100644
--- a/tests/doctor-command.test.ts
+++ b/tests/doctor-command.test.ts
@@ -1,6 +1,9 @@
 import { expect, test } from "bun:test";
 
-import { buildDoctorRecoveryGuidance } from "../src/commands/recovery-guidance.ts";
+import {
+  buildDoctorRecoveryGuidance,
+  buildRecoveryNextSteps,
+} from "../src/commands/recovery-guidance.ts";
 
 test("doctor guidance distinguishes restartable proxy drift from deeper repair", () => {
   const guidance = buildDoctorRecoveryGuidance({
@@ -32,6 +35,39 @@ test("doctor guidance distinguishes restartable proxy drift from deeper repair",
   expect(guidance.capture).toEqual(["hack crash-capture --path <repo>"]);
 });
 
+test("doctor guidance keeps CoreDNS restartable outages out of doctor --fix", () => {
+  const guidance = buildDoctorRecoveryGuidance({
+    results: [
+      {
+        name: "coredns forwarding",
+        status: "warn",
+        message: "CoreDNS not running (run: hack global up)",
+      },
+    ],
+  });
+
+  expect(guidance.temporaryBreakage).toEqual(["hack global up"]);
+  expect(guidance.configurationRepair).toEqual([]);
+});
+
+test("doctor guidance keeps dnsmasq restarts out of doctor --fix", () => {
+  const guidance = buildDoctorRecoveryGuidance({
+    results: [
+      {
+        name: "dnsmasq:53",
+        status: "warn",
+        message:
+          "No DNS response from 127.0.0.1:53 (run: sudo brew services restart dnsmasq)",
+      },
+    ],
+  });
+
+  expect(guidance.temporaryBreakage).toEqual([
+    "sudo brew services restart dnsmasq",
+  ]);
+  expect(guidance.configurationRepair).toEqual([]);
+});
+
 test("doctor guidance includes daemon recovery for stale local api state", () => {
   const guidance = buildDoctorRecoveryGuidance({
     results: [
@@ -67,3 +103,25 @@ test("doctor guidance keeps unmatched failures as follow-up instead of guessing"
     "gateway tokens: No active tokens (run: hack x gateway token-create)",
   ]);
 });
+
+test("recovery next steps quote repo paths for copy-paste safety", () => {
+  const nextSteps = buildRecoveryNextSteps({
+    guidance: {
+      temporaryBreakage: ["hack restart"],
+      configurationRepair: ["hack doctor --fix"],
+      followUp: [],
+      verify: ["hack doctor"],
+      capture: ["hack crash-capture --path <repo>"],
+    },
+    projectRoot: "/tmp/work repo",
+    includeClassifyStep: true,
+  });
+
+  expect(nextSteps).toEqual([
+    "Run `hack doctor --path '/tmp/work repo'` to classify restart versus repair work.",
+    "Temporary breakage: `hack restart --path '/tmp/work repo'`.",
+    "Configuration repair: `hack doctor --fix --path '/tmp/work repo'`.",
+    "Verify with `hack doctor --path '/tmp/work repo'`.",
+    "If it still fails, run `hack crash-capture --path '/tmp/work repo'` again after the next repro.",
+  ]);
+});

From cd3fdf9da2c261ee8da3fb6d71df41a127a77234 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:52:17 +0000
Subject: [PATCH 048/134] fix: harden linear project artifact reconciliation

---
 .../extensions/linear/commands.ts             | 162 +++++++++--
 .../extensions/linear/project-artifacts.ts    |  12 +-
 tests/linear-commands.test.ts                 | 275 ++++++++++++++++++
 3 files changed, 429 insertions(+), 20 deletions(-)

diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index 6793bbc1a..a191cc71d 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -49,6 +49,7 @@ import {
   type LocalLinearProjectArtifact,
   loadLocalLinearProjectArtifacts,
   materializeLocalLinearProjectArtifact,
+  parseLinearProjectArtifactFile,
   planLinearProjectArtifactChanges,
   resolveLinearProjectArtifactPath,
   serializeLinearProjectArtifactFile,
@@ -2936,24 +2937,45 @@ async function runProjectArtifactCommand(input: {
         return artifacts;
       }
 
+      const localArtifacts = await loadManagedProjectArtifacts({
+        family: input.family,
+        ignoreParseErrors: true,
+        runtime: input.runtime,
+      });
+      if (!localArtifacts.ok) {
+        return localArtifacts;
+      }
+
+      const localByLinearId = new Map(
+        localArtifacts.data
+          .filter((artifact) => artifact.linearId)
+          .map((artifact) => [artifact.linearId as string, artifact])
+      );
+
       let changed = 0;
       const writtenPaths: string[] = [];
       for (const artifact of artifacts.data) {
-        const localArtifact = materializeLocalLinearProjectArtifact({
+        const canonicalArtifact = materializeLocalLinearProjectArtifact({
           projectDir: input.runtime.projectDir,
           artifact,
           ...(input.family === "status-updates"
             ? { statusUpdateState: "published" as const }
             : {}),
         });
-        const wrote = await writeLocalLinearProjectArtifact({
-          artifact: localArtifact,
+        const existingManagedArtifact = artifact.linearId
+          ? localByLinearId.get(artifact.linearId)
+          : undefined;
+        const wrote = await writeManagedProjectArtifactToCanonicalPath({
+          artifact: canonicalArtifact,
+          ...(existingManagedArtifact
+            ? { previousPath: existingManagedArtifact.path }
+            : {}),
         });
         if (!wrote) {
           continue;
         }
         changed += 1;
-        writtenPaths.push(localArtifact.path);
+        writtenPaths.push(canonicalArtifact.path);
       }
 
       return {
@@ -2990,6 +3012,12 @@ async function runProjectArtifactCommand(input: {
         localArtifacts: localArtifacts.data,
         remoteArtifacts: remoteArtifacts.data,
       });
+      if (plan.errors.length > 0) {
+        return {
+          ok: false,
+          error: plan.errors.join("\n"),
+        };
+      }
       return {
         ok: true,
         payload: {
@@ -3055,14 +3083,20 @@ async function runProjectArtifactCommand(input: {
         if (!saved.ok) {
           return saved;
         }
-        const wrote = await writeLocalLinearProjectArtifact({
-          artifact: {
-            ...saved.data,
-            path: artifact.path,
-          },
+        const wrote = await writeManagedProjectArtifactToCanonicalPath({
+          artifact: materializeLocalLinearProjectArtifact({
+            projectDir: input.runtime.projectDir,
+            artifact: saved.data,
+          }),
+          previousPath: artifact.path,
         });
         if (wrote) {
-          writtenPaths.push(artifact.path);
+          writtenPaths.push(
+            resolveLinearProjectArtifactPath({
+              projectDir: input.runtime.projectDir,
+              artifact: saved.data,
+            })
+          );
         }
       }
 
@@ -3075,14 +3109,16 @@ async function runProjectArtifactCommand(input: {
         if (!saved.ok) {
           return saved;
         }
-        const wrote = await writeLocalLinearProjectArtifact({
-          artifact: {
-            ...saved.data,
-            path: entry.local.path,
-          },
+        const nextArtifact = materializeLocalLinearProjectArtifact({
+          projectDir: input.runtime.projectDir,
+          artifact: saved.data,
+        });
+        const wrote = await writeManagedProjectArtifactToCanonicalPath({
+          artifact: nextArtifact,
+          previousPath: entry.local.path,
         });
         if (wrote) {
-          writtenPaths.push(entry.local.path);
+          writtenPaths.push(nextArtifact.path);
         }
       }
 
@@ -3121,12 +3157,23 @@ async function runProjectArtifactCommand(input: {
       return localArtifacts;
     }
 
-    const drafts = localArtifacts.data.filter(
+    const draftArtifacts = localArtifacts.data.filter(
       (artifact) =>
         artifact.kind === "linear-project-status-update" &&
-        isDraftStatusUpdatePath({ path: artifact.path }) &&
-        !artifact.linearId
+        isDraftStatusUpdatePath({ path: artifact.path })
+    );
+    const alreadyPublishedDraft = draftArtifacts.find(
+      (artifact) => artifact.linearId
     );
+    if (alreadyPublishedDraft) {
+      return {
+        ok: false,
+        error:
+          "Publish requires a draft status update without a linearId. Remove the linearId or move the file to published/ first.",
+      };
+    }
+
+    const drafts = draftArtifacts.filter((artifact) => !artifact.linearId);
 
     const movedPaths: Array<{ from: string; to: string }> = [];
     for (const artifact of drafts) {
@@ -3240,6 +3287,7 @@ async function loadManagedProjectArtifacts(input: {
   readonly family: LinearProjectArtifactFamily;
   readonly runtime: ProjectArtifactRuntime;
   readonly path?: string;
+  readonly ignoreParseErrors?: boolean;
 }): Promise<
   | { readonly ok: true; readonly data: readonly LocalLinearProjectArtifact[] }
   | { readonly ok: false; readonly error: string }
@@ -3249,6 +3297,9 @@ async function loadManagedProjectArtifacts(input: {
       ok: true,
       data: await loadLocalLinearProjectArtifacts({
         family: input.family,
+        ...(input.ignoreParseErrors !== undefined
+          ? { ignoreParseErrors: input.ignoreParseErrors }
+          : {}),
         linearProjectId: input.runtime.projectId,
         path: input.path,
         projectDir: input.runtime.projectDir,
@@ -3623,6 +3674,79 @@ async function writeLocalLinearProjectArtifact(input: {
   return true;
 }
 
+async function writeManagedProjectArtifactToCanonicalPath(input: {
+  readonly artifact: LocalLinearProjectArtifact;
+  readonly previousPath?: string;
+}): Promise<boolean> {
+  await assertManagedArtifactPathWritable({
+    artifact: input.artifact,
+    ...(input.previousPath ? { previousPath: input.previousPath } : {}),
+  });
+  const wrote = await writeLocalLinearProjectArtifact({
+    artifact: input.artifact,
+  });
+  if (
+    input.previousPath &&
+    input.previousPath !== input.artifact.path &&
+    (wrote || (await Bun.file(input.artifact.path).exists()))
+  ) {
+    await removeFileIfExists({
+      path: input.previousPath,
+    });
+  }
+  return wrote;
+}
+
+async function assertManagedArtifactPathWritable(input: {
+  readonly artifact: LocalLinearProjectArtifact;
+  readonly previousPath?: string;
+}): Promise<void> {
+  const existingText = await readFileIfExists({
+    path: input.artifact.path,
+  });
+  if (existingText === null) {
+    return;
+  }
+
+  if (input.previousPath && input.previousPath === input.artifact.path) {
+    return;
+  }
+
+  const parsedExisting = parseExistingManagedArtifactAtPath({
+    path: input.artifact.path,
+    text: existingText,
+  });
+  if (!parsedExisting) {
+    throw new Error(
+      `Refusing to overwrite unmanaged file: ${input.artifact.path}`
+    );
+  }
+
+  if (
+    parsedExisting.kind !== input.artifact.kind ||
+    parsedExisting.linearProjectId !== input.artifact.linearProjectId ||
+    parsedExisting.linearId !== input.artifact.linearId
+  ) {
+    throw new Error(
+      `Refusing to overwrite managed file for a different artifact: ${input.artifact.path}`
+    );
+  }
+}
+
+function parseExistingManagedArtifactAtPath(input: {
+  readonly path: string;
+  readonly text: string;
+}): LocalLinearProjectArtifact | null {
+  try {
+    return parseLinearProjectArtifactFile({
+      filePath: input.path,
+      text: input.text,
+    });
+  } catch {
+    return null;
+  }
+}
+
 async function readFileIfExists(input: {
   readonly path: string;
 }): Promise<string | null> {
diff --git a/src/control-plane/extensions/linear/project-artifacts.ts b/src/control-plane/extensions/linear/project-artifacts.ts
index 672a381f2..5651f4d0a 100644
--- a/src/control-plane/extensions/linear/project-artifacts.ts
+++ b/src/control-plane/extensions/linear/project-artifacts.ts
@@ -257,11 +257,13 @@ export const loadLocalLinearProjectArtifacts = async ({
   linearProjectId,
   family,
   path,
+  ignoreParseErrors = false,
 }: {
   readonly projectDir: string;
   readonly linearProjectId: string;
   readonly family: LinearProjectArtifactFamily;
   readonly path?: string;
+  readonly ignoreParseErrors?: boolean;
 }): Promise<readonly LocalLinearProjectArtifact[]> => {
   const targetPath =
     resolveArtifactInputPath({
@@ -290,7 +292,15 @@ export const loadLocalLinearProjectArtifacts = async ({
     left.localeCompare(right)
   )) {
     const text = await Bun.file(filePath).text();
-    const artifact = parseLinearProjectArtifactFile({ filePath, text });
+    let artifact: LocalLinearProjectArtifact;
+    try {
+      artifact = parseLinearProjectArtifactFile({ filePath, text });
+    } catch (error) {
+      if (ignoreParseErrors) {
+        continue;
+      }
+      throw error;
+    }
     if (artifact.linearProjectId !== linearProjectId) {
       continue;
     }
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index 58e66b10a..6b01ade34 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -1642,6 +1642,105 @@ test("runProjectArtifactCommand pulls project documents into repo state", async
   expect(file).toContain("icon: rocket");
 });
 
+test("runProjectArtifactCommand pull refuses to overwrite unmanaged files", async () => {
+  const projectDir = ensureTempDir();
+  const targetPath = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/documents/launch-plan.md"
+  );
+  await mkdir(resolve(targetPath, ".."), { recursive: true });
+  await writeFile(targetPath, "# local scratch notes\n");
+
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "documents",
+    verb: "pull",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectDocuments: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "doc_123",
+              title: "Launch plan",
+              content: "# Launch plan\n",
+              slugId: "launch-plan",
+              archived: false,
+            },
+          ],
+        }),
+      },
+    },
+  });
+
+  expect(result.ok).toBe(false);
+  if (result.ok) {
+    return;
+  }
+
+  expect(result.error).toContain("Refusing to overwrite unmanaged file");
+  expect(await Bun.file(targetPath).text()).toBe("# local scratch notes\n");
+});
+
+test("runProjectArtifactCommand pull reconciles renamed managed files to the canonical path", async () => {
+  const projectDir = ensureTempDir();
+  const documentsDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/documents"
+  );
+  await mkdir(documentsDir, { recursive: true });
+  const oldPath = resolve(documentsDir, "old-plan.md");
+  await writeFile(
+    oldPath,
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: Old plan
+linearId: doc_123
+slug: old-plan
+archived: false
+---
+# Old plan
+`
+  );
+
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "documents",
+    verb: "pull",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectDocuments: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "doc_123",
+              title: "Launch plan",
+              content: "# Launch plan\n",
+              slugId: "launch-plan",
+              archived: false,
+            },
+          ],
+        }),
+      },
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  const newPath = resolve(documentsDir, "launch-plan.md");
+  expect(result.payload.writtenPaths).toEqual([newPath]);
+  expect(await Bun.file(newPath).exists()).toBe(true);
+  expect(await Bun.file(oldPath).exists()).toBe(false);
+});
+
 test("runProjectArtifactCommand plans create update noop and remote-only documents", async () => {
   const projectDir = ensureTempDir();
   const documentsDir = resolve(
@@ -1740,6 +1839,64 @@ archived: false
   });
 });
 
+test("runProjectArtifactCommand plan fails on duplicate managed mappings", async () => {
+  const projectDir = ensureTempDir();
+  const documentsDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/documents"
+  );
+  await mkdir(documentsDir, { recursive: true });
+  await writeFile(
+    resolve(documentsDir, "first.md"),
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: First
+linearId: doc_dup
+slug: first
+archived: false
+---
+# First
+`
+  );
+  await writeFile(
+    resolve(documentsDir, "second.md"),
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: Second
+linearId: doc_dup
+slug: second
+archived: false
+---
+# Second
+`
+  );
+
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "documents",
+    verb: "plan",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectDocuments: async () => ({
+          ok: true as const,
+          data: [],
+        }),
+      },
+    },
+  });
+
+  expect(result.ok).toBe(false);
+  if (result.ok) {
+    return;
+  }
+
+  expect(result.error).toContain('Duplicate local linearId "doc_dup"');
+});
+
 test("runProjectArtifactCommand applies document upserts and writes back linear ids", async () => {
   const projectDir = ensureTempDir();
   const documentsDir = resolve(
@@ -1844,6 +2001,74 @@ archived: false
   expect(createdText).toContain("updatedAt: 2026-03-15T09:00:00.000Z");
 });
 
+test("runProjectArtifactCommand apply rewrites renamed managed documents to the canonical path", async () => {
+  const projectDir = ensureTempDir();
+  const documentsDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/documents"
+  );
+  await mkdir(documentsDir, { recursive: true });
+  const oldPath = resolve(documentsDir, "old-name.md");
+  await writeFile(
+    oldPath,
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: Old name
+linearId: doc_update
+slug: old-name
+archived: false
+---
+# Updated body
+`
+  );
+
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "documents",
+    verb: "apply",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectDocuments: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "doc_update",
+              title: "Old name",
+              content: "# Old body\n",
+              slugId: "old-name",
+              archived: false,
+            },
+          ],
+        }),
+        updateProjectDocument: async ({ documentId }) => ({
+          ok: true as const,
+          data: {
+            id: documentId,
+            title: "New name",
+            content: "# Updated body\n",
+            slugId: "new-name",
+            archived: false,
+            updatedAt: "2026-03-15T10:00:00.000Z",
+          },
+        }),
+      },
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  const newPath = resolve(documentsDir, "new-name.md");
+  expect(result.payload.writtenPaths).toEqual([newPath]);
+  expect(await Bun.file(newPath).exists()).toBe(true);
+  expect(await Bun.file(oldPath).exists()).toBe(false);
+});
+
 test("runProjectArtifactCommand publishes draft status updates and moves them to published", async () => {
   const projectDir = ensureTempDir();
   const draftsDir = resolve(
@@ -1914,6 +2139,56 @@ Still on track for dogfooding.
   expect(publishedText).toContain("updatedAt: 2026-03-14T10:15:00.000Z");
 });
 
+test("runProjectArtifactCommand publish fails for drafts that already have a remote id", async () => {
+  const projectDir = ensureTempDir();
+  const draftsDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/status-updates/drafts"
+  );
+  await mkdir(draftsDir, { recursive: true });
+  const draftPath = resolve(draftsDir, "2026-03-14-weekly.md");
+  await writeFile(
+    draftPath,
+    `---
+kind: linear-project-status-update
+linearProjectId: proj_123
+title: Weekly update
+linearId: update_123
+slug: weekly
+archived: false
+date: 2026-03-14
+health: onTrack
+---
+Still on track for dogfooding.
+`
+  );
+
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "status-updates",
+    verb: "publish",
+    path: draftPath,
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        createProjectUpdate: async () => {
+          throw new Error("should not be called");
+        },
+      },
+    },
+  });
+
+  expect(result.ok).toBe(false);
+  if (result.ok) {
+    return;
+  }
+
+  expect(result.error).toContain(
+    "Publish requires a draft status update without a linearId"
+  );
+});
+
 function ensureTempDir(): string {
   if (!tempDir) {
     throw new Error("Missing temp dir");

From 78cc3ea9c177aa8d5c458eb4510745b0e5111e56 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 05:54:11 +0000
Subject: [PATCH 049/134] docs: expand linear project artifact help

---
 docs/cli.md               | 5 +++--
 src/commands/linear.ts    | 5 +++--
 tests/cli-command.test.ts | 8 +++++---
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index c63bfea3f..528d5b79a 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -658,8 +658,9 @@ Run `hack linear` with no args to see available subcommands.
 
 Examples:
 
-- `hack linear documents pull`
-- `hack linear milestones plan`
+- `hack linear documents list|pull|plan|apply`
+- `hack linear milestones list|pull|plan|apply`
+- `hack linear status-updates list|pull|plan|publish`
 - `hack linear status-updates publish --path .hack/linear/projects/<project-id>/status-updates/drafts/<yyyy-mm-dd>-<slug>.md`
 
 ## Internal commands
diff --git a/src/commands/linear.ts b/src/commands/linear.ts
index b928aabd5..337e2f81f 100644
--- a/src/commands/linear.ts
+++ b/src/commands/linear.ts
@@ -25,8 +25,9 @@ const linearSpec = defineCommand({
     "  hack linear sync-issue --from linear --issue ENG-123",
     "  hack linear sync-issue --from hack --ticket T-00001",
     "  hack linear sync-project --from linear --project-id <linear-project-id>",
-    "  hack linear documents pull",
-    "  hack linear milestones plan",
+    "  hack linear documents list|pull|plan|apply",
+    "  hack linear milestones list|pull|plan|apply",
+    "  hack linear status-updates list|pull|plan|publish",
     "  hack linear status-updates publish --path .hack/linear/projects/<project-id>/status-updates/drafts/<yyyy-mm-dd>-<slug>.md",
     "",
     "Alias for `hack x linear <command>`. Requires extension enabled.",
diff --git a/tests/cli-command.test.ts b/tests/cli-command.test.ts
index 4d0a8fff3..7fca58b7f 100644
--- a/tests/cli-command.test.ts
+++ b/tests/cli-command.test.ts
@@ -66,11 +66,13 @@ test("linear command metadata advertises project artifact workflows", () => {
   expect(resolved.command?.summary).toBe(
     "Linear account connection, issue sync, and project artifact management"
   );
-  expect(resolved.command?.description).toContain("hack linear documents pull");
   expect(resolved.command?.description).toContain(
-    "hack linear milestones plan"
+    "hack linear documents list|pull|plan|apply"
   );
   expect(resolved.command?.description).toContain(
-    "hack linear status-updates publish"
+    "hack linear milestones list|pull|plan|apply"
+  );
+  expect(resolved.command?.description).toContain(
+    "hack linear status-updates list|pull|plan|publish"
   );
 });

From 453fdb73a22c60d6c9355c627fda25c85bdda450 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 16:45:22 +0000
Subject: [PATCH 050/134] fix: honor explicit linear artifact project routing

---
 .../extensions/linear/commands.ts             | 309 ++++++++++++++++--
 tests/linear-commands.test.ts                 |  78 +++++
 2 files changed, 364 insertions(+), 23 deletions(-)

diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index a191cc71d..8595f55ff 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -2814,39 +2814,44 @@ async function handleProjectArtifactFamilyCommand(input: {
   const binding = resolveProjectLinearBinding({
     controlPlaneConfig: input.ctx.controlPlaneConfig,
   });
-  const selectedTarget =
-    (parsed.value.projectId
-      ? findProjectBindingTarget({
-          binding,
-          projectId: parsed.value.projectId,
-        })
-      : null) ??
-    (binding.projectId
-      ? {
-          projectId: binding.projectId,
-          ...(binding.projectName ? { projectName: binding.projectName } : {}),
-          ...(binding.teamId ? { teamId: binding.teamId } : {}),
-          ...(binding.profileId ? { profileId: binding.profileId } : {}),
-        }
-      : null);
-  const projectId = parsed.value.projectId ?? selectedTarget?.projectId;
-  if (!projectId) {
-    input.ctx.logger.error({
-      message:
-        "Missing project id. Pass --project-id, bind a default project, or add additional linked projects first.",
-    });
+  const boundTarget = resolveBoundProjectArtifactTarget({
+    binding,
+    projectId: parsed.value.projectId,
+    projectName: parsed.value.projectName,
+    teamId: parsed.value.teamId,
+  });
+  if (!boundTarget.ok) {
+    input.ctx.logger.error({ message: boundTarget.error });
     return 1;
   }
 
   const runtime = await createSyncRuntime({
     ctx: input.ctx,
-    profileId: parsed.value.profileId ?? selectedTarget?.profileId,
+    profileId:
+      parsed.value.profileId ??
+      boundTarget.target?.profileId ??
+      binding.profileId,
   });
   if (!runtime.ok) {
     input.ctx.logger.error({ message: runtime.error });
     return 1;
   }
 
+  const selectedTarget = await resolveProjectArtifactTarget({
+    binding,
+    profileId: runtime.value.profileId,
+    projectId: parsed.value.projectId,
+    projectName: parsed.value.projectName,
+    teamId: parsed.value.teamId,
+    linear: runtime.value.linear,
+  });
+  if (!selectedTarget.ok) {
+    input.ctx.logger.error({
+      message: selectedTarget.error,
+    });
+    return 1;
+  }
+
   const result = await runProjectArtifactCommand({
     family: input.family,
     verb: parsed.value.verb,
@@ -2855,7 +2860,7 @@ async function handleProjectArtifactFamilyCommand(input: {
       linear: runtime.value.linear,
       profileId: runtime.value.profileId,
       projectDir: input.ctx.project.projectDir,
-      projectId,
+      projectId: selectedTarget.target.projectId,
     },
   });
   if (!result.ok) {
@@ -6674,6 +6679,263 @@ function findProjectBindingTarget(input: {
   );
 }
 
+function resolveBoundProjectArtifactTarget(input: {
+  readonly binding: ResolvedLinearProjectBinding;
+  readonly projectId?: string;
+  readonly projectName?: string;
+  readonly teamId?: string;
+}):
+  | { readonly ok: true; readonly target: LinearProjectBindingTarget | null }
+  | { readonly ok: false; readonly error: string } {
+  const projectId = readOptionalString(input.projectId);
+  const projectName = readOptionalString(input.projectName);
+  const teamId = readOptionalString(input.teamId);
+
+  if (projectId) {
+    const target = findProjectBindingTarget({
+      binding: input.binding,
+      projectId,
+    });
+    if (!target) {
+      return { ok: true, target: null };
+    }
+    return {
+      ok: true,
+      target: {
+        ...target,
+        ...(projectName ? { projectName } : {}),
+        ...(teamId ? { teamId } : {}),
+      },
+    };
+  }
+
+  const selector = createProjectArtifactSelector({
+    projectName,
+    teamId,
+  });
+  if (!selector) {
+    return {
+      ok: true,
+      target: input.binding.projectId
+        ? {
+            projectId: input.binding.projectId,
+            ...(input.binding.projectName
+              ? { projectName: input.binding.projectName }
+              : {}),
+            ...(input.binding.teamId ? { teamId: input.binding.teamId } : {}),
+            ...(input.binding.profileId
+              ? { profileId: input.binding.profileId }
+              : {}),
+          }
+        : null,
+    };
+  }
+
+  const candidates = resolveProjectPullTargets({
+    binding: input.binding,
+  }).filter((target) =>
+    projectArtifactTargetMatchesSelector({ target, selector })
+  );
+  if (candidates.length === 0) {
+    return { ok: true, target: null };
+  }
+  if (candidates.length > 1) {
+    return {
+      ok: false,
+      error: describeAmbiguousProjectArtifactTarget({
+        projectName,
+        teamId,
+        source: "bound",
+      }),
+    };
+  }
+  return {
+    ok: true,
+    target: candidates[0] ?? null,
+  };
+}
+
+async function resolveProjectArtifactTarget(input: {
+  readonly binding: ResolvedLinearProjectBinding;
+  readonly profileId: string;
+  readonly projectId?: string;
+  readonly projectName?: string;
+  readonly teamId?: string;
+  readonly linear: Pick<ProjectArtifactRuntime["linear"], "listProjects">;
+}): Promise<
+  | {
+      readonly ok: true;
+      readonly target: LinearProjectBindingTarget;
+    }
+  | { readonly ok: false; readonly error: string }
+> {
+  const boundTarget = resolveBoundProjectArtifactTarget(input);
+  if (!boundTarget.ok) {
+    return boundTarget;
+  }
+  if (boundTarget.target) {
+    return {
+      ok: true,
+      target: {
+        ...boundTarget.target,
+        profileId: boundTarget.target.profileId ?? input.profileId,
+      },
+    };
+  }
+
+  const projectId = readOptionalString(input.projectId);
+  const projectName = readOptionalString(input.projectName);
+  const teamId = readOptionalString(input.teamId);
+  if (projectId) {
+    return {
+      ok: true,
+      target: {
+        projectId,
+        profileId: input.profileId,
+        ...(projectName ? { projectName } : {}),
+        ...(teamId ? { teamId } : {}),
+      },
+    };
+  }
+
+  const selector = createProjectArtifactSelector({
+    projectName,
+    teamId,
+  });
+  if (!selector) {
+    return {
+      ok: false,
+      error:
+        "Missing project id. Pass --project-id, bind a default project, or add additional linked projects first.",
+    };
+  }
+
+  const projects = await input.linear.listProjects({
+    first: DEFAULT_PROJECT_SYNC_LIMIT,
+  });
+  if (!projects.ok) {
+    return {
+      ok: false,
+      error: projects.error,
+    };
+  }
+
+  const matches = projects.data.filter((project) =>
+    projectArtifactTargetMatchesSelector({
+      target: {
+        projectId: project.id,
+        projectName: project.name,
+        teamId: project.teamId,
+      },
+      selector,
+    })
+  );
+  if (matches.length === 0) {
+    return {
+      ok: false,
+      error: describeMissingProjectArtifactTarget({
+        projectName,
+        teamId,
+      }),
+    };
+  }
+  if (matches.length > 1) {
+    return {
+      ok: false,
+      error: describeAmbiguousProjectArtifactTarget({
+        projectName,
+        teamId,
+        source: "remote",
+      }),
+    };
+  }
+
+  const match = matches[0];
+  if (!match) {
+    return {
+      ok: false,
+      error: describeMissingProjectArtifactTarget({
+        projectName,
+        teamId,
+      }),
+    };
+  }
+  return {
+    ok: true,
+    target: {
+      profileId: input.profileId,
+      projectId: match.id,
+      projectName: match.name,
+      teamId: match.teamId,
+    },
+  };
+}
+
+function createProjectArtifactSelector(input: {
+  readonly projectName?: string;
+  readonly teamId?: string;
+}): { readonly projectName?: string; readonly teamId?: string } | null {
+  const projectName = readOptionalString(input.projectName);
+  const teamId = readOptionalString(input.teamId);
+  if (!(projectName || teamId)) {
+    return null;
+  }
+  return {
+    ...(projectName ? { projectName: projectName.toLowerCase() } : {}),
+    ...(teamId ? { teamId: teamId.toLowerCase() } : {}),
+  };
+}
+
+function projectArtifactTargetMatchesSelector(input: {
+  readonly target: Pick<
+    LinearProjectBindingTarget,
+    "projectName" | "teamId" | "projectId"
+  >;
+  readonly selector: {
+    readonly projectName?: string;
+    readonly teamId?: string;
+  };
+}): boolean {
+  if (
+    input.selector.projectName &&
+    readOptionalString(input.target.projectName)?.toLowerCase() !==
+      input.selector.projectName
+  ) {
+    return false;
+  }
+  if (
+    input.selector.teamId &&
+    readOptionalString(input.target.teamId)?.toLowerCase() !==
+      input.selector.teamId
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function describeAmbiguousProjectArtifactTarget(input: {
+  readonly projectName?: string;
+  readonly teamId?: string;
+  readonly source: "bound" | "remote";
+}): string {
+  const parts = [
+    input.projectName ? `project name "${input.projectName}"` : null,
+    input.teamId ? `team id "${input.teamId}"` : null,
+  ].filter((part): part is string => Boolean(part));
+  return `Multiple ${input.source} Linear projects match ${parts.join(" and ")}. Pass --project-id to disambiguate.`;
+}
+
+function describeMissingProjectArtifactTarget(input: {
+  readonly projectName?: string;
+  readonly teamId?: string;
+}): string {
+  const parts = [
+    input.projectName ? `project name "${input.projectName}"` : null,
+    input.teamId ? `team id "${input.teamId}"` : null,
+  ].filter((part): part is string => Boolean(part));
+  return `No Linear project matches ${parts.join(" and ")}. Pass --project-id or update the project binding.`;
+}
+
 async function resolveProjectBindingDetails(input: {
   readonly controlPlaneConfig: ExtensionCommandContext["controlPlaneConfig"];
   readonly profileId?: string;
@@ -9643,6 +9905,7 @@ export const __testOnly = {
   parseSyncProjectArgs,
   parseUpsertAssigneeMappingArgs,
   parseUpsertAutosyncSubscriptionArgs,
+  resolveProjectArtifactTarget,
   selectLinearCommentsToAppend,
   selectTicketCommentsToPush,
   shouldFallbackConnectToOAuth,
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index 6b01ade34..b8679e773 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -414,6 +414,84 @@ test("findProjectBindingTarget resolves additional linked projects by id", () =>
   });
 });
 
+test("resolveProjectArtifactTarget matches a bound project by explicit name and team", async () => {
+  const resolved = await __testOnly.resolveProjectArtifactTarget({
+    binding: {
+      profileId: "work",
+      projectId: "proj_default",
+      projectName: "Default",
+      teamId: "team_default",
+      additionalProjects: [
+        {
+          profileId: "ops",
+          projectId: "proj_ops",
+          projectName: "Operations",
+          teamId: "team_ops",
+        },
+      ],
+    },
+    profileId: "work",
+    projectName: "Operations",
+    teamId: "team_ops",
+    linear: {
+      listProjects: async () => {
+        throw new Error("should not look up remote projects");
+      },
+    },
+  });
+
+  expect(resolved).toEqual({
+    ok: true,
+    target: {
+      profileId: "ops",
+      projectId: "proj_ops",
+      projectName: "Operations",
+      teamId: "team_ops",
+    },
+  });
+});
+
+test("resolveProjectArtifactTarget falls back to remote lookup for explicit project names", async () => {
+  const resolved = await __testOnly.resolveProjectArtifactTarget({
+    binding: {
+      profileId: "work",
+      additionalProjects: [],
+    },
+    profileId: "work",
+    projectName: "Roadmap",
+    teamId: "team_strategy",
+    linear: {
+      listProjects: async () => ({
+        ok: true as const,
+        data: [
+          {
+            id: "proj_strategy",
+            name: "Roadmap",
+            teamId: "team_strategy",
+            teamKey: "STRAT",
+          },
+          {
+            id: "proj_other",
+            name: "Roadmap",
+            teamId: "team_other",
+            teamKey: "OPS",
+          },
+        ],
+      }),
+    },
+  });
+
+  expect(resolved).toEqual({
+    ok: true,
+    target: {
+      profileId: "work",
+      projectId: "proj_strategy",
+      projectName: "Roadmap",
+      teamId: "team_strategy",
+    },
+  });
+});
+
 test("connect falls back to oauth when no token input exists", () => {
   const envKey = "HACK_LINEAR_TEST_TOKEN";
   const previous = process.env[envKey];

From 8fd8107a1894092ec1abd7f19f7645eb761b35ae Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 16:46:39 +0000
Subject: [PATCH 051/134] refactor: simplify linear artifact target selection

---
 .../extensions/linear/commands.ts             | 82 +++++++++++++------
 1 file changed, 58 insertions(+), 24 deletions(-)

diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index 8595f55ff..7aae1945f 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -6696,16 +6696,15 @@ function resolveBoundProjectArtifactTarget(input: {
       binding: input.binding,
       projectId,
     });
-    if (!target) {
-      return { ok: true, target: null };
-    }
     return {
       ok: true,
-      target: {
-        ...target,
-        ...(projectName ? { projectName } : {}),
-        ...(teamId ? { teamId } : {}),
-      },
+      target: target
+        ? applyExplicitProjectArtifactOverrides({
+            target,
+            projectName,
+            teamId,
+          })
+        : null,
     };
   }
 
@@ -6716,26 +6715,16 @@ function resolveBoundProjectArtifactTarget(input: {
   if (!selector) {
     return {
       ok: true,
-      target: input.binding.projectId
-        ? {
-            projectId: input.binding.projectId,
-            ...(input.binding.projectName
-              ? { projectName: input.binding.projectName }
-              : {}),
-            ...(input.binding.teamId ? { teamId: input.binding.teamId } : {}),
-            ...(input.binding.profileId
-              ? { profileId: input.binding.profileId }
-              : {}),
-          }
-        : null,
+      target: buildDefaultProjectBindingTarget({
+        binding: input.binding,
+      }),
     };
   }
 
-  const candidates = resolveProjectPullTargets({
+  const candidates = findBoundProjectArtifactTargetsBySelector({
     binding: input.binding,
-  }).filter((target) =>
-    projectArtifactTargetMatchesSelector({ target, selector })
-  );
+    selector,
+  });
   if (candidates.length === 0) {
     return { ok: true, target: null };
   }
@@ -6755,6 +6744,51 @@ function resolveBoundProjectArtifactTarget(input: {
   };
 }
 
+function applyExplicitProjectArtifactOverrides(input: {
+  readonly target: LinearProjectBindingTarget;
+  readonly projectName?: string;
+  readonly teamId?: string;
+}): LinearProjectBindingTarget {
+  return {
+    ...input.target,
+    ...(input.projectName ? { projectName: input.projectName } : {}),
+    ...(input.teamId ? { teamId: input.teamId } : {}),
+  };
+}
+
+function buildDefaultProjectBindingTarget(input: {
+  readonly binding: ResolvedLinearProjectBinding;
+}): LinearProjectBindingTarget | null {
+  if (!input.binding.projectId) {
+    return null;
+  }
+  return {
+    projectId: input.binding.projectId,
+    ...(input.binding.projectName
+      ? { projectName: input.binding.projectName }
+      : {}),
+    ...(input.binding.teamId ? { teamId: input.binding.teamId } : {}),
+    ...(input.binding.profileId ? { profileId: input.binding.profileId } : {}),
+  };
+}
+
+function findBoundProjectArtifactTargetsBySelector(input: {
+  readonly binding: ResolvedLinearProjectBinding;
+  readonly selector: {
+    readonly projectName?: string;
+    readonly teamId?: string;
+  };
+}): readonly LinearProjectBindingTarget[] {
+  return resolveProjectPullTargets({
+    binding: input.binding,
+  }).filter((target) =>
+    projectArtifactTargetMatchesSelector({
+      target,
+      selector: input.selector,
+    })
+  );
+}
+
 async function resolveProjectArtifactTarget(input: {
   readonly binding: ResolvedLinearProjectBinding;
   readonly profileId: string;

From 7384d8e9d4d8c5f5b72257e901a227fc06840e31 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 16:48:11 +0000
Subject: [PATCH 052/134] fix: keep root help aligned with docs ia

---
 README.md              | 4 ++--
 src/cli/help.ts        | 5 +++++
 tests/cli-help.test.ts | 8 ++++++++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 3c134f4f4..40bd39448 100644
--- a/README.md
+++ b/README.md
@@ -101,7 +101,7 @@ instead of treating Linear as a separate universe.
 
 - Main surface: `hack linear ...`
 - Common use: connect a profile, bind a project, sync issues or project state
-- Reference: [docs/integrations.md](docs/integrations.md)
+- Reference: [docs/guides/linear-integration-architecture.md](docs/guides/linear-integration-architecture.md)
 
 ### Tickets
 
@@ -146,7 +146,7 @@ Beta surfaces are intentionally separate:
 Reference surfaces:
 
 - Extensions and SDK: [docs/extensions.md](docs/extensions.md)
-- Gateway API: [docs/gateway-api.md](docs/gateway-api.md)
+- Gateway API (Beta): [docs/gateway-api.md](docs/gateway-api.md)
 - Architecture: [docs/architecture.md](docs/architecture.md)
 
 ## `hack help` guide
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 09bd2834b..b943062ca 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -185,6 +185,11 @@ function groupRootEntries(cli: CliSpec): Map<CliGroup, RootEntry[]> {
 
   for (const cmd of cli.commands) {
     if (cmd.expandInRootHelp && cmd.subcommands.length > 0) {
+      push(cmd.group, {
+        group: cmd.group,
+        invocation: buildInvocation(cli.name, [cmd.name], cmd),
+        summary: cmd.summary,
+      });
       for (const sub of cmd.subcommands) {
         const invocation = buildInvocation(cli.name, [cmd.name, sub.name], sub);
         push(cmd.group, { group: cmd.group, invocation, summary: sub.summary });
diff --git a/tests/cli-help.test.ts b/tests/cli-help.test.ts
index c0f3af68b..4a614b9d1 100644
--- a/tests/cli-help.test.ts
+++ b/tests/cli-help.test.ts
@@ -23,6 +23,12 @@ test("root help leads with core promises and separates core from beta surfaces",
   expect(help).toMatch(
     /hack tickets(?: \[args\.\.\.\])?\s+Track repo-local work in git-backed tickets/
   );
+  expect(help).toMatch(
+    /hack projects\s+Show all projects \(registry \+ running docker compose\)/
+  );
+  expect(help).toMatch(
+    /hack projects prune\s+Remove missing registry entries and stop orphaned containers/
+  );
 
   expect(help.indexOf("Core workflows:")).toBeLessThan(
     help.indexOf("Beta workflows:")
@@ -49,4 +55,6 @@ test("markdown help preserves the core offer and command grouping", () => {
   expect(help).toContain("### Beta workflows");
   expect(help).toContain("### Extension commands");
   expect(help).toContain("`hack auth`");
+  expect(help).toContain("`hack projects`");
+  expect(help).toContain("`hack projects prune`");
 });

From 10430e3838b599248c106608a93d6a57616d2fa9 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 16:48:34 +0000
Subject: [PATCH 053/134] chore(env): tighten managed artifact schema contract

---
 docs/env.md                                   |   4 +-
 ...able-project-env-artifact-schema-design.md |   3 +-
 src/templates.ts                              |   3 +
 tests/env-backend-command.test.ts             | 157 +++++++++---------
 tests/project-config-schema.test.ts           |   2 +
 5 files changed, 92 insertions(+), 77 deletions(-)

diff --git a/docs/env.md b/docs/env.md
index 6dc012dd8..06b396f14 100644
--- a/docs/env.md
+++ b/docs/env.md
@@ -111,13 +111,15 @@ Local compatibility rules:
 - neither compatibility target stores descriptions, service scope, timestamps, or actor metadata
 - compatibility targets are derived outputs and may be regenerated from the managed artifact at any time
 
-CLI behavior when a managed artifact is active:
+Planned CLI behavior when a managed artifact is active:
 
 1. Reads validate artifact keys against `.hack/hack.env.json` when present.
 2. Reads report artifact intent, local materialization state, and drift between them.
 3. `hack env set` mutates the canonical artifact first, then materializes the entry to `.hack/.env` or the configured secret backend based on `value.kind`.
 4. If an entry changes kind, Hack removes stale local state from the old compatibility target before writing the new one.
 
+This behavior is design intent for the managed artifact workflow; it is not fully implemented by the current CLI yet.
+
 See [docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md](plans/2026-03-13-portable-project-env-artifact-schema-design.md) for the full design rationale and implementation boundary.
 
 ## CLI
diff --git a/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md b/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md
index 488f98861..c95aedaad 100644
--- a/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md
+++ b/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md
@@ -295,9 +295,10 @@ Rules:
 
 - reject unknown schema versions
 - reject entries without a valid uppercase env key
-- reject duplicate keys inside one artifact
+- reject duplicate keys inside one artifact during parser/CLI validation, since the JSON Schema cannot express key uniqueness within an array of objects
 - reject invalid `value.kind` values
 - reject non-array `services` values other than `null`/omitted
+- reject empty `services` arrays
 - sort and de-duplicate service names at serialization boundaries
 - warn, rather than silently discard, when artifact keys are not declared in `.hack/hack.env.json`
 - require explicit confirmation before applying artifact entries that are unknown to the contract
diff --git a/src/templates.ts b/src/templates.ts
index b46b8365d..e35c3db9d 100644
--- a/src/templates.ts
+++ b/src/templates.ts
@@ -693,6 +693,8 @@ export function renderProjectManagedEnvSchemaJson(): string {
       },
       entries: {
         type: "array",
+        description:
+          "Managed env entries sorted by key. Duplicate keys must be rejected by artifact parsers and writers.",
         items: {
           type: "object",
           additionalProperties: false,
@@ -718,6 +720,7 @@ export function renderProjectManagedEnvSchemaJson(): string {
                 { type: "null" },
                 {
                   type: "array",
+                  minItems: 1,
                   items: { type: "string", minLength: 1 },
                   uniqueItems: true,
                 },
diff --git a/tests/env-backend-command.test.ts b/tests/env-backend-command.test.ts
index bd67629e3..36f7702b8 100644
--- a/tests/env-backend-command.test.ts
+++ b/tests/env-backend-command.test.ts
@@ -177,86 +177,93 @@ test("env backend use cloud requires provider and stores cloud settings", async
   expect(json.cloud.secretPrefix).toBe("hack-cli");
 });
 
-test("env set --secret stores value using encrypted backend", async () => {
-  if (!tempDir) {
-    throw new Error("Missing temp dir");
-  }
-  process.env.HACK_SECRETS_FILE_KEY = "env-backend-command-key";
-  const projectRoot = resolve(tempDir, "repo");
-  const projectDir = resolve(projectRoot, ".hack");
-  await mkdir(projectDir, { recursive: true });
-  await writeFile(resolve(projectDir, "docker-compose.yml"), "services: {}\n");
-  await writeFile(
-    resolve(projectDir, "hack.config.json"),
-    `${JSON.stringify(
-      {
-        name: "env-backend-project",
-        controlPlane: {
-          secrets: {
-            backend: "encrypted_file",
-            encryptedFile: {
-              path: resolve(tempDir, "secrets.enc.json"),
+test(
+  "env set --secret stores value using encrypted backend",
+  async () => {
+    if (!tempDir) {
+      throw new Error("Missing temp dir");
+    }
+    process.env.HACK_SECRETS_FILE_KEY = "env-backend-command-key";
+    const projectRoot = resolve(tempDir, "repo");
+    const projectDir = resolve(projectRoot, ".hack");
+    await mkdir(projectDir, { recursive: true });
+    await writeFile(
+      resolve(projectDir, "docker-compose.yml"),
+      "services: {}\n"
+    );
+    await writeFile(
+      resolve(projectDir, "hack.config.json"),
+      `${JSON.stringify(
+        {
+          name: "env-backend-project",
+          controlPlane: {
+            secrets: {
+              backend: "encrypted_file",
+              encryptedFile: {
+                path: resolve(tempDir, "secrets.enc.json"),
+              },
             },
           },
         },
-      },
-      null,
-      2
-    )}\n`
-  );
-  await writeFile(
-    resolve(projectDir, "hack.env.json"),
-    `${JSON.stringify(
-      {
-        version: 1,
-        vars: [
-          {
-            key: "API_KEY",
-            required: false,
-            source: "keychain",
-          },
-        ],
-      },
-      null,
-      2
-    )}\n`
-  );
+        null,
+        2
+      )}\n`
+    );
+    await writeFile(
+      resolve(projectDir, "hack.env.json"),
+      `${JSON.stringify(
+        {
+          version: 1,
+          vars: [
+            {
+              key: "API_KEY",
+              required: false,
+              source: "keychain",
+            },
+          ],
+        },
+        null,
+        2
+      )}\n`
+    );
 
-  const setResult = await runHack({
-    args: ["env", "set", "--secret", "API_KEY=super-secret"],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-      HACK_SECRETS_FILE_KEY: "env-backend-command-key",
-    },
-    cwd: projectRoot,
-  });
-  expect(setResult.exitCode).toBe(0);
-  expect(`${setResult.stdout}\n${setResult.stderr}`).toContain(
-    "encrypted_file"
-  );
+    const setResult = await runHack({
+      args: ["env", "set", "--secret", "API_KEY=super-secret"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+        HACK_SECRETS_FILE_KEY: "env-backend-command-key",
+      },
+      cwd: projectRoot,
+    });
+    expect(setResult.exitCode).toBe(0);
+    expect(`${setResult.stdout}\n${setResult.stderr}`).toContain(
+      "encrypted_file"
+    );
 
-  const listResult = await runHack({
-    args: ["env", "list", "--show-secrets", "--json"],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-      HACK_SECRETS_FILE_KEY: "env-backend-command-key",
-    },
-    cwd: projectRoot,
-  });
-  expect(listResult.exitCode).toBe(0);
-  const listJson = JSON.parse(listResult.stdout) as {
-    readonly vars: ReadonlyArray<{
-      readonly key: string;
-      readonly value: string | null;
-      readonly source: string;
-    }>;
-  };
-  const apiKey = listJson.vars.find((entry) => entry.key === "API_KEY");
-  expect(apiKey?.source).toBe("keychain");
-  expect(apiKey?.value).toBe("super-secret");
-});
+    const listResult = await runHack({
+      args: ["env", "list", "--show-secrets", "--json"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+        HACK_SECRETS_FILE_KEY: "env-backend-command-key",
+      },
+      cwd: projectRoot,
+    });
+    expect(listResult.exitCode).toBe(0);
+    const listJson = JSON.parse(listResult.stdout) as {
+      readonly vars: ReadonlyArray<{
+        readonly key: string;
+        readonly value: string | null;
+        readonly source: string;
+      }>;
+    };
+    const apiKey = listJson.vars.find((entry) => entry.key === "API_KEY");
+    expect(apiKey?.source).toBe("keychain");
+    expect(apiKey?.value).toBe("super-secret");
+  },
+  { timeout: 20_000 }
+);
 
 async function runHack(input: {
   readonly args: readonly string[];
diff --git a/tests/project-config-schema.test.ts b/tests/project-config-schema.test.ts
index 69cebb781..4640bad90 100644
--- a/tests/project-config-schema.test.ts
+++ b/tests/project-config-schema.test.ts
@@ -77,6 +77,7 @@ test("managed env schema models entry kind, metadata, and service scope", () =>
   });
 
   const entries = properties.entries as Record<string, unknown>;
+  expect(entries.description).toContain("Duplicate keys must be rejected");
   const entry = entries.items as Record<string, unknown>;
   expect(entry.additionalProperties).toBe(false);
   expect(entry.required).toEqual(["key", "value", "required"]);
@@ -95,6 +96,7 @@ test("managed env schema models entry kind, metadata, and service scope", () =>
     { type: "null" },
     {
       type: "array",
+      minItems: 1,
       items: { type: "string", minLength: 1 },
       uniqueItems: true,
     },

From 3c512b9d2cf54fd9d79f077bbb73e8a019d5627a Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 16:50:04 +0000
Subject: [PATCH 054/134] docs: clarify linear project artifact targeting

---
 .../guides/linear-integration-architecture.md | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/guides/linear-integration-architecture.md b/docs/guides/linear-integration-architecture.md
index 14a3ec219..afae90280 100644
--- a/docs/guides/linear-integration-architecture.md
+++ b/docs/guides/linear-integration-architecture.md
@@ -83,6 +83,44 @@ These artifacts do not live in `hack.config.json` blobs or direct one-shot CLI f
 a dedicated repo tree under `.hack/linear/projects/<project-id>/` and use explicit `pull`, `plan`,
 and `apply`/`publish` workflows.
 
+### Command surface
+
+- `hack linear documents list|pull|plan|apply`
+- `hack linear milestones list|pull|plan|apply`
+- `hack linear status-updates list|pull|plan|publish`
+
+### Target selection
+
+Project artifact commands share the same targeting flags:
+
+- `--profile`
+- `--project-id`
+- `--project-name`
+- `--team-id`
+- `--path`
+- `--json`
+
+Resolution rules:
+
+1. `--project-id` wins when provided.
+2. Otherwise, Hack first tries to match `--project-name` and `--team-id` against the repo's bound
+   project plus any additional linked projects.
+3. If no bound project matches, Hack queries Linear projects for the selected profile and resolves a
+   unique match by `--project-name` and optional `--team-id`.
+4. If multiple projects match, the command fails and requires `--project-id`.
+5. If no explicit targeting flags are present, Hack uses the repo's default bound Linear project.
+
+### Sync rules
+
+- `list` only reads remote state.
+- `pull` writes repo-managed files from remote state.
+- `plan` shows create/update/noop/remote-only work without mutating Linear.
+- `apply` is only valid for upsertable artifacts: documents and milestones.
+- `publish` is only valid for append-only status updates.
+- Local file removal never archives or deletes remote artifacts implicitly.
+- Status updates are immutable once published; drafts move from `drafts/` to `published/` after a
+  successful publish.
+
 Design + implementation details:
 - `docs/plans/2026-03-14-linear-project-artifacts-design.md`
 - `docs/plans/2026-03-14-linear-project-artifacts-plan.md`

From 0042167d90648f66c34ef26e4562d346bb7c7550 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 16:50:05 +0000
Subject: [PATCH 055/134] fix(auth): widen org plugin session status typing

---
 services/auth-broker/src/modules/orgs/plugin.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/services/auth-broker/src/modules/orgs/plugin.ts b/services/auth-broker/src/modules/orgs/plugin.ts
index 35e16af87..e44a67ffb 100644
--- a/services/auth-broker/src/modules/orgs/plugin.ts
+++ b/services/auth-broker/src/modules/orgs/plugin.ts
@@ -579,7 +579,7 @@ export function createOrgsPlugin(input: {
 async function requireSession(input: {
   readonly runtime: BetterAuthRuntime;
   readonly request: Request;
-  readonly set: { status?: number };
+  readonly set: { status?: number | string };
 }) {
   const session = await resolveBetterAuthSession({
     runtime: input.runtime,

From ed3737ad9f03cc2e3029bbeab8a135312e815036 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 16:56:45 +0000
Subject: [PATCH 056/134] docs(readme): fix linear sync example

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ca919d4f8..39dcb24cd 100644
--- a/README.md
+++ b/README.md
@@ -55,7 +55,7 @@ hack tickets setup
 hack tickets create --title "Investigate flaky auth flow"
 hack tickets list
 hack linear project-bind --project-id "<linear-project-id>"
-hack linear sync-project --from linear
+hack linear sync-project --from linear --project-id "<linear-project-id>"
 ```
 
 Docs:

From f523440cdf066298bf537d3f7c26bd37d86998c2 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:01:02 +0000
Subject: [PATCH 057/134] fix: normalize linear prerequisite aliases

---
 docs/guides/prerequisite-detection-matrix.md |  3 +++
 src/cli/prerequisites.ts                     | 16 +++++++++++--
 tests/prerequisites-matrix.test.ts           | 24 ++++++++++++++++++++
 3 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/docs/guides/prerequisite-detection-matrix.md b/docs/guides/prerequisite-detection-matrix.md
index 10f72e2bd..b4ca50619 100644
--- a/docs/guides/prerequisite-detection-matrix.md
+++ b/docs/guides/prerequisite-detection-matrix.md
@@ -150,6 +150,9 @@ linear set-subscription
 linear remove-subscription
 ```
 
+`hack linear ...` entries also apply to the equivalent `hack x linear ...`
+alias path.
+
 ## Notes for Follow-on Implementation
 
 - Preserve the current distinction between diagnostics and actions. Status commands should not disappear behind setup wizards.
diff --git a/src/cli/prerequisites.ts b/src/cli/prerequisites.ts
index da1c536a2..4d6cc40ee 100644
--- a/src/cli/prerequisites.ts
+++ b/src/cli/prerequisites.ts
@@ -661,20 +661,32 @@ export const COMMANDS_WITH_LOCAL_PREREQUISITE_HANDLING = [
   },
 ] as const satisfies readonly LocalPrerequisiteHandling[];
 
+function normalizePrerequisiteCommand(input: {
+  readonly command: string;
+}): string {
+  if (!input.command.startsWith("x linear")) {
+    return input.command;
+  }
+
+  return input.command.slice(2);
+}
+
 export function getCommandPrerequisiteContracts(input: {
   readonly command: string;
 }): readonly CommandPrerequisiteContract[] {
+  const command = normalizePrerequisiteCommand({ command: input.command });
   return COMMAND_PREREQUISITE_CONTRACTS.filter((contract) =>
-    contract.commands.includes(input.command)
+    contract.commands.includes(command)
   );
 }
 
 export function getLocalPrerequisiteHandling(input: {
   readonly command: string;
 }): LocalPrerequisiteHandling | null {
+  const command = normalizePrerequisiteCommand({ command: input.command });
   return (
     COMMANDS_WITH_LOCAL_PREREQUISITE_HANDLING.find(
-      (entry) => entry.command === input.command
+      (entry) => entry.command === command
     ) ?? null
   );
 }
diff --git a/tests/prerequisites-matrix.test.ts b/tests/prerequisites-matrix.test.ts
index 693aef8eb..008c6679b 100644
--- a/tests/prerequisites-matrix.test.ts
+++ b/tests/prerequisites-matrix.test.ts
@@ -109,6 +109,24 @@ test("status-style auth commands warn instead of intercepting missing auth", ()
   );
 });
 
+test("x linear aliases resolve to the shared Linear prerequisite contracts", () => {
+  const [linearStatus] = getCommandPrerequisiteContracts({
+    command: "linear status",
+  });
+  const [xLinearStatus] = getCommandPrerequisiteContracts({
+    command: "x linear status",
+  });
+  const [linearSyncIssue] = getCommandPrerequisiteContracts({
+    command: "linear sync-issue",
+  });
+  const [xLinearSyncIssue] = getCommandPrerequisiteContracts({
+    command: "x linear sync-issue",
+  });
+
+  expect(xLinearStatus).toEqual(linearStatus);
+  expect(xLinearSyncIssue).toEqual(linearSyncIssue);
+});
+
 test("action commands escalate to guidance for missing integration auth", () => {
   const [githubAction] = getCommandPrerequisiteContracts({
     command: "x github pr-upsert",
@@ -150,6 +168,9 @@ test("cleanup and local-config commands stay out of shared prerequisite intercep
   expect(
     getCommandPrerequisiteContracts({ command: "linear project-unlink" })
   ).toEqual([]);
+  expect(
+    getCommandPrerequisiteContracts({ command: "x linear disconnect" })
+  ).toEqual([]);
 });
 
 test("major setup commands can be explicitly excluded from shared interception", () => {
@@ -170,6 +191,9 @@ test("major setup commands can be explicitly excluded from shared interception",
   expect(
     getLocalPrerequisiteHandling({ command: "linear setup" })?.reason
   ).toContain("local project wiring command");
+  expect(
+    getLocalPrerequisiteHandling({ command: "x linear setup" })?.reason
+  ).toContain("local project wiring command");
 });
 
 test("broker-backed linear commands guide through Hack auth", () => {

From f67c628a8410476a38b2c08053d95ed6bdc740fb Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:06:07 +0000
Subject: [PATCH 058/134] HACK-428: checkpoint merge prep

---
 src/cli/help.ts        | 10 ++++++++++
 tests/cli-help.test.ts |  9 +++++++++
 2 files changed, 19 insertions(+)

diff --git a/src/cli/help.ts b/src/cli/help.ts
index b943062ca..4fc15e443 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -225,6 +225,11 @@ function renderCommandHelp(
   lines.push(`  ${invocation} [options]`);
   lines.push("");
 
+  if (command.group === "Beta") {
+    lines.push("Status: Beta workflow");
+    lines.push("");
+  }
+
   if (command.description) {
     lines.push(command.description);
     lines.push("");
@@ -275,6 +280,11 @@ function renderCommandHelpMarkdown(
   lines.push("```");
   lines.push("");
 
+  if (command.group === "Beta") {
+    lines.push("> Status: Beta workflow.");
+    lines.push("");
+  }
+
   if (command.description) {
     lines.push(mdEscape(command.description));
     lines.push("");
diff --git a/tests/cli-help.test.ts b/tests/cli-help.test.ts
index 4a614b9d1..6ce4fa30f 100644
--- a/tests/cli-help.test.ts
+++ b/tests/cli-help.test.ts
@@ -58,3 +58,12 @@ test("markdown help preserves the core offer and command grouping", () => {
   expect(help).toContain("`hack projects`");
   expect(help).toContain("`hack projects prune`");
 });
+
+test("beta subcommand help stays visibly labeled beta", () => {
+  const help = renderHelpForPath(CLI_SPEC, ["remote", "setup"]);
+  const markdown = renderHelpMarkdownForPath(CLI_SPEC, ["remote", "setup"]);
+
+  expect(help).toContain("hack remote setup");
+  expect(help).toContain("Status: Beta workflow");
+  expect(markdown).toContain("> Status: Beta workflow.");
+});

From 0a58f398049b2c3bf53a5372976580fc26952dbd Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:06:51 +0000
Subject: [PATCH 059/134] test: cover linear milestone artifact commands

---
 tests/linear-commands.test.ts | 179 ++++++++++++++++++++++++++++++++++
 1 file changed, 179 insertions(+)

diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index b8679e773..027cf60f0 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -2147,6 +2147,185 @@ archived: false
   expect(await Bun.file(oldPath).exists()).toBe(false);
 });
 
+test("runProjectArtifactCommand pulls project milestones into repo state", async () => {
+  const projectDir = ensureTempDir();
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "milestones",
+    verb: "pull",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectMilestones: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "milestone_123",
+              title: "Private beta",
+              description: "Ship the beta cohort.\n",
+              status: "pending",
+              targetDate: "2026-04-01",
+              sortOrder: 7,
+              archived: false,
+              updatedAt: "2026-03-14T10:00:00.000Z",
+            },
+          ],
+        }),
+      },
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(result.payload.changed).toBe(1);
+  expect(result.payload.writtenPaths).toEqual([
+    resolve(
+      projectDir,
+      ".hack/linear/projects/proj_123/milestones/private-beta.md"
+    ),
+  ]);
+
+  const file = await Bun.file(result.payload.writtenPaths[0] ?? "").text();
+  expect(file).toContain("kind: linear-project-milestone");
+  expect(file).toContain("linearId: milestone_123");
+  expect(file).toContain("targetDate: 2026-04-01");
+  expect(file).toContain("state: pending");
+});
+
+test("runProjectArtifactCommand applies milestone upserts and writes back linear ids", async () => {
+  const projectDir = ensureTempDir();
+  const milestonesDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/milestones"
+  );
+  await mkdir(milestonesDir, { recursive: true });
+  await writeFile(
+    resolve(milestonesDir, "private-beta.md"),
+    `---
+kind: linear-project-milestone
+linearProjectId: proj_123
+title: Private beta
+slug: private-beta
+targetDate: 2026-04-01
+state: pending
+archived: false
+---
+Ship the beta cohort.
+`
+  );
+  await writeFile(
+    resolve(milestonesDir, "launch.md"),
+    `---
+kind: linear-project-milestone
+linearProjectId: proj_123
+title: Launch
+linearId: milestone_launch
+slug: launch
+targetDate: 2026-05-01
+state: planned
+archived: false
+---
+Prepare launch checklist.
+`
+  );
+
+  const createCalls: string[] = [];
+  const updateCalls: string[] = [];
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "milestones",
+    verb: "apply",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectMilestones: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "milestone_launch",
+              title: "Launch",
+              description: "Old launch notes.\n",
+              status: "planned",
+              targetDate: "2026-05-01",
+              archived: false,
+            },
+          ],
+        }),
+        createProjectMilestone: async ({ title, description, targetDate }) => {
+          createCalls.push(`${title}:${description ?? ""}:${targetDate ?? ""}`);
+          return {
+            ok: true as const,
+            data: {
+              id: "milestone_private_beta",
+              title,
+              description,
+              status: "pending",
+              targetDate,
+              archived: false,
+              updatedAt: "2026-03-15T09:00:00.000Z",
+            },
+          };
+        },
+        updateProjectMilestone: async ({
+          milestoneId,
+          title,
+          description,
+          status,
+        }) => {
+          updateCalls.push(
+            `${milestoneId}:${title ?? ""}:${description ?? ""}:${status ?? ""}`
+          );
+          return {
+            ok: true as const,
+            data: {
+              id: milestoneId,
+              title: title ?? "Launch",
+              description: description ?? "Prepare launch checklist.\n",
+              status: status ?? "planned",
+              targetDate: "2026-05-01",
+              archived: false,
+              updatedAt: "2026-03-15T10:00:00.000Z",
+            },
+          };
+        },
+      },
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(createCalls).toEqual([
+    "Private beta:Ship the beta cohort.\n:2026-04-01",
+  ]);
+  expect(updateCalls).toEqual([
+    "milestone_launch:Launch:Prepare launch checklist.\n:planned",
+  ]);
+  expect(result.payload.summary.created).toBe(1);
+  expect(result.payload.summary.updated).toBe(1);
+
+  const createdText = await Bun.file(
+    resolve(milestonesDir, "private-beta.md")
+  ).text();
+  expect(createdText).toContain("linearId: milestone_private_beta");
+  expect(createdText).toContain("updatedAt: 2026-03-15T09:00:00.000Z");
+  expect(createdText).toContain("state: pending");
+
+  const updatedText = await Bun.file(
+    resolve(milestonesDir, "launch.md")
+  ).text();
+  expect(updatedText).toContain("linearId: milestone_launch");
+  expect(updatedText).toContain("updatedAt: 2026-03-15T10:00:00.000Z");
+  expect(updatedText).toContain("state: planned");
+});
+
 test("runProjectArtifactCommand publishes draft status updates and moves them to published", async () => {
   const projectDir = ensureTempDir();
   const draftsDir = resolve(

From a428423ebe3c9ed6e7c7c5d9c1ef025af754c263 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:08:03 +0000
Subject: [PATCH 060/134] HACK-454: checkpoint merge prep

---
 docs/cli.md                                   |   3 +-
 docs/extensions.md                            |  12 +-
 ...-13-linear-project-management-ux-design.md | 178 +++++
 ...03-13-linear-project-management-ux-plan.md | 154 ++++
 src/commands/linear.ts                        |  10 +-
 .../extensions/linear/commands.ts             | 671 +++++++++++++++---
 tests/linear-commands.test.ts                 | 300 ++++++++
 7 files changed, 1230 insertions(+), 98 deletions(-)
 create mode 100644 docs/plans/2026-03-13-linear-project-management-ux-design.md
 create mode 100644 docs/plans/2026-03-13-linear-project-management-ux-plan.md

diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..34e0b73fc 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -654,7 +654,8 @@ Run `hack tickets` with no args to see available subcommands.
 Usage: `hack linear <args...>`
 
 `hack linear` is a convenience alias for the Linear extension (`hack x linear ...`).
-Run `hack linear` with no args to see available subcommands.
+Run `hack linear` with no args to see available subcommands. Use `hack linear status` to check the
+active Linear profile, repo route, and available next steps.
 
 ## Internal commands
 
diff --git a/docs/extensions.md b/docs/extensions.md
index b4c8b0a81..69aec192c 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -286,9 +286,12 @@ hack x linear oauth-connect --profile work --set-default
 # or, default one-shot behavior (falls back to OAuth when no token is present):
 hack x linear connect --profile work --set-default
 
-# bind this hack project to a default Linear project
+# bind this repo to its default Linear project route
 hack x linear project-bind --profile work --project-id "<linear-project-id>"
 
+# confirm what this repo is connected to and can do next
+hack x linear status
+
 # one-off syncs (manual by default)
 hack x linear sync-issue --from linear --issue ENG-123
 hack x linear sync-issue --from hack --ticket T-00001
@@ -304,6 +307,13 @@ Notes:
   `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
 - Project mapping is stored in project config:
   `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
+- `hack x linear status` is the primary "what is connected here?" command. It reports the active
+  profile, repo route, linked projects, available capabilities, and repair commands for missing
+  profile/token/binding states.
+- `hack x linear setup` now summarizes repo readiness for Linear instead of only echoing raw config
+  keys.
+- `hack x linear project-bind` now explains which team/project the repo will affect and what command
+  to run next.
 - Sync is manual by default (`sync-issue` / `sync-project`); there is no background autosync yet.
 - Ticket provenance is preserved during sync via `owner`, `source`, `tags`, and `external*` linkage fields.
 - `hack x linear connect` uses token mode when `--token`/`--stdin`/`$HACK_LINEAR_API_TOKEN` is present, and otherwise falls back to browser OAuth.
diff --git a/docs/plans/2026-03-13-linear-project-management-ux-design.md b/docs/plans/2026-03-13-linear-project-management-ux-design.md
new file mode 100644
index 000000000..d3ac75520
--- /dev/null
+++ b/docs/plans/2026-03-13-linear-project-management-ux-design.md
@@ -0,0 +1,178 @@
+# Linear Project Management UX Design
+
+## Context
+
+The current `hack linear` setup surface exposes auth and extension internals more than project-management meaning. Users can connect a profile and bind a project, but the default CLI responses make it harder than necessary to answer three practical questions:
+
+- What Linear account/profile is active here?
+- Which Linear team/project will this repo route to?
+- What commands are valid next, and how do I repair missing or invalid bindings?
+
+The issue scope is limited to the existing `setup`, `project-bind`, and `status` commands. Command names remain stable to avoid churn in scripts, docs, and user muscle memory.
+
+## Goals
+
+- Reframe `setup`, `project-bind`, and `status` around active profile, project routing, and capabilities.
+- Make human-facing output answer what is connected, what is bound, and what to do next.
+- Explicitly describe which project/team a command will affect.
+- Point every broken state at the correct repair command.
+- Keep `--json` useful for automation without leaking unnecessary auth machinery into normal terminal output.
+
+## Non-Goals
+
+- Renaming the command surface.
+- Reworking OAuth/token plumbing.
+- Changing sync behavior or autosync semantics.
+- Migrating config storage away from existing routing/auth fields.
+
+## Approaches Considered
+
+### 1. Stable verbs, new summaries and repair-centric output (recommended)
+
+Keep `setup`, `project-bind`, and `status` but redesign their human-facing responses around project-management meaning. Add shared helpers that compute:
+
+- active profile and its connection state
+- bound default project/team and linked projects
+- user-facing capabilities and next steps
+- repair commands for missing token/profile/project binding states
+
+Pros:
+
+- Lowest migration risk.
+- Preserves docs and scripts.
+- Directly addresses the acceptance criteria.
+
+Cons:
+
+- Old verbs still reflect the legacy mental model somewhat.
+
+### 2. Add friendlier aliases on top of the existing verbs
+
+Keep the existing commands but add alternative entry points such as `bind` or `whoami`.
+
+Pros:
+
+- Slightly clearer discovery.
+
+Cons:
+
+- Broader command-surface work.
+- Raises documentation and help complexity without being required by the issue.
+
+### 3. Full command rename
+
+Replace the current verbs with a new primary surface.
+
+Pros:
+
+- Could optimize the language more aggressively.
+
+Cons:
+
+- High compatibility and documentation churn.
+- Out of scope for the acceptance criteria.
+
+## Recommended Design
+
+Adopt approach 1.
+
+### Shared status model
+
+Introduce a shared project-management summary helper in the Linear extension that resolves:
+
+- `activeProfile`
+- `connected`
+- `connectionLabel`
+- `boundProject`
+- `linkedProjects`
+- `capabilities`
+- `repairCommand`
+- `routingSummary`
+- `nextSteps`
+
+This model is used by `status` directly and by `setup` / `project-bind` success states.
+
+### `hack linear status`
+
+`status` becomes the default “what is connected here?” command.
+
+Human output should include:
+
+- active Linear profile
+- whether that profile is connected locally
+- which Hack project routing override is active
+- default Linear project/team routing for this repo
+- any additional linked projects
+- capabilities that are currently unlocked
+- next actions or repair actions
+
+Examples of capability language:
+
+- `sync tickets for the bound Linear project`
+- `pull issues from linked Linear projects`
+- `repair local access from the connected Hack account`
+
+Examples of repair language:
+
+- missing profile: `Run hack linear connect --profile <id> or hack linear oauth-connect --profile <id>.`
+- missing token for selected profile: `Run hack linear connect --profile <id>.`
+- missing project binding: `Run hack linear project-bind --profile <id> --project-id <linear-project-id>.`
+- selected profile override points to a missing profile: call that out and point at `hack linear setup --profile <valid-profile>` or `hack linear project-bind --profile <valid-profile> ...`
+
+### `hack linear setup`
+
+`setup` remains the fastest “make this repo ready for Linear” command, but its output changes from raw config fields to an outcome summary:
+
+- active profile after setup
+- default project/team route now bound for this repo, if provided
+- what commands will use that route
+- next recommended command if setup is partial
+
+If setup only sets a profile and not a project binding, it should say the repo is connected but not yet routed for project sync, then point to `project-bind`.
+
+### `hack linear project-bind`
+
+`project-bind` becomes the explicit routing command.
+
+Human output should answer:
+
+- which repo is now routed
+- which active profile owns that route
+- which default team/project sync commands target
+- which linked projects remain in scope
+- what to run next
+
+Error states should use routing language rather than raw config language. For example:
+
+- `Missing --project-id` becomes guidance that the repo has no default Linear project route and should either pass `--project-id` or clear the route.
+- unresolved project/team should say the selected profile cannot verify the target and suggest reconnecting that profile if access is stale.
+
+### JSON compatibility
+
+Keep existing fields where practical, but add user-facing fields so callers can consume the clearer model:
+
+- `connected`
+- `connectionLabel`
+- `routing`
+- `capabilities`
+- `repair`
+- `nextSteps`
+
+### Help and docs
+
+Update top-level `hack linear` examples and docs so the first mental model is:
+
+1. connect a profile
+2. bind this repo to a Linear project
+3. use `hack linear status` to confirm what this repo can do
+
+## Testing
+
+- Add parser/helper tests for the new status/setup/bind summary payloads and repair decisions.
+- Preserve existing parser coverage for command flags.
+- Verify command docs/help reflect the new routing language.
+
+## Risks
+
+- Human-facing text can drift from the actual command behavior if the shared summary helper is not used consistently.
+- JSON shape changes could surprise external callers if existing fields are removed. Avoid removal in this pass.
diff --git a/docs/plans/2026-03-13-linear-project-management-ux-plan.md b/docs/plans/2026-03-13-linear-project-management-ux-plan.md
new file mode 100644
index 000000000..57179df2b
--- /dev/null
+++ b/docs/plans/2026-03-13-linear-project-management-ux-plan.md
@@ -0,0 +1,154 @@
+# Linear Project Management UX Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Redesign `hack linear setup`, `hack linear project-bind`, and `hack linear status` so users can understand the active profile, repo routing, capabilities, and repair paths without knowing extension internals.
+
+**Architecture:** Keep the existing command names and storage layout, but add shared project-management summary helpers inside the Linear extension. Use those helpers to drive the human-facing output and enriched JSON payloads for `setup`, `project-bind`, and `status`, then update help/docs to match the new routing language.
+
+**Tech Stack:** Bun, TypeScript, existing CLI display helpers, Bun test
+
+---
+
+### Task 1: Add failing tests for the shared project-management summary model
+
+**Files:**
+- Modify: `tests/linear-commands.test.ts`
+- Test: `tests/linear-commands.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests that expect new helper output for:
+
+- connected profile + bound project + capabilities
+- missing token/profile with repair command
+- setup summary showing partial vs complete repo readiness
+- project-bind summary showing routing scope and next steps
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/linear-commands.test.ts`
+Expected: FAIL because the new helper functions / payload shape do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Create shared summary helpers in `src/control-plane/extensions/linear/commands.ts` and expose them via `__testOnly`.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/linear-commands.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/linear-commands.test.ts src/control-plane/extensions/linear/commands.ts
+git commit -m "feat: redesign linear project management status"
+```
+
+### Task 2: Rework human-facing `status`, `setup`, and `project-bind` output
+
+**Files:**
+- Modify: `src/control-plane/extensions/linear/commands.ts`
+- Test: `tests/linear-commands.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for command payload builders covering:
+
+- `status` reports active route and capabilities
+- `setup` reports readiness and next steps
+- `project-bind` reports default route plus linked project scope
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/linear-commands.test.ts`
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+Refactor the command handlers to call the shared summary helper and render:
+
+- status panel with connection, routing, capabilities, repair
+- setup panel with repo readiness and next command
+- project-bind panel with route scope and next command
+
+Keep existing JSON fields where possible, but add the new summary fields.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/linear-commands.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/linear/commands.ts tests/linear-commands.test.ts
+git commit -m "feat: reframe linear setup and binding output"
+```
+
+### Task 3: Update top-level help and docs
+
+**Files:**
+- Modify: `src/commands/linear.ts`
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing test**
+
+If practical, add or update a CLI/help test that covers the new examples. Otherwise rely on doc edits plus command-level tests from previous tasks.
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/linear-command-alias.test.ts tests/linear-commands.test.ts`
+Expected: Existing help expectations fail if examples changed.
+
+**Step 3: Write minimal implementation**
+
+Update help text and documentation to emphasize:
+
+- connect profile
+- bind repo route
+- confirm status/capabilities
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/linear-command-alias.test.ts tests/linear-commands.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/commands/linear.ts docs/extensions.md docs/cli.md tests/linear-command-alias.test.ts tests/linear-commands.test.ts
+git commit -m "docs: clarify linear routing and capability language"
+```
+
+### Task 4: Verify quality gates and complete session handoff
+
+**Files:**
+- Modify if needed: `.hack/tickets/*` via CLI
+
+**Step 1: Run targeted verification**
+
+Run: `bun test tests/linear-commands.test.ts tests/linear-command-alias.test.ts`
+Expected: PASS
+
+**Step 2: Run quality gate**
+
+Run: `bunx ultracite check`
+Expected: PASS
+
+**Step 3: File remaining work if needed**
+
+Create follow-up tickets only for work explicitly left out of this pass.
+
+**Step 4: Update issue status context**
+
+Do not mutate Linear directly from this run. Instead prepare concise handoff notes describing completion state and residual risks.
+
+**Step 5: Commit**
+
+```bash
+git add docs/plans/2026-03-13-linear-project-management-ux-design.md docs/plans/2026-03-13-linear-project-management-ux-plan.md
+git commit -m "docs: plan linear project management ux redesign"
+```
diff --git a/src/commands/linear.ts b/src/commands/linear.ts
index 7c3426f9c..630b81ed8 100644
--- a/src/commands/linear.ts
+++ b/src/commands/linear.ts
@@ -13,17 +13,19 @@ import { logger } from "../ui/logger.ts";
  */
 const linearSpec = defineCommand({
   name: "linear",
-  summary: "Linear account connection and ticket sync",
+  summary: "Linear project routing, connection status, and ticket sync",
   description: [
     "Usage:",
     "  hack linear status",
     "  hack linear connect --profile work --set-default",
-    "  hack linear connect --profile default --stdin",
     "  hack linear oauth-connect --profile work --set-default",
-    "  hack linear project-bind --project-id <linear-project-id>",
+    "  hack linear project-bind --profile work --project-id <linear-project-id>",
     "  hack linear sync-issue --from linear --issue ENG-123",
     "  hack linear sync-issue --from hack --ticket T-00001",
-    "  hack linear sync-project --from linear --project-id <linear-project-id>",
+    "  hack linear sync-project --from linear",
+    "",
+    "Use `hack linear status` to confirm the active profile, repo route,",
+    "available capabilities, and repair steps.",
     "",
     "Alias for `hack x linear <command>`. Requires extension enabled.",
   ].join("\n"),
diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index ebaf9b342..670890055 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -80,58 +80,46 @@ export const LINEAR_COMMANDS: readonly ExtensionCommand[] = [
         projectDir: ctx.project.projectDir,
       });
 
-      if (parsed.value.profileId) {
-        await updateProjectConfig({
-          projectDir: ctx.project.projectDir,
-          path: "controlPlane.routing.overrides.linear.profile",
-          value: parsed.value.profileId,
-        });
-      }
-      if (parsed.value.projectId) {
-        await updateProjectConfig({
-          projectDir: ctx.project.projectDir,
-          path: "controlPlane.routing.overrides.linear.projectId",
-          value: parsed.value.projectId,
-        });
-      }
-      if (parsed.value.projectName !== undefined) {
-        await updateProjectConfig({
-          projectDir: ctx.project.projectDir,
-          path: "controlPlane.routing.overrides.linear.projectName",
-          value: parsed.value.projectName,
-        });
-      }
-      if (parsed.value.teamId !== undefined) {
-        await updateProjectConfig({
-          projectDir: ctx.project.projectDir,
-          path: "controlPlane.routing.overrides.linear.teamId",
-          value: parsed.value.teamId,
-        });
-      }
+      const existingBinding = resolveProjectLinearBinding({
+        controlPlaneConfig: ctx.controlPlaneConfig,
+      });
+      await persistLinearSetupOverrides({
+        projectDir: ctx.project.projectDir,
+        parsed: parsed.value,
+      });
 
-      const payload = {
-        ok: true,
-        extension: EXTENSION_ID,
-        projectProfile: parsed.value.profileId ?? null,
-        projectId: parsed.value.projectId ?? null,
-        projectName: parsed.value.projectName ?? null,
-        teamId: parsed.value.teamId ?? null,
-      };
+      const binding = resolveLinearSetupBinding({
+        parsed: parsed.value,
+        existingBinding,
+      });
+      const status = await resolveLinearStatusPayload({
+        controlPlaneConfig: ctx.controlPlaneConfig,
+        profileId: binding.profileId,
+      });
+      const summary = buildLinearProjectManagementSummary({
+        status,
+        binding,
+      });
+      const setupSummary = buildLinearSetupSummary({
+        profileId: parsed.value.profileId,
+        binding,
+        status,
+      });
+      const payload = buildLinearSetupPayload({
+        binding,
+        status,
+        summary,
+        setupSummary,
+      });
 
       if (parsed.value.json) {
         process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
         return 0;
       }
 
-      await display.kv({
-        title: "Linear setup",
-        entries: [
-          ["extension", EXTENSION_ID],
-          ["project_profile", parsed.value.profileId ?? ""],
-          ["linear_project_id", parsed.value.projectId ?? ""],
-          ["linear_project_name", parsed.value.projectName ?? ""],
-          ["linear_team_id", parsed.value.teamId ?? ""],
-        ],
+      await renderLinearSetupPanel({
+        summary,
+        setupSummary,
       });
       return 0;
     },
@@ -784,22 +772,25 @@ export const LINEAR_COMMANDS: readonly ExtensionCommand[] = [
         const payload = buildProjectBindingPayload({
           binding: existingBinding,
         });
+        const summary = buildLinearProjectBindSummary({
+          binding: existingBinding,
+        });
         if (parsed.value.json) {
-          process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+          process.stdout.write(
+            `${JSON.stringify({ ...payload, summary }, null, 2)}\n`
+          );
         } else {
-          await display.kv({
+          await display.panel({
             title: "Linear project binding",
-            entries: [
-              ["profile", payload.profileId ?? ""],
-              ["project_id", payload.projectId ?? ""],
-              ["project_name", payload.projectName ?? ""],
-              ["team_id", payload.teamId ?? ""],
-              [
-                "additional_projects",
-                payload.additionalProjects
-                  .map((project) => project.projectId)
-                  .join(", "),
-              ],
+            tone: payload.projectId ? "info" : "warn",
+            lines: [
+              `Active profile: ${summary.activeProfile}`,
+              `Route: ${summary.routeLabel}`,
+              ...(summary.linkedProjectsLabel
+                ? [summary.linkedProjectsLabel]
+                : []),
+              "Next:",
+              ...summary.nextSteps.map((step) => `- ${step}`),
             ],
           });
         }
@@ -837,14 +828,22 @@ export const LINEAR_COMMANDS: readonly ExtensionCommand[] = [
           binding: { additionalProjects: [] },
           cleared: true,
         });
+        const summary = buildLinearProjectBindSummary({
+          binding: { additionalProjects: [] },
+        });
         if (parsed.value.json) {
-          process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+          process.stdout.write(
+            `${JSON.stringify({ ...payload, summary }, null, 2)}\n`
+          );
         } else {
           await display.panel({
             title: "Linear project binding",
             tone: "success",
             lines: [
-              "Cleared project-level Linear routing overrides, including additional synced projects.",
+              "Cleared this repo's Linear routing overrides, including linked projects.",
+              `Route: ${summary.routeLabel}`,
+              "Next:",
+              "- Run `hack linear status` to review what is still connected.",
             ],
           });
         }
@@ -919,23 +918,35 @@ export const LINEAR_COMMANDS: readonly ExtensionCommand[] = [
           }),
         },
       });
+      const summary = buildLinearProjectBindSummary({
+        binding: {
+          ...(boundProfile ? { profileId: boundProfile } : {}),
+          projectId,
+          projectName: resolvedTeamAndName.projectName,
+          teamId: resolvedTeamAndName.teamId,
+          additionalProjects: removeAdditionalProjectBinding({
+            existing: existingBinding.additionalProjects,
+            projectId,
+          }),
+        },
+      });
 
       if (parsed.value.json) {
-        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        process.stdout.write(
+          `${JSON.stringify({ ...payload, summary }, null, 2)}\n`
+        );
       } else {
-        await display.kv({
+        await display.panel({
           title: "Linear project binding",
-          entries: [
-            ["profile", payload.profileId ?? ""],
-            ["project_id", payload.projectId],
-            ["project_name", payload.projectName],
-            ["team_id", payload.teamId],
-            [
-              "additional_projects",
-              payload.additionalProjects
-                .map((project) => project.projectId)
-                .join(", "),
-            ],
+          tone: "success",
+          lines: [
+            `Active profile: ${summary.activeProfile}`,
+            `Route: ${summary.routeLabel}`,
+            ...(summary.linkedProjectsLabel
+              ? [summary.linkedProjectsLabel]
+              : []),
+            "Next:",
+            ...summary.nextSteps.map((step) => `- ${step}`),
           ],
         });
       }
@@ -1984,7 +1995,7 @@ async function handleLinearStatusCommand(input: {
     return 1;
   }
 
-  const payload = await resolveLinearStatusPayload({
+  const payload = await resolveLinearStatusCommandPayload({
     controlPlaneConfig: input.ctx.controlPlaneConfig,
     profileId: parsed.value.profileId,
   });
@@ -2022,6 +2033,11 @@ type LinearStatusPayload = {
   readonly ok: boolean;
 };
 
+type LinearStatusCommandPayload = LinearStatusPayload & {
+  readonly projectBinding: ReturnType<typeof buildProjectBindingPayload>;
+  readonly summary: LinearProjectManagementSummary;
+};
+
 async function resolveLinearStatusPayload(input: {
   readonly controlPlaneConfig: ExtensionCommandContext["controlPlaneConfig"];
   readonly profileId?: string;
@@ -2072,28 +2088,72 @@ async function resolveLinearStatusPayload(input: {
   };
 }
 
+async function resolveLinearStatusCommandPayload(input: {
+  readonly controlPlaneConfig: ExtensionCommandContext["controlPlaneConfig"];
+  readonly profileId?: string;
+}): Promise<LinearStatusCommandPayload> {
+  const status = await resolveLinearStatusPayload(input);
+  const projectBinding = buildProjectBindingPayload({
+    binding: resolveProjectLinearBinding({
+      controlPlaneConfig: input.controlPlaneConfig,
+    }),
+  });
+  const summary = buildLinearProjectManagementSummary({
+    status,
+    binding: {
+      ...(projectBinding.profileId
+        ? { profileId: projectBinding.profileId }
+        : {}),
+      ...(projectBinding.projectId
+        ? { projectId: projectBinding.projectId }
+        : {}),
+      ...(projectBinding.projectName
+        ? { projectName: projectBinding.projectName }
+        : {}),
+      ...(projectBinding.teamId ? { teamId: projectBinding.teamId } : {}),
+      additionalProjects: projectBinding.additionalProjects,
+    },
+  });
+  return {
+    ...status,
+    projectBinding,
+    summary,
+  };
+}
+
 async function renderLinearStatusPayload(input: {
-  readonly payload: LinearStatusPayload;
+  readonly payload: LinearStatusCommandPayload;
   readonly logger: ExtensionCommandContext["logger"];
 }): Promise<void> {
-  await display.kv({
+  const lines = [
+    `Active profile: ${input.payload.summary.activeProfile}`,
+    `Connection: ${input.payload.summary.connectionLabel}`,
+    `Route: ${input.payload.summary.routingSummary}`,
+    ...(input.payload.summary.linkedProjectsLabel
+      ? [input.payload.summary.linkedProjectsLabel]
+      : []),
+    ...(input.payload.summary.capabilities.length > 0
+      ? [
+          "Capabilities:",
+          ...input.payload.summary.capabilities.map(
+            (capability) => `- ${capability}`
+          ),
+        ]
+      : []),
+    ...(input.payload.summary.repair
+      ? [
+          `Repair: ${input.payload.summary.repair.reason}`,
+          `Run: ${input.payload.summary.repair.command}`,
+        ]
+      : []),
+    ...(input.payload.summary.nextSteps.length > 0
+      ? ["Next:", ...input.payload.summary.nextSteps.map((step) => `- ${step}`)]
+      : []),
+  ];
+  await display.panel({
     title: "Linear status",
-    entries: [
-      ["selected_profile", input.payload.selectedProfile],
-      ["selected_source", input.payload.selectedSource],
-      ["default_profile", input.payload.defaultProfile],
-      ["selected_missing", input.payload.selectedMissing ? "yes" : "no"],
-      ["auth_ref", input.payload.authRef],
-      ["service", input.payload.service],
-      ["token_env_fallback", input.payload.tokenEnvFallback],
-      ["api_url", input.payload.apiUrl],
-      ["account_id", input.payload.accountId ?? ""],
-      ["account_name", input.payload.accountName ?? ""],
-      ["account_email", input.payload.accountEmail ?? ""],
-      ["token_resolved", input.payload.tokenResolved ? "yes" : "no"],
-      ["token_source", input.payload.tokenSource ?? ""],
-      ["token_expires_at", input.payload.tokenExpiresAt ?? ""],
-    ],
+    tone: input.payload.ok ? "info" : "warn",
+    lines,
   });
   if (input.payload.profileError) {
     input.logger.warn({ message: input.payload.profileError });
@@ -5237,6 +5297,170 @@ type ResolvedLinearProjectBinding = {
   readonly additionalProjects: readonly LinearProjectBindingTarget[];
 };
 
+type LinearRepairAction = {
+  readonly reason: string;
+  readonly command: string;
+};
+
+type LinearProjectManagementSummary = {
+  readonly activeProfile: string;
+  readonly connected: boolean;
+  readonly connectionLabel: string;
+  readonly routingSummary: string;
+  readonly linkedProjectsLabel: string | null;
+  readonly capabilities: readonly string[];
+  readonly repair: LinearRepairAction | null;
+  readonly nextSteps: readonly string[];
+};
+
+type LinearSetupSummary = {
+  readonly ready: boolean;
+  readonly activeProfile: string;
+  readonly connected: boolean;
+  readonly routeLabel: string;
+  readonly nextSteps: readonly string[];
+};
+
+type LinearProjectBindSummary = {
+  readonly activeProfile: string;
+  readonly routeLabel: string;
+  readonly linkedProjectsLabel: string | null;
+  readonly nextSteps: readonly string[];
+};
+
+async function persistLinearSetupOverrides(input: {
+  readonly projectDir: string;
+  readonly parsed: SetupArgs;
+}): Promise<void> {
+  if (input.parsed.profileId) {
+    await updateProjectConfig({
+      projectDir: input.projectDir,
+      path: "controlPlane.routing.overrides.linear.profile",
+      value: input.parsed.profileId,
+    });
+  }
+  if (input.parsed.projectId) {
+    await updateProjectConfig({
+      projectDir: input.projectDir,
+      path: "controlPlane.routing.overrides.linear.projectId",
+      value: input.parsed.projectId,
+    });
+  }
+  if (input.parsed.projectName !== undefined) {
+    await updateProjectConfig({
+      projectDir: input.projectDir,
+      path: "controlPlane.routing.overrides.linear.projectName",
+      value: input.parsed.projectName,
+    });
+  }
+  if (input.parsed.teamId !== undefined) {
+    await updateProjectConfig({
+      projectDir: input.projectDir,
+      path: "controlPlane.routing.overrides.linear.teamId",
+      value: input.parsed.teamId,
+    });
+  }
+}
+
+function resolveLinearSetupBinding(input: {
+  readonly parsed: SetupArgs;
+  readonly existingBinding: ResolvedLinearProjectBinding;
+}): ResolvedLinearProjectBinding {
+  const effectiveProfileId =
+    input.parsed.profileId ?? input.existingBinding.profileId;
+  const effectiveProjectId =
+    input.parsed.projectId ?? input.existingBinding.projectId;
+  const effectiveProjectName =
+    input.parsed.projectName !== undefined
+      ? input.parsed.projectName || undefined
+      : input.existingBinding.projectName;
+  const effectiveTeamId =
+    input.parsed.teamId !== undefined
+      ? input.parsed.teamId || undefined
+      : input.existingBinding.teamId;
+
+  return {
+    ...(effectiveProfileId ? { profileId: effectiveProfileId } : {}),
+    ...(effectiveProjectId ? { projectId: effectiveProjectId } : {}),
+    ...(effectiveProjectName ? { projectName: effectiveProjectName } : {}),
+    ...(effectiveTeamId ? { teamId: effectiveTeamId } : {}),
+    additionalProjects: input.existingBinding.additionalProjects,
+  };
+}
+
+function buildLinearSetupPayload(input: {
+  readonly binding: ResolvedLinearProjectBinding;
+  readonly status: LinearStatusPayload;
+  readonly summary: LinearProjectManagementSummary;
+  readonly setupSummary: LinearSetupSummary;
+}): {
+  readonly ok: boolean;
+  readonly extension: string;
+  readonly projectProfile: string | null;
+  readonly projectId: string | null;
+  readonly projectName: string | null;
+  readonly teamId: string | null;
+  readonly connected: boolean;
+  readonly connectionLabel: string;
+  readonly routingSummary: string;
+  readonly capabilities: readonly string[];
+  readonly repair: LinearRepairAction | null;
+  readonly ready: boolean;
+  readonly nextSteps: readonly string[];
+} {
+  return {
+    ok: input.status.ok,
+    extension: EXTENSION_ID,
+    projectProfile: input.binding.profileId ?? null,
+    projectId: input.binding.projectId ?? null,
+    projectName: input.binding.projectName ?? null,
+    teamId: input.binding.teamId ?? null,
+    connected: input.summary.connected,
+    connectionLabel: input.summary.connectionLabel,
+    routingSummary: input.summary.routingSummary,
+    capabilities: input.summary.capabilities,
+    repair: input.summary.repair,
+    ready: input.setupSummary.ready,
+    nextSteps: input.setupSummary.nextSteps,
+  };
+}
+
+async function renderLinearSetupPanel(input: {
+  readonly summary: LinearProjectManagementSummary;
+  readonly setupSummary: LinearSetupSummary;
+}): Promise<void> {
+  await display.panel({
+    title: "Linear setup",
+    tone: input.setupSummary.ready ? "success" : "info",
+    lines: [
+      `Extension: ${EXTENSION_ID}`,
+      `Active profile: ${input.setupSummary.activeProfile}`,
+      `Connection: ${input.summary.connectionLabel}`,
+      `Route: ${input.setupSummary.routeLabel}`,
+      ...(input.summary.linkedProjectsLabel
+        ? [input.summary.linkedProjectsLabel]
+        : []),
+      ...(input.summary.capabilities.length > 0
+        ? [
+            "Capabilities:",
+            ...input.summary.capabilities.map(
+              (capability) => `- ${capability}`
+            ),
+          ]
+        : []),
+      ...(input.summary.repair
+        ? [
+            `Repair: ${input.summary.repair.reason}`,
+            `Run: ${input.summary.repair.command}`,
+          ]
+        : []),
+      ...(input.setupSummary.nextSteps.length > 0
+        ? ["Next:", ...input.setupSummary.nextSteps.map((step) => `- ${step}`)]
+        : []),
+    ],
+  });
+}
+
 function resolveProjectLinearBinding(input: {
   readonly controlPlaneConfig: ExtensionCommandContext["controlPlaneConfig"];
 }): ResolvedLinearProjectBinding {
@@ -5402,6 +5626,266 @@ function buildProjectBindingPayload(input: {
   };
 }
 
+function pluralize(input: {
+  readonly count: number;
+  readonly singular: string;
+  readonly plural?: string;
+}): string {
+  if (input.count === 1) {
+    return input.singular;
+  }
+  return input.plural ?? `${input.singular}s`;
+}
+
+function formatLinearProjectTarget(input: {
+  readonly projectId: string;
+  readonly projectName?: string;
+  readonly teamId?: string;
+}): string {
+  const projectLabel = input.projectName
+    ? `${input.projectName} (${input.projectId})`
+    : input.projectId;
+  return input.teamId
+    ? `${projectLabel} in team ${input.teamId}`
+    : projectLabel;
+}
+
+function resolveLinearConnectionLabel(input: {
+  readonly activeProfile: string;
+  readonly connected: boolean;
+  readonly status: LinearStatusPayload;
+}): string {
+  if (input.connected) {
+    if (input.status.accountName) {
+      return `Connected as ${input.status.accountName}`;
+    }
+    if (input.status.accountEmail) {
+      return `Connected as ${input.status.accountEmail}`;
+    }
+    return "Connected";
+  }
+  if (input.status.selectedMissing) {
+    return `Profile "${input.activeProfile}" is selected but not configured`;
+  }
+  return "Not connected";
+}
+
+function buildLinearRoutingSummary(input: {
+  readonly binding: ResolvedLinearProjectBinding;
+}): string {
+  if (!input.binding.projectId) {
+    return "This repo does not have a default Linear project route yet.";
+  }
+  return `This repo routes Linear sync to ${formatLinearProjectTarget({
+    projectId: input.binding.projectId,
+    projectName: input.binding.projectName,
+    teamId: input.binding.teamId,
+  })}.`;
+}
+
+function buildLinkedProjectsLabel(input: {
+  readonly binding: ResolvedLinearProjectBinding;
+}): string | null {
+  const linkedProjectsCount = input.binding.additionalProjects.length;
+  if (linkedProjectsCount === 0) {
+    return null;
+  }
+  return `${linkedProjectsCount} linked ${pluralize({
+    count: linkedProjectsCount,
+    singular: "project",
+  })}: ${input.binding.additionalProjects
+    .map((project) =>
+      formatLinearProjectTarget({
+        projectId: project.projectId,
+        projectName: project.projectName,
+        teamId: project.teamId,
+      })
+    )
+    .join(", ")}.`;
+}
+
+function resolveLinearRepairAction(input: {
+  readonly activeProfile: string;
+  readonly connected: boolean;
+  readonly status: LinearStatusPayload;
+}): LinearRepairAction | null {
+  if (input.status.selectedMissing || input.status.profileError) {
+    return {
+      reason: "The active Linear profile binding is invalid.",
+      command: `hack linear setup --profile ${input.activeProfile}`,
+    };
+  }
+  if (input.status.error?.includes("hack auth login")) {
+    return {
+      reason: "Hack account login is required for broker-owned Linear access.",
+      command: "hack auth login",
+    };
+  }
+  if (!input.connected) {
+    return {
+      reason: "Local Linear access is missing for the active profile.",
+      command: `hack linear connect --profile ${input.activeProfile}`,
+    };
+  }
+  return null;
+}
+
+function buildLinearCapabilities(input: {
+  readonly connected: boolean;
+  readonly binding: ResolvedLinearProjectBinding;
+}): readonly string[] {
+  const capabilities: string[] = [];
+  if (input.connected && input.binding.projectId) {
+    capabilities.push("Sync tickets for the bound Linear project");
+  }
+  if (input.connected && input.binding.additionalProjects.length > 0) {
+    capabilities.push(
+      `Pull issues from ${input.binding.additionalProjects.length} linked Linear ${pluralize(
+        {
+          count: input.binding.additionalProjects.length,
+          singular: "project",
+        }
+      )}`
+    );
+  }
+  if (input.connected && !input.binding.projectId) {
+    capabilities.push("Bind this repo to a Linear project before project sync");
+  }
+  if (!input.connected && input.binding.projectId) {
+    capabilities.push("Repair local Linear access for the active profile");
+  }
+  return capabilities;
+}
+
+function buildLinearNextSteps(input: {
+  readonly repair: LinearRepairAction | null;
+  readonly binding: ResolvedLinearProjectBinding;
+  readonly activeProfile: string;
+}): readonly string[] {
+  if (input.repair) {
+    return [`Run \`${input.repair.command}\`.`];
+  }
+  if (input.binding.projectId) {
+    return ["Run `hack linear sync-project --from linear`."];
+  }
+  return [
+    `Run \`hack linear project-bind --profile ${input.activeProfile} --project-id <linear-project-id>\`.`,
+  ];
+}
+
+function buildLinearProjectManagementSummary(input: {
+  readonly status: LinearStatusPayload;
+  readonly binding: ResolvedLinearProjectBinding;
+}): LinearProjectManagementSummary {
+  const activeProfile =
+    input.status.selectedProfile ?? input.binding.profileId ?? "default";
+  const connected = input.status.tokenResolved;
+  const connectionLabel = resolveLinearConnectionLabel({
+    activeProfile,
+    connected,
+    status: input.status,
+  });
+  const routingSummary = buildLinearRoutingSummary({
+    binding: input.binding,
+  });
+  const linkedProjectsLabel = buildLinkedProjectsLabel({
+    binding: input.binding,
+  });
+  const repair = resolveLinearRepairAction({
+    activeProfile,
+    connected,
+    status: input.status,
+  });
+  const capabilities = buildLinearCapabilities({
+    connected,
+    binding: input.binding,
+  });
+  const nextSteps = buildLinearNextSteps({
+    repair,
+    binding: input.binding,
+    activeProfile,
+  });
+
+  return {
+    activeProfile,
+    connected,
+    connectionLabel,
+    routingSummary,
+    linkedProjectsLabel,
+    capabilities,
+    repair,
+    nextSteps,
+  };
+}
+
+function buildLinearSetupSummary(input: {
+  readonly profileId?: string;
+  readonly binding: ResolvedLinearProjectBinding;
+  readonly status: LinearStatusPayload;
+}): LinearSetupSummary {
+  const projectSummary = buildLinearProjectManagementSummary({
+    status: input.status,
+    binding: input.binding,
+  });
+  return {
+    ready: projectSummary.connected && Boolean(input.binding.projectId),
+    activeProfile:
+      input.profileId ??
+      input.binding.profileId ??
+      input.status.selectedProfile,
+    connected: projectSummary.connected,
+    routeLabel: input.binding.projectId
+      ? projectSummary.routingSummary
+      : "No default Linear project is bound to this repo yet.",
+    nextSteps: input.binding.projectId
+      ? ["Run `hack linear status` to confirm the active route."]
+      : [
+          `Run \`hack linear project-bind --profile ${projectSummary.activeProfile} --project-id <linear-project-id>\`.`,
+        ],
+  };
+}
+
+function buildLinearProjectBindSummary(input: {
+  readonly binding: ResolvedLinearProjectBinding;
+}): LinearProjectBindSummary {
+  const routeLabel = input.binding.projectId
+    ? `This repo now uses ${formatLinearProjectTarget({
+        projectId: input.binding.projectId,
+        projectName: input.binding.projectName,
+        teamId: input.binding.teamId,
+      })} as its default Linear route.`
+    : "This repo no longer has a default Linear route.";
+  const linkedProjectsCount = input.binding.additionalProjects.length;
+  const linkedProjectsLabel =
+    linkedProjectsCount > 0
+      ? `${linkedProjectsCount} linked ${pluralize({
+          count: linkedProjectsCount,
+          singular: "project",
+        })} remains in scope: ${input.binding.additionalProjects
+          .map((project) =>
+            formatLinearProjectTarget({
+              projectId: project.projectId,
+              projectName: project.projectName,
+            })
+          )
+          .join(", ")}.`
+      : null;
+  return {
+    activeProfile: input.binding.profileId ?? "default",
+    routeLabel,
+    linkedProjectsLabel,
+    nextSteps: input.binding.projectId
+      ? [
+          "Run `hack linear status` to review active capabilities.",
+          "Run `hack linear sync-project --from linear` to sync the default route.",
+        ]
+      : [
+          `Run \`hack linear project-bind --profile ${input.binding.profileId ?? "default"} --project-id <linear-project-id>\` to bind a default route.`,
+          "Run `hack linear status` to review what is still connected.",
+        ],
+  };
+}
+
 function resolveProjectPullTargets(input: {
   readonly binding: ResolvedLinearProjectBinding;
   readonly explicitProjectId?: string;
@@ -8309,6 +8793,9 @@ function normalizeOAuthActor(value: string | undefined): "user" | "app" | null {
 }
 
 export const __testOnly = {
+  buildLinearProjectBindSummary,
+  buildLinearProjectManagementSummary,
+  buildLinearSetupSummary,
   buildOAuthArgsFromConnectArgs,
   detectAuthoritativeFieldConflicts,
   findProjectBindingTarget,
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index 75eee414b..58d9f061d 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -334,6 +334,306 @@ test("resolveProjectPullTargets includes default and additional bound projects",
   ]);
 });
 
+test("buildLinearProjectManagementSummary reports connected routing and capabilities", () => {
+  const summary = __testOnly.buildLinearProjectManagementSummary({
+    status: {
+      extensionId: "dance.hack.linear",
+      selectedProfile: "work",
+      selectedSource: "project_routing",
+      defaultProfile: "work",
+      selectedMissing: false,
+      authRef: "linear.api.work",
+      service: "hack-linear-auth",
+      tokenEnvFallback: "HACK_LINEAR_API_TOKEN",
+      apiUrl: "https://api.linear.app/graphql",
+      accountId: "user-1",
+      accountName: "Work User",
+      accountEmail: "work@example.com",
+      tokenResolved: true,
+      tokenSource: "keychain",
+      tokenExpiresAt: null,
+      error: null,
+      profileError: null,
+      ok: true,
+    },
+    binding: {
+      profileId: "work",
+      projectId: "proj_default",
+      projectName: "Default",
+      teamId: "team_default",
+      additionalProjects: [
+        {
+          projectId: "proj_extra",
+          projectName: "Extra",
+          teamId: "team_extra",
+        },
+      ],
+    },
+  });
+
+  expect(summary).toMatchObject({
+    activeProfile: "work",
+    connected: true,
+    connectionLabel: "Connected as Work User",
+    routingSummary:
+      "This repo routes Linear sync to Default (proj_default) in team team_default.",
+    capabilities: [
+      "Sync tickets for the bound Linear project",
+      "Pull issues from 1 linked Linear project",
+    ],
+    repair: null,
+  });
+  expect(summary.nextSteps).toContain(
+    "Run `hack linear sync-project --from linear`."
+  );
+});
+
+test("buildLinearProjectManagementSummary prefers the selected status profile over repo binding", () => {
+  const summary = __testOnly.buildLinearProjectManagementSummary({
+    status: {
+      extensionId: "dance.hack.linear",
+      selectedProfile: "ops",
+      selectedSource: "command_flags",
+      defaultProfile: "work",
+      selectedMissing: false,
+      authRef: "linear.api.ops",
+      service: "hack-linear-auth",
+      tokenEnvFallback: "HACK_LINEAR_API_TOKEN",
+      apiUrl: "https://api.linear.app/graphql",
+      accountId: "user-2",
+      accountName: "Ops User",
+      accountEmail: "ops@example.com",
+      tokenResolved: false,
+      tokenSource: null,
+      tokenExpiresAt: null,
+      error: 'Missing Linear token for profile "ops".',
+      profileError: null,
+      ok: false,
+    },
+    binding: {
+      profileId: "work",
+      projectId: "proj_default",
+      projectName: "Default",
+      teamId: "team_default",
+      additionalProjects: [],
+    },
+  });
+
+  expect(summary.activeProfile).toBe("ops");
+  expect(summary.repair?.command).toBe("hack linear connect --profile ops");
+});
+
+test("buildLinearProjectManagementSummary points missing local access at connect repair", () => {
+  const summary = __testOnly.buildLinearProjectManagementSummary({
+    status: {
+      extensionId: "dance.hack.linear",
+      selectedProfile: "work",
+      selectedSource: "command_flags",
+      defaultProfile: "work",
+      selectedMissing: false,
+      authRef: "linear.api.work",
+      service: "hack-linear-auth",
+      tokenEnvFallback: "HACK_LINEAR_API_TOKEN",
+      apiUrl: "https://api.linear.app/graphql",
+      accountId: "user-1",
+      accountName: "Work User",
+      accountEmail: "work@example.com",
+      tokenResolved: false,
+      tokenSource: null,
+      tokenExpiresAt: null,
+      error: 'Missing Linear token for profile "work".',
+      profileError: null,
+      ok: false,
+    },
+    binding: {
+      profileId: "work",
+      projectId: "proj_default",
+      projectName: "Default",
+      teamId: "team_default",
+      additionalProjects: [],
+    },
+  });
+
+  expect(summary).toMatchObject({
+    activeProfile: "work",
+    connected: false,
+    repair: {
+      reason: "Local Linear access is missing for the active profile.",
+      command: "hack linear connect --profile work",
+    },
+  });
+  expect(summary.nextSteps).toContain(
+    "Run `hack linear connect --profile work`."
+  );
+});
+
+test("buildLinearProjectManagementSummary points broker auth failures at hack auth login", () => {
+  const summary = __testOnly.buildLinearProjectManagementSummary({
+    status: {
+      extensionId: "dance.hack.linear",
+      selectedProfile: "work",
+      selectedSource: "command_flags",
+      defaultProfile: "work",
+      selectedMissing: false,
+      authRef: "linear.api.work",
+      service: "hack-linear-auth",
+      tokenEnvFallback: "HACK_LINEAR_API_TOKEN",
+      apiUrl: "https://api.linear.app/graphql",
+      accountId: null,
+      accountName: null,
+      accountEmail: null,
+      tokenResolved: false,
+      tokenSource: null,
+      tokenExpiresAt: null,
+      error:
+        'Linear broker management token expired for profile "work". Run `hack auth login` for broker-owned access, or reconnect this Linear profile to refresh its saved broker token.',
+      profileError: null,
+      ok: false,
+    },
+    binding: {
+      profileId: "work",
+      projectId: "proj_default",
+      projectName: "Default",
+      teamId: "team_default",
+      additionalProjects: [],
+    },
+  });
+
+  expect(summary.repair).toEqual({
+    reason: "Hack account login is required for broker-owned Linear access.",
+    command: "hack auth login",
+  });
+  expect(summary.nextSteps).toEqual(["Run `hack auth login`."]);
+});
+
+test("buildLinearProjectManagementSummary points invalid profile bindings at setup repair", () => {
+  const summary = __testOnly.buildLinearProjectManagementSummary({
+    status: {
+      extensionId: "dance.hack.linear",
+      selectedProfile: "missing",
+      selectedSource: "project_routing",
+      defaultProfile: "work",
+      selectedMissing: true,
+      authRef: "linear.api.missing",
+      service: "hack-linear-auth",
+      tokenEnvFallback: "HACK_LINEAR_API_TOKEN",
+      apiUrl: "https://api.linear.app/graphql",
+      accountId: null,
+      accountName: null,
+      accountEmail: null,
+      tokenResolved: false,
+      tokenSource: null,
+      tokenExpiresAt: null,
+      error: null,
+      profileError: 'Linear profile "missing" was not found.',
+      ok: false,
+    },
+    binding: {
+      profileId: "missing",
+      projectId: "proj_default",
+      projectName: "Default",
+      teamId: "team_default",
+      additionalProjects: [],
+    },
+  });
+
+  expect(summary.repair).toEqual({
+    reason: "The active Linear profile binding is invalid.",
+    command: "hack linear setup --profile missing",
+  });
+  expect(summary.nextSteps).toEqual([
+    "Run `hack linear setup --profile missing`.",
+  ]);
+});
+
+test("buildLinearSetupSummary explains partial repo readiness", () => {
+  const summary = __testOnly.buildLinearSetupSummary({
+    profileId: "work",
+    binding: {
+      profileId: "work",
+      additionalProjects: [],
+    },
+    status: {
+      extensionId: "dance.hack.linear",
+      selectedProfile: "work",
+      selectedSource: "project_routing",
+      defaultProfile: "work",
+      selectedMissing: false,
+      authRef: "linear.api.work",
+      service: "hack-linear-auth",
+      tokenEnvFallback: "HACK_LINEAR_API_TOKEN",
+      apiUrl: "https://api.linear.app/graphql",
+      accountId: "user-1",
+      accountName: "Work User",
+      accountEmail: "work@example.com",
+      tokenResolved: true,
+      tokenSource: "keychain",
+      tokenExpiresAt: null,
+      error: null,
+      profileError: null,
+      ok: true,
+    },
+  });
+
+  expect(summary).toMatchObject({
+    ready: false,
+    activeProfile: "work",
+    connected: true,
+    routeLabel: "No default Linear project is bound to this repo yet.",
+  });
+  expect(summary.nextSteps).toEqual([
+    "Run `hack linear project-bind --profile work --project-id <linear-project-id>`.",
+  ]);
+});
+
+test("buildLinearProjectBindSummary explains default route and linked project scope", () => {
+  const summary = __testOnly.buildLinearProjectBindSummary({
+    binding: {
+      profileId: "work",
+      projectId: "proj_default",
+      projectName: "Default",
+      teamId: "team_default",
+      additionalProjects: [
+        {
+          projectId: "proj_extra",
+          projectName: "Extra",
+          teamId: "team_extra",
+        },
+      ],
+    },
+  });
+
+  expect(summary).toEqual({
+    activeProfile: "work",
+    routeLabel:
+      "This repo now uses Default (proj_default) in team team_default as its default Linear route.",
+    linkedProjectsLabel:
+      "1 linked project remains in scope: Extra (proj_extra).",
+    nextSteps: [
+      "Run `hack linear status` to review active capabilities.",
+      "Run `hack linear sync-project --from linear` to sync the default route.",
+    ],
+  });
+});
+
+test("buildLinearProjectBindSummary avoids sync guidance when no default route exists", () => {
+  const summary = __testOnly.buildLinearProjectBindSummary({
+    binding: {
+      additionalProjects: [],
+    },
+  });
+
+  expect(summary).toEqual({
+    activeProfile: "default",
+    routeLabel: "This repo no longer has a default Linear route.",
+    linkedProjectsLabel: null,
+    nextSteps: [
+      "Run `hack linear project-bind --profile default --project-id <linear-project-id>` to bind a default route.",
+      "Run `hack linear status` to review what is still connected.",
+    ],
+  });
+});
+
 test("resolveProjectPullTargets keeps per-project profile overrides for linked projects", () => {
   const targets = __testOnly.resolveProjectPullTargets({
     binding: {

From 47e5d8f330ad07e45ddc03f8b9ebd19ffaab0fe3 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:08:07 +0000
Subject: [PATCH 061/134] HACK-429: checkpoint merge prep

---
 ...26-03-13-cli-ux-and-guided-setup-design.md | 412 +++++++++
 ...2026-03-13-cli-ux-and-guided-setup-plan.md | 446 ++++++++++
 .../extensions/tickets/tickets-git-channel.ts | 842 ++++++++++++------
 tests/tickets-extension.test.ts               | 110 +++
 4 files changed, 1518 insertions(+), 292 deletions(-)
 create mode 100644 docs/plans/2026-03-13-cli-ux-and-guided-setup-design.md
 create mode 100644 docs/plans/2026-03-13-cli-ux-and-guided-setup-plan.md

diff --git a/docs/plans/2026-03-13-cli-ux-and-guided-setup-design.md b/docs/plans/2026-03-13-cli-ux-and-guided-setup-design.md
new file mode 100644
index 000000000..44fc8b266
--- /dev/null
+++ b/docs/plans/2026-03-13-cli-ux-and-guided-setup-design.md
@@ -0,0 +1,412 @@
+# CLI UX And Guided Setup Design
+
+## Context
+
+Hack already exposes most of the underlying capability needed for setup, repair, and provider auth:
+
+- `hack doctor` checks many machine prerequisites and already suggests `hack doctor --fix` for several failures.
+- `hack setup` manages agent/editor integrations.
+- `hack auth` provides a first-class Hack account flow.
+- `hack linear` exists as a top-level alias over the Linear extension.
+- `hack tickets` exists as a top-level alias over the tickets extension.
+- `hack x` remains the generic extension dispatcher.
+
+The problem is not missing raw capability. The problem is that prerequisite detection, next-step routing, and status language are still fragmented across commands, extensions, and transport-specific error strings.
+
+Today a user can still hit all of these failure classes:
+
+- missing runtime prerequisites discovered only after a command fails
+- mux/session failures that surface as backend absence rather than setup guidance
+- GitHub flows that remain extension-centric and token-centric
+- Linear broker flows that depend on Hack auth, local profile config, and project routing, but do not always explain which layer is missing
+- help output that explains commands, but not the setup state required to use them
+
+This stream defines the UX contract for first-run and repair behavior without requiring every child issue to invent its own interception language.
+
+## Goals
+
+- Make missing prerequisites discoverable from CLI output alone.
+- Route users to the right setup or repair flow automatically.
+- Define consistent top-level semantics for built-in commands, top-level aliases, and `hack x`.
+- Normalize how status/help/error output describes auth, profiles, teams, and project routing.
+- Break the stream into child issues that are independently executable.
+
+## Non-Goals
+
+- Do not redesign the full visual style of every command output.
+- Do not collapse all extension commands into the root CLI in one pass.
+- Do not replace provider-specific logic with one giant generic setup engine.
+- Do not move existing local-only workflows behind mandatory Hack sign-in.
+- Do not implement every child issue in this stream from this program ticket.
+
+## Approaches Considered
+
+### 1. Program-level UX contract first, then targeted child implementation
+
+Define one shared prerequisite matrix, interception model, command taxonomy, and status vocabulary. Land that as docs plus child issue decomposition, then let each child issue implement one part.
+
+Pros:
+
+- Matches the acceptance criteria for this stream issue.
+- Prevents runtime, mux, GitHub, and Linear work from drifting apart.
+- Makes future code review objective because the contract is explicit.
+
+Cons:
+
+- Does not immediately change runtime behavior by itself.
+
+### 2. Incrementally patch each command family directly
+
+Fix `doctor`, `session`, GitHub auth, Linear auth, and help output one by one without a formal shared contract.
+
+Pros:
+
+- Faster short-term shipping on one surface at a time.
+
+Cons:
+
+- High risk of inconsistent messages and overlapping repair flows.
+- Makes later cleanup harder because semantics drift.
+
+### 3. Centralize all setup detection in one universal setup command
+
+Create a single setup wizard that owns all prerequisite detection and recovery.
+
+Pros:
+
+- Conceptually simple entry point.
+
+Cons:
+
+- Too large for this stream.
+- Conflicts with Hack’s existing command-oriented workflow.
+- Still would not address provider-specific interception needs cleanly.
+
+## Recommended Direction
+
+Use approach 1.
+
+This stream should land the product contract for guided setup and repair, then delegate execution to child issues focused on runtime/mux, command semantics, GitHub auth/setup, and Linear auth/setup.
+
+## Current Surface Summary
+
+The current codebase implies the following shape:
+
+- runtime/global infra health lives primarily under `hack doctor`
+- project lifecycle lives under root commands like `hack up`, `hack logs`, and `hack open`
+- Hack account auth lives under `hack auth`
+- Linear already has a root alias: `hack linear`
+- tickets already has a root alias: `hack tickets`
+- GitHub is still extension-only under `hack x github`
+- extension enablement is handled separately from provider auth
+
+This means the new UX contract should not pretend the CLI is fully flattened already. It should explicitly define which commands stay root-level, which commands remain extension-level for now, and how the CLI explains that split.
+
+## Approved UX Contract
+
+### 1. Prerequisites are grouped by capability, not by implementation detail
+
+The CLI should reason about four user-facing capability groups:
+
+- runtime
+- mux sessions
+- GitHub integration
+- Linear integration
+
+Each group has a small prerequisite matrix with:
+
+- what the user is trying to do
+- what must exist
+- how the CLI checks it
+- what command repairs it
+- whether the CLI can auto-intercept and route
+
+### 2. Every missing prerequisite maps to one next step
+
+When a command fails because a prerequisite is missing, the user should see:
+
+- what is missing
+- why this command needs it
+- the exact next command to run
+- whether rerunning the original command should work afterward
+
+Avoid vague guidance like:
+
+- "not configured"
+- "missing context"
+- "extension disabled"
+
+unless the output also names the corrective action.
+
+### 3. Root commands are intent-first; `hack x` is the escape hatch
+
+The command taxonomy should be:
+
+- `hack <root-command>` for built-in product workflows and high-frequency integrated flows
+- `hack <alias>` for promoted extensions with stable UX contracts
+- `hack x <namespace> ...` for advanced or not-yet-promoted extension workflows
+
+For this stream, the intended top-level shape is:
+
+- keep `hack auth`
+- keep `hack linear`
+- keep `hack tickets`
+- keep `hack setup`
+- keep `hack doctor`
+- keep `hack x` as the generic dispatcher
+- add a first-class decision on whether GitHub remains `hack x github` or is promoted to `hack github`
+
+### 4. Interception should happen at the command entry point closest to intent
+
+The CLI should intercept at the first command the user naturally runs, not after multiple opaque transport failures.
+
+Examples:
+
+- `hack up` should intercept missing global/runtime health and send the user to `hack doctor` or `hack doctor --fix`
+- `hack session start` should intercept missing mux backend and explain how to enable tmux/zellij or choose no-mux mode
+- `hack x github ...` or `hack github ...` should intercept missing `gh`, missing stored profile state, and missing Hack auth only when the chosen flow actually requires it
+- `hack linear ...` should intercept missing Hack auth, missing broker-backed profile access, missing local token/profile state, or missing project binding distinctly
+
+### 5. Status output must separate these concepts consistently
+
+Human-facing and JSON output should use stable language for:
+
+- Hack account session
+- provider connection
+- selected profile
+- selected organization/team
+- project binding/routing
+- local access versus broker-owned access
+
+The CLI should not force users to infer which layer failed from an error string.
+
+## Prerequisite Detection Matrix
+
+### Runtime
+
+| Capability | Required state | Existing check surface | Expected interception |
+| --- | --- | --- | --- |
+| `hack up`, `hack open`, `hack logs`, `hack ps` | bun installed, docker available, docker daemon reachable, global networking healthy enough for routed features | mostly `hack doctor`, partial command-local checks in project commands | commands route to `hack doctor` / `hack doctor --fix` with targeted explanation |
+| routed HTTPS hosts | caddy/global infra, DNS resolver, trust state | `hack doctor`, project command warnings | command explains whether routing is degraded vs fully blocked |
+| mutagen-backed workflows | mutagen binary/agent availability | `hack doctor`, mutagen helpers | repair points to `hack doctor --fix` or explicit mutagen path override |
+
+### Mux Sessions
+
+| Capability | Required state | Existing check surface | Expected interception |
+| --- | --- | --- | --- |
+| `hack session`, `hack session start` | chosen mux mode resolves to available tmux/zellij backend, or explicit no-mux mode | mux resolver + backend availability checks | session command explains missing backend and setup choice instead of acting like zero sessions exist |
+| attach/exec/capture | backend installed and target session exists | session commands | command distinguishes "backend missing" from "session missing" |
+
+### GitHub Integration
+
+| Capability | Required state | Existing check surface | Expected interception |
+| --- | --- | --- | --- |
+| GitHub status/connect/profile workflows | extension enabled, selected profile resolved, local token/app installation state available | GitHub extension auth/commands | user sees promoted command semantics and exact repair path |
+| broker-owned/shared GitHub features | valid Hack auth session plus authorized broker access | provider-specific auth flows | output distinguishes Hack account login from GitHub provider connection |
+| PR/remote bootstrap workflows | `gh` installed when flow depends on GitHub CLI | GitHub commands | command offers install/setup guidance before failing deeper |
+
+### Linear Integration
+
+| Capability | Required state | Existing check surface | Expected interception |
+| --- | --- | --- | --- |
+| local profile/token flows | extension enabled, selected profile resolved, local token saved or provided | Linear command parsing/auth helpers | output explains profile selection and storage source clearly |
+| broker-owned connection/autosync flows | Hack auth session, broker management token, permitted profile/team/project access | Linear auth/session helpers | command states whether user needs `hack auth login`, reconnect, or different profile/team |
+| project sync/routing flows | project context present, project binding present, route scope known | Linear commands + project config | output names bound project/team/profile and what is missing |
+
+## Interception Rules
+
+### Root runtime commands
+
+For `hack up`, `hack open`, `hack logs`, and related project commands:
+
+- preflight only the prerequisites relevant to the requested behavior
+- distinguish hard blockers from degraded modes
+- point to `hack doctor` or `hack doctor --fix` when a shared runtime issue is the root cause
+- preserve the original command in the message so the user knows what to retry
+
+### Session commands
+
+For `hack session`:
+
+- if mux mode is `auto` and no backend is available, explain the decision tree: install tmux, install zellij, or set mux mode to `none`
+- if a backend exists but session name is missing, show normal session guidance
+- do not silently treat missing backend as an empty session list
+
+### Extension promotion and dispatch
+
+For promoted namespaces:
+
+- root alias and `hack x` behavior should stay functionally aligned
+- root help should explain when a workflow is promoted
+- `hack x` help should describe itself as the advanced/escape-hatch path
+
+For unpromoted namespaces:
+
+- `hack x <namespace>` remains canonical until promotion is approved
+
+### Provider auth flows
+
+For GitHub and Linear:
+
+- first explain whether the missing layer is Hack account auth, provider auth, or project/profile selection
+- do not say "not authorized" without naming the identity boundary
+- show active profile/team/project bindings in status output when they affect the requested command
+
+## Status And Help Vocabulary
+
+The CLI should standardize these phrases:
+
+- `Hack account`: the Better Auth session used for broker-owned resources
+- `Provider profile`: the selected GitHub or Linear profile
+- `Local access`: provider token/profile state stored on this machine
+- `Broker access`: remote access owned by the Hack account/org/team
+- `Project binding`: the project-level route to a provider profile/project/team
+- `Repair`: a recoverable path where the CLI knows the next command
+
+Avoid mixing these into ambiguous phrases like:
+
+- `connected` with no scope
+- `authorized` with no subject
+- `default` with no mention of profile vs team vs project binding
+
+## Child Issue Breakdown
+
+This stream should break into the following child issues.
+These are already recorded in the repo-local `hack` tickets ref as `T-00001` through `T-00006`.
+
+### 1. Runtime prerequisite detection and guided repair (`T-00002`)
+
+Scope:
+
+- define command-level runtime preflight helpers
+- align `hack up`/`open`/`logs` with `hack doctor`
+- normalize degraded-vs-blocked messaging
+
+Primary files:
+
+- `src/commands/project.ts`
+- `src/commands/doctor.ts`
+- shared runtime helper modules under `src/lib/` or `src/commands/`
+
+### 2. Mux/session prerequisite interception (`T-00003`)
+
+Scope:
+
+- make missing tmux/zellij explicit
+- surface mux mode and repair actions in `hack session`
+- distinguish backend absence from missing sessions
+
+Primary files:
+
+- `src/commands/session.ts`
+- `src/mux/mux-resolver.ts`
+- `src/mux/*.ts`
+
+### 3. Top-level command semantics and help cleanup (`T-00001`)
+
+Scope:
+
+- define promotion rules for root aliases vs `hack x`
+- decide GitHub root alias promotion
+- improve root help and dispatcher help copy
+- make extension-disabled messaging intent-first
+
+Primary files:
+
+- `src/cli/help.ts`
+- `src/cli/spec.ts`
+- `src/commands/x.ts`
+- command alias files such as `src/commands/linear.ts`, `src/commands/tickets.ts`
+
+### 4. GitHub setup and auth guidance cleanup (`T-00005`)
+
+Scope:
+
+- clarify setup/auth/status output for GitHub profiles
+- intercept missing `gh`, missing local auth, and broker-auth requirements
+- align any promoted root alias with extension behavior
+
+Primary files:
+
+- `src/control-plane/extensions/github/commands.ts`
+- `src/control-plane/extensions/github/auth.ts`
+- related GitHub tests
+
+### 5. Linear setup and broker/local access guidance cleanup (`T-00006`)
+
+Scope:
+
+- clarify Hack auth vs Linear auth vs project binding failures
+- standardize status output around profile/team/project context
+- improve repair routing for broker-backed access and local repair flows
+
+Primary files:
+
+- `src/control-plane/extensions/linear/commands.ts`
+- `src/control-plane/extensions/linear/auth.ts`
+- related Linear tests
+
+### 6. Shared status payload vocabulary (`T-00004`)
+
+Scope:
+
+- define shared JSON fields and human phrasing for auth/profile/routing status
+- align provider and root status commands on that vocabulary
+
+Primary files:
+
+- auth/provider command implementations
+- any shared status rendering helpers
+- command tests asserting payload shape and text
+
+## Testing Strategy
+
+This stream’s child work should bias toward command-level tests that assert:
+
+- the right interception occurs before deep failure
+- output names the missing prerequisite explicitly
+- output names the exact next command
+- JSON output exposes the same state model as human output
+
+Use focused Bun tests for:
+
+- command parsing
+- command handlers with mocked fetch/process state
+- status payload rendering
+- help output snapshots where needed
+
+## Acceptance Mapping
+
+### A user can discover and fix missing setup from CLI output alone
+
+Covered by:
+
+- prerequisite matrix
+- interception rules
+- repair vocabulary
+
+### Core workflows route users into the correct setup or repair flow automatically
+
+Covered by:
+
+- root runtime command interception
+- session interception
+- provider auth flow interception
+
+### Integration commands explain active bindings and missing context clearly
+
+Covered by:
+
+- status/help vocabulary
+- provider-specific guidance rules
+- shared status payload contract
+
+### The child issues in this stream are sufficient to implement the new UX contract
+
+Covered by:
+
+- six-child breakdown across runtime, mux, semantics, GitHub, Linear, and shared status payloads
+
+## Recommended Next Step
+
+Write an implementation plan that converts this contract into small tasks and create local child tickets mirroring the issue breakdown above.
diff --git a/docs/plans/2026-03-13-cli-ux-and-guided-setup-plan.md b/docs/plans/2026-03-13-cli-ux-and-guided-setup-plan.md
new file mode 100644
index 000000000..2b38d407a
--- /dev/null
+++ b/docs/plans/2026-03-13-cli-ux-and-guided-setup-plan.md
@@ -0,0 +1,446 @@
+# CLI UX And Guided Setup Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Establish and implement a consistent guided-setup and repair contract across runtime, mux, GitHub, Linear, and top-level command semantics so users can recover from missing setup directly from CLI output.
+
+**Architecture:** Keep Hack’s command-oriented structure, but add a shared prerequisite/interception vocabulary that root commands, promoted aliases, and extension commands all use consistently. Treat `hack doctor` as the runtime repair authority, `hack auth` as the Hack-account authority, provider commands as provider-specific repair surfaces, and `hack x` as the advanced dispatcher instead of the default user journey.
+
+**Tech Stack:** Bun, TypeScript, Hack CLI command framework, extension command surfaces, Bun tests.
+
+## Execution Notes
+
+- Implement this stream through child issues rather than as one giant branch.
+- Favor command-level tests that assert the user-visible next step.
+- Keep JSON payloads and human output aligned.
+- Reuse existing helpers before adding new shared layers.
+- Repo-local ticket mapping:
+  `T-00001` top-level semantics, `T-00002` runtime repair, `T-00003` mux/session repair,
+  `T-00004` shared status vocabulary, `T-00005` GitHub guidance, `T-00006` Linear guidance.
+
+---
+
+### Task 1: Introduce a shared prerequisite result model
+
+**Files:**
+
+- Create: `src/cli/prereq.ts`
+- Modify: `src/commands/project.ts`
+- Modify: `src/commands/session.ts`
+- Test: `tests/cli-prereq.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for a minimal prerequisite result model that can represent:
+
+- `ok`
+- `degraded`
+- `blocked`
+- exact repair command
+- retryable original command
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/cli-prereq.test.ts
+```
+
+Expected: FAIL because the shared prerequisite model does not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Add a small shared type/helper layer for prerequisite checks and repair messages. Keep it presentation-focused rather than building a large framework.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/cli-prereq.test.ts
+```
+
+Expected: PASS
+
+### Task 2: Align runtime commands with guided doctor repair
+
+**Files:**
+
+- Modify: `src/commands/project.ts`
+- Modify: `src/commands/doctor.ts`
+- Test: `tests/project-up-command.test.ts`
+- Test: `tests/daemon-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add focused tests showing that runtime failures route users to:
+
+- `hack doctor`
+- `hack doctor --fix`
+- degraded-mode explanations when routing or trust is unavailable but the command can still partially work
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/project-up-command.test.ts tests/daemon-command.test.ts
+```
+
+Expected: FAIL after adding the new expectations.
+
+**Step 3: Write minimal implementation**
+
+Use the shared prerequisite model to standardize runtime repair messages in project commands. Reuse doctor checks where practical instead of duplicating raw diagnostics.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/project-up-command.test.ts tests/daemon-command.test.ts
+```
+
+Expected: PASS
+
+### Task 3: Make mux/session repair intent-first
+
+**Files:**
+
+- Modify: `src/commands/session.ts`
+- Modify: `src/mux/mux-resolver.ts`
+- Modify: `src/mux/tmux-backend.ts`
+- Modify: `src/mux/zellij-backend.ts`
+- Test: `tests/session-utils.test.ts`
+- Create: `tests/session-command-guidance.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+
+- auto mux mode with no available backend
+- explicit tmux mode with tmux missing
+- explicit zellij mode with zellij missing
+- existing backend but missing named session
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/session-command-guidance.test.ts tests/session-utils.test.ts
+```
+
+Expected: FAIL because session guidance does not yet distinguish backend setup from missing sessions clearly.
+
+**Step 3: Write minimal implementation**
+
+Return structured prerequisite failures from session entry points and render repair options:
+
+- install tmux
+- install zellij
+- configure mux mode to `none`
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/session-command-guidance.test.ts tests/session-utils.test.ts
+```
+
+Expected: PASS
+
+### Task 4: Clean up root help and dispatcher semantics
+
+**Files:**
+
+- Modify: `src/cli/help.ts`
+- Modify: `src/cli/spec.ts`
+- Modify: `src/commands/x.ts`
+- Modify: `src/commands/linear.ts`
+- Modify: `src/commands/tickets.ts`
+- Test: `tests/cli-command.test.ts`
+- Create: `tests/help-output.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+
+- root help surfacing promoted workflows clearly
+- `hack x` help framing itself as advanced/dispatcher behavior
+- extension-disabled output naming the exact promoted or extension entry point
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts tests/help-output.test.ts
+```
+
+Expected: FAIL with current help/dispatcher messaging.
+
+**Step 3: Write minimal implementation**
+
+Update root help and dispatcher copy to:
+
+- explain promoted aliases
+- explain when `hack x` is still canonical
+- make disabled-extension output intent-first rather than namespace-first
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts tests/help-output.test.ts
+```
+
+Expected: PASS
+
+### Task 5: Decide and implement GitHub top-level semantics
+
+**Files:**
+
+- Modify: `src/cli/spec.ts`
+- Create or modify: `src/commands/github.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Test: `tests/github-commands.test.ts`
+- Create: `tests/github-command-alias.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for the approved GitHub entry-point decision:
+
+- if promoted: `hack github ...` mirrors `hack x github ...`
+- if not promoted: help/repair output consistently points users to `hack x github`
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/github-commands.test.ts tests/github-command-alias.test.ts
+```
+
+Expected: FAIL because the chosen semantics are not implemented yet.
+
+**Step 3: Write minimal implementation**
+
+Implement the approved path only. Do not redesign GitHub auth in the same step.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/github-commands.test.ts tests/github-command-alias.test.ts
+```
+
+Expected: PASS
+
+### Task 6: Improve GitHub prerequisite interception
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Modify: `src/control-plane/extensions/github/auth.ts`
+- Test: `tests/github-commands.test.ts`
+- Test: `tests/github-auth.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+
+- missing `gh`
+- missing selected GitHub profile
+- missing local token/app installation state
+- broker-owned flow requiring Hack auth
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/github-commands.test.ts tests/github-auth.test.ts
+```
+
+Expected: FAIL after adding new guidance expectations.
+
+**Step 3: Write minimal implementation**
+
+Make GitHub commands report the missing layer explicitly and name the next command to run.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/github-commands.test.ts tests/github-auth.test.ts
+```
+
+Expected: PASS
+
+### Task 7: Improve Linear prerequisite interception and routing clarity
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/linear/commands.ts`
+- Modify: `src/control-plane/extensions/linear/auth.ts`
+- Test: `tests/linear-commands.test.ts`
+- Test: `tests/linear-auth.test.ts`
+- Test: `tests/auth-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+
+- missing Hack auth for broker-owned Linear access
+- stale broker token vs missing broker token
+- missing local profile/token state
+- missing project binding when running sync/project-scoped commands
+- status output including profile/team/project context clearly
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/linear-commands.test.ts tests/linear-auth.test.ts tests/auth-command.test.ts
+```
+
+Expected: FAIL after new expectations are added.
+
+**Step 3: Write minimal implementation**
+
+Standardize Linear repair output around four layers:
+
+- Hack account session
+- broker permission/profile ownership
+- local profile/token access
+- project binding/routing
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/linear-commands.test.ts tests/linear-auth.test.ts tests/auth-command.test.ts
+```
+
+Expected: PASS
+
+### Task 8: Standardize shared status vocabulary and payloads
+
+**Files:**
+
+- Modify: `src/commands/auth.ts`
+- Modify: provider status commands under `src/control-plane/extensions/*/commands.ts`
+- Create: `src/ui/status-contract.ts`
+- Test: `tests/auth-command.test.ts`
+- Test: `tests/github-commands.test.ts`
+- Test: `tests/linear-commands.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests asserting stable human/JSON vocabulary for:
+
+- Hack account
+- provider profile
+- local access
+- broker access
+- project binding
+- repair next step
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/auth-command.test.ts tests/github-commands.test.ts tests/linear-commands.test.ts
+```
+
+Expected: FAIL because the shared vocabulary layer does not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Add a small shared status helper and adopt it in status-oriented commands.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/auth-command.test.ts tests/github-commands.test.ts tests/linear-commands.test.ts
+```
+
+Expected: PASS
+
+### Task 9: Create and sync child tickets for the stream
+
+**Files:**
+
+- Verify only in git-backed tickets store
+
+**Step 1: Create child tickets**
+
+Create tickets for:
+
+- runtime prerequisite repair
+- mux/session interception
+- root help and command semantics
+- GitHub setup/auth guidance
+- Linear setup/auth guidance
+- shared status vocabulary
+
+Current status: these tickets already exist in the repo-local hidden ref as `T-00001` through
+`T-00006`.
+
+**Step 2: Mark dependencies**
+
+Model dependencies so shared vocabulary and command semantics can support the provider-specific work without blocking unrelated runtime fixes.
+
+**Step 3: Sync tickets**
+
+Run:
+
+```bash
+bun index.ts x tickets sync
+```
+
+Expected: tickets ref updates successfully once the workspace is bootstrapped.
+
+### Task 10: Final verification
+
+**Files:**
+
+- Verify only
+
+**Step 1: Run focused tests for changed slices**
+
+Run the relevant focused `bun test ...` commands from the child issue being implemented.
+
+**Step 2: Run repo quality gates**
+
+Run:
+
+```bash
+bun run check
+bun run typecheck
+bun run test
+```
+
+Expected: PASS
+
+**Step 3: Verify ticket state and handoff context**
+
+Run:
+
+```bash
+bun index.ts x tickets list
+git status --short
+```
+
+Expected: new docs and ticket artifacts are present, and remaining work is captured in child tickets.
diff --git a/src/control-plane/extensions/tickets/tickets-git-channel.ts b/src/control-plane/extensions/tickets/tickets-git-channel.ts
index 7517170e2..94aff0833 100644
--- a/src/control-plane/extensions/tickets/tickets-git-channel.ts
+++ b/src/control-plane/extensions/tickets/tickets-git-channel.ts
@@ -341,118 +341,155 @@ export function createGitTicketsChannel(opts: {
     return await fetchRemoteRefToTracking(ref, trackingRef);
   };
 
-  const checkoutHead = async (input: {
-    readonly remoteUrl: string | null;
+  const checkoutBranchFromRef = async (input: {
+    readonly checkoutRef: string;
   }): Promise<
     | { readonly ok: true; readonly pushRef: string }
     | { readonly ok: false; readonly error: string }
   > => {
-    await rm(worktreeDir, { recursive: true, force: true });
-    await mkdir(worktreeDir, { recursive: true });
+    const rev = await runGitDir({
+      args: ["rev-parse", "--verify", input.checkoutRef],
+    });
+    if (!rev.ok) {
+      return { ok: false, error: "" };
+    }
 
-    if (input.remoteUrl) {
-      let canCheckoutRemote = false;
-      let checkoutRef = `origin/${branch}`;
-
-      const fetched = await fetchRemoteRef(remoteRef);
-      if (fetched.ok) {
-        canCheckoutRemote = true;
-        if (legacyRemoteRef && legacyTrackingRef) {
-          const legacyFetch = await fetchRemoteRefToTracking(
-            legacyRemoteRef,
-            legacyTrackingRef
-          );
-          if (!(legacyFetch.ok || legacyFetch.missing)) {
-            return {
-              ok: false,
-              error: `git fetch failed: ${legacyFetch.error}`,
-            };
-          }
-        }
-      } else if (fetched.missing && legacyRemoteRef) {
-        const legacyFetch = legacyTrackingRef
-          ? await fetchRemoteRefToTracking(legacyRemoteRef, legacyTrackingRef)
-          : await fetchRemoteRef(legacyRemoteRef);
-        if (legacyFetch.ok) {
-          canCheckoutRemote = true;
-          if (legacyTrackingRef) {
-            checkoutRef = legacyTrackingRef;
-          }
-        } else if (!legacyFetch.missing) {
-          return { ok: false, error: `git fetch failed: ${legacyFetch.error}` };
-        }
-      } else if (!fetched.missing) {
-        return { ok: false, error: `git fetch failed: ${fetched.error}` };
-      }
+    const checkout = await runGitDir({
+      args: ["checkout", "-B", branch, rev.stdout.trim()],
+    });
+    if (!checkout.ok) {
+      return {
+        ok: false,
+        error: `git checkout failed: ${checkout.stderr.trim()}`,
+      };
+    }
 
-      if (canCheckoutRemote) {
-        const rev = await runGitDir({
-          args: ["rev-parse", "--verify", checkoutRef],
-        });
-        if (rev.ok) {
-          const checkout = await runGitDir({
-            args: ["checkout", "-B", branch, rev.stdout.trim()],
-          });
-          if (!checkout.ok) {
-            return {
-              ok: false,
-              error: `git checkout failed: ${checkout.stderr.trim()}`,
-            };
-          }
-
-          const reset = await runGitDir({ args: ["reset", "--hard"] });
-          if (!reset.ok) {
-            return {
-              ok: false,
-              error: `git reset failed: ${reset.stderr.trim()}`,
-            };
-          }
-
-          return {
-            ok: true,
-            pushRef: resolvePushRefForCheckout({ checkoutRef }),
-          };
-        }
-      }
+    const reset = await runGitDir({ args: ["reset", "--hard"] });
+    if (!reset.ok) {
+      return {
+        ok: false,
+        error: `git reset failed: ${reset.stderr.trim()}`,
+      };
     }
 
-    const localRef = await runGitDir({
-      args: ["rev-parse", "--verify", branch],
-    });
-    if (!localRef.ok) {
-      const orphan = await runGitDir({
-        args: ["checkout", "--orphan", branch],
-      });
-      if (!orphan.ok) {
-        return {
-          ok: false,
-          error: `git checkout --orphan failed: ${orphan.stderr.trim()}`,
-        };
-      }
+    return {
+      ok: true,
+      pushRef: resolvePushRefForCheckout({ checkoutRef: input.checkoutRef }),
+    };
+  };
 
-      await mkdir(resolve(worktreeDir, ".hack/tickets"), { recursive: true });
-      await Bun.write(
-        resolve(worktreeDir, ".hack/tickets/README.md"),
-        "Tickets ref for hack-cli\n"
-      );
+  const resolveRemoteCheckoutPlan = async (input: {
+    readonly remoteUrl: string | null;
+  }): Promise<{
+    readonly checkoutRef?: string;
+    readonly fetchFailure: string | null;
+  }> => {
+    if (!input.remoteUrl) {
+      return { fetchFailure: null };
+    }
 
-      const added = await runGitDir({ args: ["add", "-A"] });
-      if (!added.ok) {
-        return { ok: false, error: `git add failed: ${added.stderr.trim()}` };
-      }
-      const committed = await runGitDir({
-        args: ["commit", "-m", "init tickets"],
-      });
-      if (!committed.ok) {
-        return {
-          ok: false,
-          error: `git commit failed: ${committed.stderr.trim()}`,
-        };
-      }
+    const fetched = await fetchRemoteRef(remoteRef);
+    if (fetched.ok) {
+      const fetchFailure =
+        legacyRemoteRef && legacyTrackingRef
+          ? await resolveLegacyFetchFailure({
+              ref: legacyRemoteRef,
+              trackingRef: legacyTrackingRef,
+            })
+          : null;
+      return {
+        checkoutRef: `origin/${branch}`,
+        fetchFailure,
+      };
+    }
+
+    if (fetched.missing) {
+      return legacyRemoteRef
+        ? await resolveLegacyRemoteCheckoutPlan()
+        : { fetchFailure: null };
+    }
+
+    return { fetchFailure: `git fetch failed: ${fetched.error}` };
+  };
+
+  const resolveLegacyFetchFailure = async (input: {
+    readonly ref: string;
+    readonly trackingRef: string;
+  }): Promise<string | null> => {
+    const legacyFetch = await fetchRemoteRefToTracking(
+      input.ref,
+      input.trackingRef
+    );
+    if (legacyFetch.ok || legacyFetch.missing) {
+      return null;
+    }
+    return `git fetch failed: ${legacyFetch.error}`;
+  };
+
+  const resolveLegacyRemoteCheckoutPlan = async (): Promise<{
+    readonly checkoutRef?: string;
+    readonly fetchFailure: string | null;
+  }> => {
+    if (!legacyRemoteRef) {
+      return { fetchFailure: null };
+    }
 
-      return { ok: true, pushRef: remoteRef };
+    const legacyFetch = legacyTrackingRef
+      ? await fetchRemoteRefToTracking(legacyRemoteRef, legacyTrackingRef)
+      : await fetchRemoteRef(legacyRemoteRef);
+    if (legacyFetch.ok) {
+      return {
+        checkoutRef: legacyTrackingRef ?? `origin/${branch}`,
+        fetchFailure: null,
+      };
     }
+    if (legacyFetch.missing) {
+      return { fetchFailure: null };
+    }
+    return { fetchFailure: `git fetch failed: ${legacyFetch.error}` };
+  };
 
+  const initializeOrphanTicketsBranch = async (): Promise<
+    | { readonly ok: true; readonly pushRef: string }
+    | { readonly ok: false; readonly error: string }
+  > => {
+    const orphan = await runGitDir({
+      args: ["checkout", "--orphan", branch],
+    });
+    if (!orphan.ok) {
+      return {
+        ok: false,
+        error: `git checkout --orphan failed: ${orphan.stderr.trim()}`,
+      };
+    }
+
+    await mkdir(resolve(worktreeDir, ".hack/tickets"), { recursive: true });
+    await Bun.write(
+      resolve(worktreeDir, ".hack/tickets/README.md"),
+      "Tickets ref for hack-cli\n"
+    );
+
+    const added = await runGitDir({ args: ["add", "-A"] });
+    if (!added.ok) {
+      return { ok: false, error: `git add failed: ${added.stderr.trim()}` };
+    }
+    const committed = await runGitDir({
+      args: ["commit", "-m", "init tickets"],
+    });
+    if (!committed.ok) {
+      return {
+        ok: false,
+        error: `git commit failed: ${committed.stderr.trim()}`,
+      };
+    }
+
+    return { ok: true, pushRef: remoteRef };
+  };
+
+  const checkoutLocalBranch = async (): Promise<
+    | { readonly ok: true; readonly pushRef: string }
+    | { readonly ok: false; readonly error: string }
+  > => {
     const checkout = await runGitDir({ args: ["checkout", branch] });
     if (!checkout.ok) {
       return {
@@ -469,6 +506,41 @@ export function createGitTicketsChannel(opts: {
     return { ok: true, pushRef: remoteRef };
   };
 
+  const checkoutHead = async (input: {
+    readonly remoteUrl: string | null;
+  }): Promise<
+    | { readonly ok: true; readonly pushRef: string }
+    | { readonly ok: false; readonly error: string }
+  > => {
+    await rm(worktreeDir, { recursive: true, force: true });
+    await mkdir(worktreeDir, { recursive: true });
+
+    const remotePlan = await resolveRemoteCheckoutPlan(input);
+    if (remotePlan.checkoutRef) {
+      const remoteCheckout = await checkoutBranchFromRef({
+        checkoutRef: remotePlan.checkoutRef,
+      });
+      if (remoteCheckout.ok) {
+        return remoteCheckout;
+      }
+      if (remoteCheckout.error) {
+        return remoteCheckout;
+      }
+    }
+
+    const localRef = await runGitDir({
+      args: ["rev-parse", "--verify", branch],
+    });
+    if (!localRef.ok) {
+      if (remotePlan.fetchFailure) {
+        return { ok: false, error: remotePlan.fetchFailure };
+      }
+      return await initializeOrphanTicketsBranch();
+    }
+
+    return await checkoutLocalBranch();
+  };
+
   const mergeLegacyRefIntoCurrentBranch = async (input: {
     readonly remoteUrl: string | null;
   }): Promise<
@@ -487,60 +559,28 @@ export function createGitTicketsChannel(opts: {
       if (fetched.missing) {
         return { ok: true, imported: false };
       }
-      return { ok: false, error: `git fetch failed: ${fetched.error}` };
+      return { ok: true, imported: false };
     }
 
-    const listed = await runGitDir({
-      args: [
-        "ls-tree",
-        "-r",
-        "--name-only",
-        legacyTrackingRef,
-        ".hack/tickets/events",
-      ],
+    const legacyPaths = await listLegacyEventPaths({
+      runGitDir,
+      legacyTrackingRef,
     });
-    if (!listed.ok) {
-      return {
-        ok: false,
-        error: `git ls-tree failed: ${listed.stderr.trim() || listed.stdout.trim()}`,
-      };
+    if (!legacyPaths.ok) {
+      return legacyPaths;
     }
 
-    let imported = false;
-    const legacyPaths = listed.stdout
-      .split("\n")
-      .map((path) => path.trim())
-      .filter((path) => path.startsWith(".hack/tickets/events/"));
-
-    for (const relativePath of legacyPaths) {
-      const shown = await runGitDir({
-        args: ["show", `${legacyTrackingRef}:${relativePath}`],
-      });
-      if (!shown.ok) {
-        return {
-          ok: false,
-          error: `git show failed: ${shown.stderr.trim() || shown.stdout.trim()}`,
-        };
-      }
-
-      const targetPath = resolve(worktreeDir, relativePath);
-      const existing = await Bun.file(targetPath)
-        .text()
-        .catch(() => "");
-      const merged = mergeTicketEventLogs({
-        existing,
-        incoming: shown.stdout,
-      });
-      if (merged === existing) {
-        continue;
-      }
-
-      await mkdir(dirname(targetPath), { recursive: true });
-      await Bun.write(targetPath, merged);
-      imported = true;
+    const imported = await importLegacyEventPaths({
+      legacyPaths: legacyPaths.paths,
+      legacyTrackingRef,
+      runGitDir,
+      worktreeDir,
+    });
+    if (!imported.ok) {
+      return imported;
     }
 
-    if (!imported) {
+    if (!imported.imported) {
       return { ok: true, imported: false };
     }
 
@@ -614,47 +654,23 @@ export function createGitTicketsChannel(opts: {
       recursive: true,
     });
 
-    const grouped = new Map<string, Record<string, unknown>[]>();
-    for (const ev of input.events) {
-      const ts =
-        typeof ev.ts === "number"
-          ? (ev.ts as number)
-          : Math.floor(Date.now() / 1000);
-      const path = resolveEventsPath(ts);
-      const list = grouped.get(path) ?? [];
-      list.push(ev);
-      grouped.set(path, list);
-    }
+    const grouped = groupEventsByPath({
+      events: input.events,
+      resolveEventsPath,
+    });
 
     for (const [path, events] of grouped) {
       const existing = await Bun.file(path)
         .text()
         .catch(() => "");
-      const existingIds = new Set<string>();
-      for (const line of existing.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-          continue;
-        }
-        const parsed = safeJsonParse(trimmed);
-        if (isRecord(parsed) && typeof parsed.eventId === "string") {
-          existingIds.add(parsed.eventId);
-        }
-      }
-
-      const lines: string[] = [];
-      for (const ev of events) {
-        const id = typeof ev.eventId === "string" ? ev.eventId : "";
-        if (!id || existingIds.has(id)) {
-          continue;
-        }
-        lines.push(stableStringify(ev));
-      }
+      const existingIds = collectEventIds(existing);
+      const lines = serializeNewEvents({
+        events,
+        existingIds,
+      });
 
       if (lines.length > 0) {
-        const prefix =
-          existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-        await Bun.write(path, `${existing}${prefix}${lines.join("\n")}\n`);
+        await Bun.write(path, appendJsonLines({ existing, lines }));
       }
     }
 
@@ -670,55 +686,17 @@ export function createGitTicketsChannel(opts: {
     { readonly ok: true } | { readonly ok: false; readonly error: string }
   > => {
     const eventsDir = resolve(worktreeDir, ".hack/tickets/events");
-    let files: string[] = [];
-    try {
-      files = (await readdir(eventsDir)).filter((f) => f.endsWith(".jsonl"));
-    } catch {
+    const files = await listJsonlFiles(eventsDir);
+    if (!files) {
       return { ok: true };
     }
 
-    for (const file of files.sort()) {
+    for (const file of files) {
       const path = resolve(eventsDir, file);
       const text = await Bun.file(path)
         .text()
         .catch(() => "");
-      const parsed: Record<string, unknown>[] = [];
-      const seen = new Set<string>();
-
-      for (const line of text.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-          continue;
-        }
-        const value = safeJsonParse(trimmed);
-        if (!isRecord(value)) {
-          continue;
-        }
-        const eventId = typeof value.eventId === "string" ? value.eventId : "";
-        const ts = typeof value.ts === "number" ? value.ts : Number.NaN;
-        if (!(eventId && Number.isFinite(ts))) {
-          continue;
-        }
-        if (seen.has(eventId)) {
-          continue;
-        }
-        seen.add(eventId);
-        parsed.push(value);
-      }
-
-      parsed.sort((a, b) => {
-        const aTs = typeof a.ts === "number" ? (a.ts as number) : 0;
-        const bTs = typeof b.ts === "number" ? (b.ts as number) : 0;
-        if (aTs !== bTs) {
-          return aTs - bTs;
-        }
-        const aId = typeof a.eventId === "string" ? (a.eventId as string) : "";
-        const bId = typeof b.eventId === "string" ? (b.eventId as string) : "";
-        return aId.localeCompare(bId);
-      });
-
-      const next = parsed.map((ev) => stableStringify(ev)).join("\n");
-      const normalized = next.length > 0 ? `${next}\n` : "";
+      const normalized = normalizeEventLogText(text);
       if (normalized !== text) {
         await Bun.write(path, normalized);
       }
@@ -765,23 +743,28 @@ export function createGitTicketsChannel(opts: {
       return { ok: true, didPush: false };
     }
 
-    const push = await runGitDir({
-      args: ["push", "origin", `${localBranchRef}:${input.pushRef}`],
+    const push = await pushTicketsRef({
+      runGitDir,
+      localBranchRef,
+      pushRef: input.pushRef,
     });
     if (push.ok) {
       return { ok: true, didPush: true };
     }
 
-    const pushMessage = `${push.stderr}\n${push.stdout}`.trim();
-    if (refMode === "hidden" && isHiddenRefRejected(pushMessage)) {
+    const pushError = buildPushFailureMessage({
+      message: `${push.stderr}\n${push.stdout}`.trim(),
+      refMode,
+    });
+    if (pushError.rejectedHiddenRef) {
       return {
         ok: false,
-        error: `git push failed: ${pushMessage}\nRemote rejected hidden refs. Set controlPlane.tickets.git.refMode to "heads" to use a branch ref.`,
+        error: pushError.message,
       };
     }
 
     opts.logger.warn({
-      message: `git push failed, retrying after fetch: ${pushMessage}`,
+      message: `git push failed, retrying after fetch: ${pushError.message}`,
     });
 
     const checkedOut = await checkoutHead({ remoteUrl: input.remoteUrl });
@@ -789,11 +772,12 @@ export function createGitTicketsChannel(opts: {
       return checkedOut;
     }
 
-    if (input.pendingEvents && input.pendingEvents.length > 0) {
-      const wrote = await writeEvents({ events: input.pendingEvents });
-      if (!wrote.ok) {
-        return wrote;
-      }
+    const wrote = await writePendingEventsIfAny({
+      pendingEvents: input.pendingEvents,
+      writeEvents,
+    });
+    if (!wrote.ok) {
+      return wrote;
     }
 
     const committed = await commitAll("tickets: retry");
@@ -801,18 +785,23 @@ export function createGitTicketsChannel(opts: {
       return committed;
     }
 
-    const retry = await runGitDir({
-      args: ["push", "origin", `${localBranchRef}:${checkedOut.pushRef}`],
+    const retry = await pushTicketsRef({
+      runGitDir,
+      localBranchRef,
+      pushRef: checkedOut.pushRef,
     });
     if (!retry.ok) {
-      const retryMessage = `${retry.stderr}\n${retry.stdout}`.trim();
-      if (refMode === "hidden" && isHiddenRefRejected(retryMessage)) {
+      const retryError = buildPushFailureMessage({
+        message: `${retry.stderr}\n${retry.stdout}`.trim(),
+        refMode,
+      });
+      if (retryError.rejectedHiddenRef) {
         return {
           ok: false,
-          error: `git push failed: ${retryMessage}\nRemote rejected hidden refs. Set controlPlane.tickets.git.refMode to "heads" to use a branch ref.`,
+          error: retryError.message,
         };
       }
-      return { ok: false, error: `git push failed: ${retryMessage}` };
+      return { ok: false, error: retryError.message };
     }
 
     return { ok: true, didPush: true };
@@ -995,31 +984,20 @@ export function createGitTicketsChannel(opts: {
       return pushed;
     }
 
-    let didPruneLegacy = false;
-    let pruneError: string | undefined;
-
-    if (input.pruneLegacyRef && legacyRemoteRef && checkedOut.remoteUrl) {
-      const prunedLegacy = await runGitDir({
-        args: ["push", "origin", `:${legacyRemoteRef}`],
-      });
-      if (prunedLegacy.ok) {
-        didPruneLegacy = true;
-        if (legacyTrackingRef) {
-          await runGitDir({
-            args: ["update-ref", "-d", legacyTrackingRef],
-          });
-        }
-      } else {
-        pruneError = `${prunedLegacy.stderr}\n${prunedLegacy.stdout}`.trim();
-      }
-    }
+    const pruneResult = await pruneLegacyRemoteRef({
+      pruneLegacyRef: input.pruneLegacyRef,
+      legacyRemoteRef,
+      legacyTrackingRef,
+      remoteUrl: checkedOut.remoteUrl,
+      runGitDir,
+    });
 
     return {
       ok: true,
       didCommit: committed.didCommit,
       didPush: pushed.didPush,
-      didPruneLegacy,
-      ...(pruneError ? { pruneError } : {}),
+      didPruneLegacy: pruneResult.didPruneLegacy,
+      ...(pruneResult.pruneError ? { pruneError: pruneResult.pruneError } : {}),
     };
   };
 
@@ -1176,45 +1154,325 @@ function mergeTicketEventLogs(input: {
   readonly existing: string;
   readonly incoming: string;
 }): string {
-  const parsed: Record<string, unknown>[] = [];
-  const seen = new Set<string>();
+  return appendJsonLines({
+    existing: "",
+    lines: collectNormalizedEventLines([input.existing, input.incoming]),
+  });
+}
 
-  for (const text of [input.existing, input.incoming]) {
-    for (const line of text.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed) {
-        continue;
-      }
-      const value = safeJsonParse(trimmed);
-      if (!isRecord(value)) {
-        continue;
-      }
-      const eventId = typeof value.eventId === "string" ? value.eventId : "";
-      const ts = typeof value.ts === "number" ? value.ts : Number.NaN;
-      if (!(eventId && Number.isFinite(ts))) {
-        continue;
-      }
-      if (seen.has(eventId)) {
-        continue;
-      }
-      seen.add(eventId);
-      parsed.push(value);
-    }
+async function listLegacyEventPaths(input: {
+  readonly runGitDir: (input: { readonly args: readonly string[] }) => Promise<{
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+  }>;
+  readonly legacyTrackingRef: string;
+}): Promise<
+  | { readonly ok: true; readonly paths: string[] }
+  | { readonly ok: false; readonly error: string }
+> {
+  const listed = await input.runGitDir({
+    args: [
+      "ls-tree",
+      "-r",
+      "--name-only",
+      input.legacyTrackingRef,
+      ".hack/tickets/events",
+    ],
+  });
+  if (!listed.ok) {
+    return {
+      ok: false,
+      error: `git ls-tree failed: ${listed.stderr.trim() || listed.stdout.trim()}`,
+    };
   }
 
-  parsed.sort((a, b) => {
-    const aTs = typeof a.ts === "number" ? (a.ts as number) : 0;
-    const bTs = typeof b.ts === "number" ? (b.ts as number) : 0;
-    if (aTs !== bTs) {
-      return aTs - bTs;
+  return {
+    ok: true,
+    paths: listed.stdout
+      .split("\n")
+      .map((path) => path.trim())
+      .filter((path) => path.startsWith(".hack/tickets/events/")),
+  };
+}
+
+async function importLegacyEventPaths(input: {
+  readonly legacyPaths: readonly string[];
+  readonly legacyTrackingRef: string;
+  readonly runGitDir: (input: { readonly args: readonly string[] }) => Promise<{
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+  }>;
+  readonly worktreeDir: string;
+}): Promise<
+  | { readonly ok: true; readonly imported: boolean }
+  | { readonly ok: false; readonly error: string }
+> {
+  let imported = false;
+
+  for (const relativePath of input.legacyPaths) {
+    const shown = await input.runGitDir({
+      args: ["show", `${input.legacyTrackingRef}:${relativePath}`],
+    });
+    if (!shown.ok) {
+      return {
+        ok: false,
+        error: `git show failed: ${shown.stderr.trim() || shown.stdout.trim()}`,
+      };
+    }
+
+    const targetPath = resolve(input.worktreeDir, relativePath);
+    const existing = await Bun.file(targetPath)
+      .text()
+      .catch(() => "");
+    const merged = mergeTicketEventLogs({
+      existing,
+      incoming: shown.stdout,
+    });
+    if (merged === existing) {
+      continue;
     }
-    const aId = typeof a.eventId === "string" ? (a.eventId as string) : "";
-    const bId = typeof b.eventId === "string" ? (b.eventId as string) : "";
-    return aId.localeCompare(bId);
+
+    await mkdir(dirname(targetPath), { recursive: true });
+    await Bun.write(targetPath, merged);
+    imported = true;
+  }
+
+  return { ok: true, imported };
+}
+
+async function pushTicketsRef(input: {
+  readonly runGitDir: (input: { readonly args: readonly string[] }) => Promise<{
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+  }>;
+  readonly localBranchRef: string;
+  readonly pushRef: string;
+}): Promise<{
+  readonly ok: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+}> {
+  return await input.runGitDir({
+    args: ["push", "origin", `${input.localBranchRef}:${input.pushRef}`],
+  });
+}
+
+async function writePendingEventsIfAny(input: {
+  readonly pendingEvents?: readonly Record<string, unknown>[];
+  readonly writeEvents: (input: {
+    readonly events: readonly Record<string, unknown>[];
+  }) => Promise<
+    { readonly ok: true } | { readonly ok: false; readonly error: string }
+  >;
+}): Promise<
+  { readonly ok: true } | { readonly ok: false; readonly error: string }
+> {
+  if (!(input.pendingEvents && input.pendingEvents.length > 0)) {
+    return { ok: true };
+  }
+  return await input.writeEvents({ events: input.pendingEvents });
+}
+
+function buildPushFailureMessage(input: {
+  readonly message: string;
+  readonly refMode: TicketsGitRefMode;
+}): {
+  readonly message: string;
+  readonly rejectedHiddenRef: boolean;
+} {
+  if (input.refMode === "hidden" && isHiddenRefRejected(input.message)) {
+    return {
+      message: `git push failed: ${input.message}\nRemote rejected hidden refs. Set controlPlane.tickets.git.refMode to "heads" to use a branch ref.`,
+      rejectedHiddenRef: true,
+    };
+  }
+
+  return {
+    message: `git push failed: ${input.message}`,
+    rejectedHiddenRef: false,
+  };
+}
+
+async function pruneLegacyRemoteRef(input: {
+  readonly pruneLegacyRef: boolean;
+  readonly legacyRemoteRef: string | null;
+  readonly legacyTrackingRef: string | null;
+  readonly remoteUrl: string | null;
+  readonly runGitDir: (input: { readonly args: readonly string[] }) => Promise<{
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+  }>;
+}): Promise<{
+  readonly didPruneLegacy: boolean;
+  readonly pruneError?: string;
+}> {
+  if (!(input.pruneLegacyRef && input.legacyRemoteRef && input.remoteUrl)) {
+    return { didPruneLegacy: false };
+  }
+
+  const prunedLegacy = await input.runGitDir({
+    args: ["push", "origin", `:${input.legacyRemoteRef}`],
   });
+  if (!prunedLegacy.ok) {
+    return {
+      didPruneLegacy: false,
+      pruneError: `${prunedLegacy.stderr}\n${prunedLegacy.stdout}`.trim(),
+    };
+  }
+
+  if (input.legacyTrackingRef) {
+    await input.runGitDir({
+      args: ["update-ref", "-d", input.legacyTrackingRef],
+    });
+  }
+
+  return { didPruneLegacy: true };
+}
 
-  const next = parsed.map((event) => stableStringify(event)).join("\n");
-  return next ? `${next}\n` : "";
+async function listJsonlFiles(eventsDir: string): Promise<string[] | null> {
+  try {
+    return (await readdir(eventsDir))
+      .filter((f) => f.endsWith(".jsonl"))
+      .sort();
+  } catch {
+    return null;
+  }
+}
+
+function groupEventsByPath(input: {
+  readonly events: readonly Record<string, unknown>[];
+  readonly resolveEventsPath: (tsSeconds: number) => string;
+}): Map<string, Record<string, unknown>[]> {
+  const grouped = new Map<string, Record<string, unknown>[]>();
+  for (const event of input.events) {
+    const ts =
+      typeof event.ts === "number"
+        ? (event.ts as number)
+        : Math.floor(Date.now() / 1000);
+    const path = input.resolveEventsPath(ts);
+    const list = grouped.get(path) ?? [];
+    list.push(event);
+    grouped.set(path, list);
+  }
+  return grouped;
+}
+
+function collectEventIds(text: string): Set<string> {
+  const ids = new Set<string>();
+  for (const line of text.split("\n")) {
+    const value = parseTicketEventLine(line);
+    if (value && typeof value.eventId === "string") {
+      ids.add(value.eventId);
+    }
+  }
+  return ids;
+}
+
+function serializeNewEvents(input: {
+  readonly events: readonly Record<string, unknown>[];
+  readonly existingIds: ReadonlySet<string>;
+}): string[] {
+  const lines: string[] = [];
+  for (const event of input.events) {
+    const id = typeof event.eventId === "string" ? event.eventId : "";
+    if (!id || input.existingIds.has(id)) {
+      continue;
+    }
+    lines.push(stableStringify(event));
+  }
+  return lines;
+}
+
+function appendJsonLines(input: {
+  readonly existing: string;
+  readonly lines: readonly string[];
+}): string {
+  if (input.lines.length === 0) {
+    return input.existing;
+  }
+  const prefix =
+    input.existing.length > 0 && !input.existing.endsWith("\n") ? "\n" : "";
+  return `${input.existing}${prefix}${input.lines.join("\n")}\n`;
+}
+
+function normalizeEventLogText(text: string): string {
+  const lines = collectNormalizedEventLines([text]);
+  return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+
+function collectNormalizedEventLines(texts: readonly string[]): string[] {
+  const events = collectUniqueTicketEvents(texts);
+  return events.map((event) => stableStringify(event));
+}
+
+function collectUniqueTicketEvents(
+  texts: readonly string[]
+): Record<string, unknown>[] {
+  const events: Record<string, unknown>[] = [];
+  const seen = new Set<string>();
+  for (const text of texts) {
+    appendUniqueTicketEvents({
+      text,
+      seen,
+      events,
+    });
+  }
+  events.sort(compareTicketEvents);
+  return events;
+}
+
+function appendUniqueTicketEvents(input: {
+  readonly text: string;
+  readonly seen: Set<string>;
+  readonly events: Record<string, unknown>[];
+}): void {
+  for (const line of input.text.split("\n")) {
+    const event = parseTicketEventLine(line);
+    if (!event) {
+      continue;
+    }
+    const eventId = event.eventId as string;
+    if (input.seen.has(eventId)) {
+      continue;
+    }
+    input.seen.add(eventId);
+    input.events.push(event);
+  }
+}
+
+function parseTicketEventLine(line: string): Record<string, unknown> | null {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const value = safeJsonParse(trimmed);
+  if (!isRecord(value)) {
+    return null;
+  }
+  const eventId = typeof value.eventId === "string" ? value.eventId : "";
+  const ts = typeof value.ts === "number" ? value.ts : Number.NaN;
+  if (!(eventId && Number.isFinite(ts))) {
+    return null;
+  }
+  return value;
+}
+
+function compareTicketEvents(
+  a: Record<string, unknown>,
+  b: Record<string, unknown>
+): number {
+  const aTs = typeof a.ts === "number" ? (a.ts as number) : 0;
+  const bTs = typeof b.ts === "number" ? (b.ts as number) : 0;
+  if (aTs !== bTs) {
+    return aTs - bTs;
+  }
+  const aId = typeof a.eventId === "string" ? (a.eventId as string) : "";
+  const bId = typeof b.eventId === "string" ? (b.eventId as string) : "";
+  return aId.localeCompare(bId);
 }
 
 function isRetryableTrackingRefLockFailure(input: {
diff --git a/tests/tickets-extension.test.ts b/tests/tickets-extension.test.ts
index dc336da44..6e35d3a0f 100644
--- a/tests/tickets-extension.test.ts
+++ b/tests/tickets-extension.test.ts
@@ -260,6 +260,116 @@ testIntegration(
   }
 );
 
+testIntegration(
+  "tickets extension: list and show fall back to local tickets ref when origin fetch fails",
+  { timeout: 60_000 },
+  async () => {
+    const root = await mkdirTempDir({
+      prefix: "hack-cli-tickets-offline-read-",
+    });
+    const projectDir = join(root, "project");
+    const remoteDir = join(root, "remote.git");
+
+    await mkdir(projectDir, { recursive: true });
+    await copyDir({
+      from: resolve(import.meta.dir, "../examples/tickets"),
+      to: projectDir,
+    });
+
+    await run({ cwd: projectDir, cmd: ["git", "init"] });
+    await run({
+      cwd: projectDir,
+      cmd: ["git", "config", "user.email", "tests@hack"],
+    });
+    await run({
+      cwd: projectDir,
+      cmd: ["git", "config", "user.name", "hack-cli-tests"],
+    });
+    await run({ cwd: projectDir, cmd: ["git", "add", "-A"] });
+    await run({ cwd: projectDir, cmd: ["git", "commit", "-m", "init"] });
+
+    await run({ cwd: root, cmd: ["git", "init", "--bare", remoteDir] });
+    await run({
+      cwd: projectDir,
+      cmd: ["git", "remote", "add", "origin", remoteDir],
+    });
+    await run({
+      cwd: projectDir,
+      cmd: ["git", "push", "-u", "origin", "HEAD:main"],
+    });
+
+    const created = await runHack({
+      cwd: projectDir,
+      args: [
+        "tickets",
+        "create",
+        "--title",
+        "Offline-readable ticket",
+        "--json",
+      ],
+    });
+    expect(created.exitCode).toBe(0);
+    const createdJson = JSON.parse(created.stdout) as {
+      ticket: { ticketId: string };
+    };
+
+    await run({
+      cwd: projectDir,
+      cmd: [
+        "git",
+        "remote",
+        "set-url",
+        "origin",
+        join(root, "missing-remote.git"),
+      ],
+    });
+
+    const listed = await runAllowFail({
+      cwd: projectDir,
+      cmd: [
+        "bun",
+        resolve(import.meta.dir, "../index.ts"),
+        "tickets",
+        "list",
+        "--json",
+      ],
+    });
+    expect(listed.exitCode).toBe(0);
+    const listJson = JSON.parse(listed.stdout) as {
+      tickets: { ticketId: string; title: string }[];
+    };
+    expect(
+      listJson.tickets.some(
+        (ticket) =>
+          ticket.ticketId === createdJson.ticket.ticketId &&
+          ticket.title === "Offline-readable ticket"
+      )
+    ).toBe(true);
+
+    const shown = await runAllowFail({
+      cwd: projectDir,
+      cmd: [
+        "bun",
+        resolve(import.meta.dir, "../index.ts"),
+        "tickets",
+        "show",
+        createdJson.ticket.ticketId,
+        "--json",
+      ],
+    });
+    expect(shown.exitCode).toBe(0);
+    const showJson = JSON.parse(shown.stdout) as {
+      ticket: { ticketId: string; title: string };
+    };
+    expect(showJson.ticket).toMatchObject({
+      ticketId: createdJson.ticket.ticketId,
+      title: "Offline-readable ticket",
+    });
+
+    await rm(root, { recursive: true, force: true });
+  }
+);
+
 interface RunResult {
   readonly stdout: string;
   readonly stderr: string;

From ebd9e390cdf6858bb0651dbdd2af30b1310f2ba7 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:08:11 +0000
Subject: [PATCH 062/134] HACK-449: checkpoint merge prep

---
 .cursor/rules/hack.mdc                          |   6 ++++++
 .../hack-449-normalized-ticket-model.bundle     | Bin 0 -> 11271 bytes
 2 files changed, 6 insertions(+)
 create mode 100644 artifacts/hack-449-normalized-ticket-model.bundle

diff --git a/.cursor/rules/hack.mdc b/.cursor/rules/hack.mdc
index 835164c17..8f55277b3 100644
--- a/.cursor/rules/hack.mdc
+++ b/.cursor/rules/hack.mdc
@@ -37,6 +37,12 @@ hack down
 hack global status
 hack session
 hack tickets list
+hack node list
+hack node status --watch
+hack node ssh setup --node <id>
+hack node routes status
+hack node routes repair
+hack dispatch run --project <name|id> --node default --branch <branch> --runner generic -- "pwd"
 hack internal extra-hosts list
 hack internal extra-hosts set <hostname> <target>
 hack internal extra-hosts unset <hostname>
diff --git a/artifacts/hack-449-normalized-ticket-model.bundle b/artifacts/hack-449-normalized-ticket-model.bundle
new file mode 100644
index 0000000000000000000000000000000000000000..5548df9950f8825da5d0cfca17a83918d93b1297
GIT binary patch
literal 11271
zcmV+iEcnwSAa*h!XK8dGVs&n0Y-I{9I5jggH85r{Vq!C6GB;ymVK*@~GdN>5W;r-v
zG-WkoHaR#rWnpGDAY*86a%CuTWo%_(b7d(yATcg6H!d*>WMwomV`X78H!wA3Vly)_
zI5K27H#lWtF=043I5aV2VqrNkVl_E8AaZ49b1!IRVPtbJXklY(Ei^PaEpBgeZDDL_
zdSzrSbZKL2WppiVZ)9a`3JOp`LrVYv00IC201llIc$}q=OKt-p5JdN!qL+yxMKI6<
zSXPupc0L84CP5w;3wIXI>5Vi;NUf?~wOT43M3AM%q&!AbFebg&X;)7at)b{u@zQEJ
zk+_9Hox!0tD2t3yr^TietU~S5TD%K}Fs<G>3I#>@<)3}PS8bI?g$wmg`2pvAfa{Sz
zzgwu=d)nIvC~LJb3he@Ka!O1(Z<+r0MHCAB!Zlrq@2@AwRB9*a`)FaSf0W_qV9u-j
zfVOAa#1j=|TMYUIOi0y<MQ*prwnImA9Fh+3rr9Qgc$@)R0Hy!#4DJlDsRR_Y0^`og
ze1Hs>!dkP#-$-?iqUT?;y#y`+G-b<5IU>Kv>Hzj#24c$OQ#=e~I5aRYFfbr=Wpi|M
z07N0NcKHuIM!<xGmd%sIn1tcgNRuB1PjAX7nD7G36K>M?#B}o}Um2noT;O670!C|i
zoO{9if_Z}!qew+poS&rEiXy?cojPe+7V<$Y*E=WcG428Y#sds3{05Hmu!?f1)tgeu
zB1*)aF_l@*^bL5N0c-%1|E&e#1(53$2gcDFe!8lIw!vp9^+cpl4|FUlvHz9<Of7D2
za&2L3X?kIFX>V>WZDatkU-&;gvI+QAzAx*&uk);)qch4eFfcYWG$3?oV{2t}b1rRU
z0H-M?D<LAfKuiW<ka)Uc>TkMbCqcR{Uh@(H^V^%$9~Qr0k?ySNJ4tkYDA}!eoJEgK
zP6IIvg;#XZ0{}~}k!EreHgt(ZLhR{8P3+3{&<>j(h6`{Yj==$lDgnzUy`S%W-G1MH
zzHBbLnSe!Gs^y&!l#VrJYQzqcDELf9FxAv$p^65@0BI`R&4nSNWDEPHAX)H|59Bud
z_9ZXEW5c*jj1Wz8$il8thrYrT=zMWv>#o0W_=g#qAl1<=j_^n)u$6N#7fpMDljs3#
zmZc&bl_t`y&z-V^7hmC37RID2$Qvmn#KL=Mq6Cr7PRgl1#D3}S`pE_2?z;c9wAN$s
z<9T!Q11bt_ld#hQc$~FZO_Lk95xvi^Kv9=OMRF_Gm1EaNQQ1l?S*2BygUjUsXPP9u
z7+?Zmmdn`s?|I$8d~kQ|at=9cEe8Yi^w)dcjTh>ZY3?XR_1=e0Tk{{CjCbmtZ^>5G
zrz0s>UQnx2+1v43Wz9WBWt^&GXs#OXQt)=uTkYtI9um0-N%5*2x|-!|<oq_pdRx6s
zs-?Ygkd*MTMmz6Jqpc#BOggK0)IH&qPAVoJ^nsLit<tUT69pB|uE8EZ*j7P<dkWY9
z{dctYfzMH8>7bjl+FOXIv$eNF*XeMsRUiCM)QH6<szAvEYPVJO;)VL!Ya6R-qyA3R
zL*!DoY|^MAzND<j`o=qZ7WLWzPe<RuXD1)-wh;49-_dx`2XioPt=LP!X?CT%i)%T$
zHw0VskdD{|>GaTB)0ng!Re{d;rlqinJvC-;8rABgl^-B?zfe*HMLu?$^jRIqQNU($
zemERO>2Kk79oFh=lfD^t`SUkXJDol7CYyK55vZ!Vu2Zbi8PRw@MKZgyZ2YtOxl$@N
zN9y!HDRA_!)t|6*XIy)&R@wL!77QL^3dSAqFll@(=M|ikEG;%Dwe#)ytBaMGbQ&Ur
z`kvfM{i0UJ{Rqz-0>voLJA~wpTKU}~d@DJpV>AaxbSbT*0TzFTZqvJ0%IR+2sy=7+
z^dXK*-~S*>fvmtL9!(!dGZYdV%C+%3_h>r|V&xu7DdJ5>u&!GQY69s*?M=GSTB)IL
zpIK)){KttxPP>LiNjdMX%jsWWZ3&H}@9Guc6ccq=IO^tZRW!QTIi~D#vz0s&PajM=
z4m<g&Ig_xBbNg-k$cd8h*H1DD8F^Q{F(KgTuAA|d82Xu0Qxf*WWH8b-+gc;3;|a;A
zPDjdwFoF<H4shNzW4smz)T$$FUvA1$*vU+E-@q$^k`90ZfcT&DNgee)2^C?RSf<V-
zfUQS&JtO+0L7rXjSqZfdzEgU_wtS@b#(``>TYPHt2NDe*<F9NNR)W273~!34=!ekA
zHUed?MayOg0hFcu2~5DLx>Yx$G5{ev<gALsZFWd?IvUH2J5yDTI)703dMT4#B7_Xj
z9@qg@E#9bA3h-Q1q?_X`X^EPN=Ir_UH@Sv0q%h58Vlnmno`l3clqq8B5KHA%j-C7r
zv`3=gaU~L6^H<aaDG@l*57x@Aeu&3RGo~Hi0~AbW-nsnz)d)L8bq_bbZ7*3zH;o@$
zdc4d9Blfy^vVVH<e#uG&?14I;CZJysEC`q$(dQ8C<pNi4Z8$Gx)+vZD<S5oA(p~XV
z@8!p&RQ86~A-mC<m{vv5BW=_rt!B;=)UzR_vcIFGxvpW`M{0a%zsS4SrD3_vWk%b9
zz8opwU&p!3%?1Ib2?7P@x#FoIqTQ&AVYPs*X47hH$;Gg2VKaGAs$yB2EUwqH4Ez+^
z@dF^J+4`E>Cm$)}YSBd*hcwkKS8KyPQ#&+Fj2$;D6JdPFf?w8~n9hJ;^8LorJ<WBU
z8E<C7YWm60lm-i*iqz`>_Ci}Cw2)IC-BF`q3<!rYG&OdG1&n2EcDfMWhOx~}(Qlw~
z{&<EaS~@-0^l`9LO7<T32AOl}*fC#p&lNI5kkXHX18j2EoD5(Tq#|F`DD`<+jYbGx
zEV50{*B$;7_pxHg^be>2M%ypsizUsblDCpRWHmo?7qWQFEy!YF>@5~cBX$--(LF34
zrxs!P9cd0$>#{P!@qc#V|ILkav+`xde+7Q8OD!nDj~Q{fG0u5cMuBTpFA@YPQ|!4a
zMQ5Yl6cqg4gQW~|#bpOG94F5THpQhi&QCrPcp6~`P)VFBS)mB2V>?1+Hvn`lgO>0F
z9|R95aRXhr0>6YH=8jyFteOg~LZPFOA)ARyy><6G7>xp-r>xvIGj_oVJXml&0c_dr
z4Np24fgE=TmT~#F+wb1z(THpKJ)qb=ozqk|#H29A_$s2%#{HQ~HelZbALAxSzN;Wm
zkS1tu7`IZlzkm6|Hiy6FZw&B~21mht{~idbm5zp0%3s_5O0bz!r2Ehz@NhJC81;tB
z@Z|`!{q@jiW27bGj!5UYaWpRFu^3TJ+LMSvgP2QSAUuzJt&2(gu^V?@j9M8i`E-4W
zgLT1y`dnvCrZ%CFXdY4N0mL790OiS3<?qk_sdt01?Q<>7AO2Y9Fd|W6Ddwn~oCwGz
z6fv$*|M>WAM9<Gu?$R1P-ZTa`;QKsEv8$;w2_uGvR-#&tbmWFZL~>$DxbkEiWg0g4
zZnix4jx~x0I!}Mm{7wC-_`tZv4lPZgVCRloZ)cy+i}3m@iOVjS7K3^qW=Br>#&^A?
zbeRv_x-P1vbU7zPilYt-(Ld`vcuy`a71vDQl7u~RXgZm{@$Gzh(ZeYQTNmT-c)!q@
zLy*RF&0WMEoXg>k-VU-@$p8QjGMmXA!WN6V{u8@rN35t;t#5{o-Ok7J9YKa}F5xAF
zW5c8Vf~K(50VVzQqgkFc>^b}EX=W}x$Ozj4h4u4T&S_Q4pkFO_Ob`GlsyFu(&Pky4
z^s3?D%azZgHVs1Ah4i2~j>}$)%Ot0AWSVTwjg^PF(Xx8S;m~L6bsN|4KKLl{eT(5o
z95OM2Zlv$%%IBt*tbwDMjI)0@h~srmE5r(C?TSA^-ziQ(2Da%z@?pW7MGV7$uTyXi
z&`a<ZJA>FSGXjdnIf(DZlvzaY(_%cr6tdar=5BF^#)?qswmL2kMwEz8?x+Nm`SxlA
z$IH4ZU7)Hb^)s3;4l}EiL9HOp>T|9o42V9zDi>tSyD*o0^~g8nvI_%?v9lLrL5nnq
zuYJdPo<Vn6#>(wfY&@dKnUc8nHgZR|yiD6Fxa~Z)pJV%4_EaO08Fw*!W>+#S%S|Bq
zTi*%VP2kaVX-B>>9Ks%bgM#qmR9mx8nY`=gZ@7St{{nbqM{4{AC!b)TDxMk-wi|e#
zDZ9C#l`<y-c$~YZv|o9{WS)3kg^-L?g}l^?65ZmG)B=UP{G!~%oXo1!6ou5hlFX7y
zh1~p<)EtG(Vuh6a<kDQAAW$kZPay%wE!Iyj%}hxx)-TCS&Q2{U)`jU#EXmBz)5}ds
z*gTQvEDHd@(kXcV0kt@F_>Js27>df&%47%=)ib{2)Oehm#xjj%!a<P<YRYCuT9+!Z
z9Qcx{k{TqJDSqa{#;cBu0K-oVx26bqoHH>10)^CylGME7%>2A!2Ie;lmU=9ch`YAx
zc+l^vw#@teOP-p56&2*?WF}WK*qtbzeE-vD|7or2S(|Qhm!!?*eFITYlwVqsnU~HW
zpJ19$8Bisve}CD&vuo?`SZ?KC1W{3(lFh)g<%qC@x!o=KT}u}H_0)f&x7O$x0M_d`
zx$pu|Htn$v7F{&b)1lh4>hX4J&|_$LoV&<;k$J;RMv;J<Tc2OIWqeRl<}bn}nDjVI
zWuM&SwTvnN=vfUZ@&k)y=ooHiWUOqiLl?P0k^eFLo}74`0Wtv1|M3E#1CW0xZf|mJ
zVQgu7Wn?XFZ)9a`E_8DMjzoWw&g;ol^1fnn=x3vTt=XB@k$Cwqf*AX@n+$lIwLD#O
z+c=W%{uPKSm6E13n%!4<9G5rasnx|}Pub4i?WJ51Ey6a>5~(GrWPFbP`vK?%(D)*0
z@7z30WTMe%H2S+i7MpEVx2%2Ia`w!wi`64<uXdYFRzI;lyQ`}W8_j-d+N$QWwiz8B
z9PmHXj8#=OEjz!s{O#my@!zMve7RnH_;`B#<?6%VPk%f4@{iNYtHs4RJ7RxjSp(4i
zWIf~h<oeUq>6L)}e8AYK+VXNVmA{Je%eJoWYu+^Q;C5XJ0(1ByuSza{-6Zj!{@3;C
z<@w2(A?=@6*QdX!bw=x=<XJtMveA9fKJ0GgudK<+Y?Q`_XwDYrAHRIKIKMtwoS$BP
z`M5a$#n3Lu{U5$+fxwn$8~9c8Z3Vx+RrO=D%~l*YRAn`8XI(UH=XP-UlTX)wzqnjn
z|MSbQi_<f^bX&A*gEfDGUrn2}J7iwgG{t?%5yqu7yGNj$3-0I5MM)UmB*;=igCe8W
z5u}Xe!|KjI+sWs0x4Gr@&7m{-^pBR;Wwu5nPfg1=1WDom6UYF`Sy4WIsLD1I2V8$F
z%A6gEjd*0mj<6H!$*z5<>Y{!6wczVK+^2si1X+w*s|UWx{*kSBTv7L(HEms#_v$B1
zR6lR4YR$6}AFtQyN6j-K`Rk_;*XJ7r@N7XoKk}zJBEOkOR^NN{o$>o@_2im?BiAfM
zcjRzg%y<@*7%CpcDa=#Hb4VeJTvO{jF0&0kwj(~#4(3t_by1Z*4MN=SiZx&4$I%tC
z)vDT+ZEDzPZ7;xiH>u}Uy~)<a|MJ`t?UO1@)8it}h(>A1JgPSiU@Zh^E=*}%+!y6Y
z2*s#*Dp$gC%AYmA<24t5jy&Y$>X)Jh{)x$3A#n<RyK5fQkJ}>G<JsDsyfU0Wo<|SF
zC68~aRuCxnojiUjLHy}BF|@1KsiBpYvu5sVjU$GiZ{)<iD-e0M6+Hfpx8hfui6vgB
zR&gOUcH}>cQfZ2>v7jp>VRi+F**-C>&ownJMQC)G5~)DzJ=!jJYaZxNwJug-)6$i#
zrTdcdkZq;20P*7Omt85&*%ga#YMVwRyzTevhne8hlk>Z5w{9h=0do1!q2f*&ZTVCP
z!tYt#7TNk|B`TMERn_^=F&jUPVSO)Vz3->`LLHAjT(weQ4)KT&{ZXyrqlawuh{O9%
zL>!Gl8du6(IKZLVVS%9d8$B)C$k{ZY2}19bAwf^s7b-d@hFfdZDx)DjVwIIuSqPQ}
zRz(Fy2@@eBrIh)A*lF%WI39=&sZuB~$U2^fhgam@q_n@olW;dBBDOiDRf2*cbL{Lo
zlg77sD7H<62ovokQBhv0STG40P*`lZVBsdZ@Jjq@d4AF+d9d5&F^GL=ss)q3@-h?t
zEI4|wlk<dvdIU=apxcZ2>VU(UHV@$<#&RIZLt=qNx!tvaJ`MKz%B?112N?Y5c~Woq
zljlt%zVvvAGj#%y<B&Ismm@hia^amIBstN6@-VzC68Y2pydgLeN=Hu@Y}`B+dOMV^
zk;}r|CpO03`SKsxov&wodvw)K?pAFRAb!4n9|Q_n-3Ub-7jmz2wksdY>RUNsNAKCS
z!!1Z^%aqc<0&~4kQn}tMHw)Wx)>ccZC&{@8I6ZJYU7Rp*bv;x8kmkuia$u67MN;z9
z4?i5RAK2e^#X4_Trc7Ls^ZLi^zN{J{F-$vsB^HAFGLB*GL)MB|nQt3AquKIRaaXJ)
zJ}CpNC>t@rmY!@ZS)H{HA|w?^O7TB#Jt~SQgi*~*VEW1B)vcs6k=l#}BTyES2Jc`J
zACxSUjD%IRbrVPx!kK<B6T-V0PYyjuVd?~^Ime4F<Skc9)W;NsfDC2}OE_@0fF!f6
zp`_D|d2Dbh0XsfspKn|YHi@Me@TtXs56E2aP$_~FcL=d~69g)Q%W8l;i_{6B>gnil
z`SuwQgVWm2-#+VO+ApUHRJ$_@2P2TRB5%cS$r_!w>bXvis!@=KYL1(z!qnMpHYTh+
z7KWbuxo5&Q?k7lxlb$jaa_U`7@tH(t<xFBzhSWZCFj9CaSrT4ku5%)69=sJ0c(S*<
z@DEuc^PdrHdv&HYZ+CSWw?OhF$L?`Y4yhsf9pcyq?82_Dc`3|+h%L2gXs}jPlx?Me
zEH=g=NoXE2;WwH};*<5{?4Gl%%+--<@*8P%<kr9PS`3SGsY;Id1iR&TRm~N4{#6p7
zs?ri&(XdT%U(0wgVx7tkkDM@2Dc>D4R5}L&QzbG2UbiqGXI`S@aAN0Yz&E0~YtSZT
zO639kT2~tf%^0LnhYJ+V)Tkf^2zr=2Qj$Q{t1w3uIY3=}<q#1MTEoYbksKY6SqBUF
zU@d<hCP&mpp`76~sdkiv8P3p3DAS}kgsj5p<s$YheTb;?UIyEjx&k?F&N_{60shfD
z2$EK&vsG`Bc!pk%+7kyzrn2nK(UAzba(*W)N3INmeC(l9ke<2G$*uzk59x~C{t&0>
ztaySG8CWQM>aC$4<Mvdo1O5xlrxqBAP5<_`0co+J5~w>Xn%1RIf|)sqB$?6dxEG^=
zHE5Yhn0qG!pqaThyNRUGjONY`7W3RvK$2(&)I9f=#DBt!n(DB&1A-`Jv_$wK|Gg0>
z@%csr7^6TCJC3L;zMd&BMLZIEBNA;!O{BEuXv+VD6sy-8s4k+OAhXbYDvte5l+uZ5
z8{P6Ud(}xkr1!3zaAzzCSygB}NJBNEMXrz(cWnG-jI_LaXV6V1CZSYkW;UU+L2FrQ
zp*>m>kUh$q!1BMG-rx1a(2Yow|4MXns^Np7P4C@qZYCQcW33Qq?r9%YTYS$?Io3<j
zDJ>XyFZ$H6W#B0ZlVvyg<s7?Kv&`-Q$-u3d{<Yp0%ns;7=}2aQh}VhqooLzw&7PUk
zn-C)u@RJOjqkv*$>g~+QEE=s{I^2neI$ACF+JhaNmdk<mO`Um3Gy$>MMj||8eiR>p
zJN7d+9p+g3NCUb*!y+cCaB*{|mjxpyMGoR1vkzfkyeE+A9f`=r^tBMiO8Pf(lxM{w
zS0yP|(wk~mulPhEAV}c|1sczWc`|OACngYbvQvVJy1qs30KlUusgx15c&5Q2G=1DW
z7&<*uTVSKdNE=|$lk6*T#}0`grOv3Yr=}`x`s85U*`vB)A<xcm(&&s0Sy<RVoRUH4
z63Wu6-`})Qd!u=;N2|N41nXgNQiKZtN4tk6N>_2FrNq!-`=CKIN5aXMP1JGZOJ?l@
zdFstfF&FMI4Kn@xS`~f_qZII}FOqT9)r1{%wyUb1|8s+%{)PUXU@0CZ0SCbZDLQ?U
zgc>-^Afc3-nZX$um63f9H7{pt#dTd)srkQl!jClmO0sTZiIW=VcmUte{kvYEy8$IF
z4Bk|dg7HeD-5|CDFIoTHR0*P6C=wTP{3}C~`9ZXY{?azA!jcH)i~i`Wppk1iBxEgV
zaQbE}*7*Ki&Fl%zJ*%e51yB(X|2UDR%Ij%V>J<<7;h{M9tVjVZ+La>wk_My?hQ<zW
zuyryh3o%!`dU<LfX%$P~0PCG?AjxcUL9BN^fsJ7pl*l;HP~-ynuuKqQV)rEepd`{i
z&--O5CQNoAEXUwqfoNGGR29hl6#!BKB`Ezn4Q%o$_sI|uwtX5R!ri^?K!9zAODzE{
zH4aIL8_rd;hks*Ny!{z0&igSO>|Ir}v6pDG>W(?OF~9<u$=V8O9W(hL<V{6sy1oQ;
zkFm1Ijlt40A5|Z2`S#hu$aqY)hKhW@w3J9L%pS64EM`o)X;PqBo-5EpH(AJI$*jA!
zO=_LuX37Z0vR%7eRJ?4dk9e-&=FDVnex?P;LcB_53K=lO#pNs9Ku+5l9XM(00uw}7
z^TwQ&dNdh&TmT(EFgx}FKA!{)Pom2&y2|1EsaH>awF47jcwKO5k1lRy%rnCWcr^fQ
z-zM9R$C98a9N&$)SRfzh1_3@d7xr<Yu+M@~Fc&7tIcr|tw-4++`-}A=xU3$NG1^~-
zItZj(zBqD<)FZk{^!!|jbB_;it9s`WK6O<`3$;RWOzs9Cg)n}M|IX=FV)Qvd?Ca_4
zbmtR6W_4D5<MoHE;Yx))GEV*Er<aWAs};RW>kQsa7>dv`>&N$KWJE!p;yX3oQ+U6|
zlccZuk`W16qes$lcgE!hUODRT)#`Lm-JLlS`U2O1VY5><B0X%(#~@K2#j`;`G;?}~
zYU9J&hsovKZY106WDkV1zhc^#ro`4}oStNQAvHnc$2qWw;g;!GUIuKVOB=AhB@Lk2
zjS1$l1=YQfh3i|%LfSn6=gzD0bhB-rP$dzwhz&Zh6*-jx4+FSZms8NhO%h2jTgmsh
zG&iKW`Iy2^uhuD`Mu%jPY0)j&wbhGb6RnMajb48aa6*STNvUq`c2OJSUC2F+NylrQ
z+c0msDPS8?#7NYQ<S2zshbbY5A*~2Mh*aG^vXn;jndv+94kfb!wHq9Ow6+MHfQJyC
z%y<cfU>AyVwch3O;*QKUM35<QI>eJ6nk6&J+-?D2!DemMb`ZTqt}D?K8j6PWDYpCx
z6qb1D<OMWZ?m1NMt!*M#1_FbU-8Vh@tlsOS=G(dJkPv8p9cRt}1LnYcPKs;?t$09>
zy-G1)E&ICa%h!Rj`hZ37C0NfB+RGUO`DiB$@&X#z+u5S2uJzd1r-9r7iK5q|qrnL6
zO_3NvGwKMLxmp$t*|7EMJ9um;#RHm?y3U?vMWg-=r>fg1lO$Kwu!(Dg>B=M;FW>;6
zqag4A<dAmBpE7e&3#D&TDzFgyB5&gPy34mSxLOl``^3}$NP@4rs>0X<7aZT}_>eb9
zgi6~<-_qPWTE<z&-aZrPy<z08EdI6QOKSY}3NqEFD_GYMZ}?h+OLzcPfi+x4bxfl~
z6!agVx!19Oikhaj9bQo3)bcEpv#hKO#HWhuu|Ol;Aa$dQP1dd+geY7X^28xiT7^q8
zp@tDbM%b&+<8t`q-8)8F*A&3?#k<0d2u+dxRXp0(FD4*=l(d*Pj#*}KQwI9{>v?S>
z&{2EaOpD-zHg++^%bG+&*qdfLUHBl=l-$5&kLT<Xt42i0W2tDO2mg|6)a)9}xuQJM
zws-QSpu63Lm-fO(Q>x*vb+aAvRGMZX2CQm<jg2Pej@G`U+4E{;cJidd7K~FL(-1Ne
zR%vIb^H7=YFqhsQgyj?y_VRwZv>eTDE3c*V+_9P6$Hri%!`D<>pTWXQ_s&W~wQPWL
zkQW$x^uxB91LcUxzI#dN<$|xh#<1cC-un3dJsk3G|0I`kD<j$~FnZ<1mQND|bV#GF
z99d&+?*u8jU`3ZCgw{l<2~@6nkJr8gOY)6a*>LR8mo9tMHeg!F;)!tuF5xgfqBYrm
zB6|c-zij5cbvW#`vf+ZKeARFU#1Sl<($R|;9*TK*cg|D+0toX7kR*itGDv4It*%oV
z$-|rB4A4)dVpu!}JvB=A-7Q4~es|=%uN)CT^<9#Fz}Rif)YjbTdXJK(DU%DT{kaHZ
z+D~3B>!>VQsAO>|z}Ho@F+h$bASM0=zZQj$oyG07h-nJKbnlZ8q-oy|b8adoH>N!W
zT|lX#Si>R>1T0&n<5t)sX=)8(mRH&mg1|GGj+LAh>TaBHthK|@;o*qC`AJW03A}yG
z&l7slyZdPoz1|kelU8;$95qfb)M?)=>QsFkU`%}+RDw*Cw*iJ%gZ-&pONwDzyAIaf
z)$6WxKh^61zH2ct>=(+D^$G{Cy_udaSl}Au9pPm0B6T?=wWe==;CU!5W++}r(xV-^
zIPUsfUQd{fC>Zl^muN{4v6a4?Kk3$SWQmH#L>yj}Lc?@v*dgANJb%fAxZ4%9#ABPm
zoBsMDa|}~=nc0xkRbD2(%71sb!(nX@rq5kPUQ$R<i;xEMEA6aHSf7<mSrVTZYf~($
z;P!_-DkoKoCu{x!Xv!0Z)Ege-ix_Tj9KE`qs#|2Ye68;g3@T(qu@4HU)moj=Alz%$
zv8evgm>1wtAoB&X4jBKA{POLyqGXTP=#6p36{ifasz}dFUdEz4c*CGeVE`iOjbV67
zXo4rpv|XhbV_B{dzXV{AC!|rzY{yg{JPIQz@zkUOf^l-PQ|FLu>sqKsWu2)y!wQIk
zfu&JdU2>KcLGu1Ygst*FS|E?CM_%oX@B=Hae!a6~{Ewn(Wx><3gs?^TCDS?|QMmBE
zj_^)ekPS~=W%u6Ya9`C@=ORBjs>K9@aXaXDokIZlkZA`1zBHg>nfRL@k|;Npf{RER
zocaeLP5ck)A>gL8b`XI}2<^Czz4gg{mftcFNcT51)Q%DvZmv@PX%wTh+mpqu<{*z|
zWm5dP?DbpzerI7`5p1@7sH<<PiFI1nRXw&#nh=%!$JNF8kL%)*TQ{ecT24Z_joy<T
zB(PM6V=_Y7;fK%5pr|}ldODM~l;G@B>T1549Mr7<tU-w?8s^RjS)iyJ`=8YAiL;$c
zh&ms^PzA2`*eZ{3iBm?t$USBFHEw0@)yKFGy!VjO6|Q8dIM{c5c545rPkz6K4}SU5
zE4aeV$0>umj*1Cz!7<JS+Gc;9sCz=!A5^_LR~A_4#d&r<{v~TUeptcTXH-iTR~PmQ
z!ZN-i_(InI!$#Wr3AIhynNOEz<ofBJtz`cY$A?%WmG4O`DP6Qzk6&wklFl(|gAiZL
z8oHc$9Z5sP1K-6{SEFgQEJ|)!l|OPxRf2F6-1ZU+keEzNHQf88I{ys<1pNWMckd!W
z1o~O^QbN=Xq=g)&E_Epd124cW3`T<5@YGDaB_8Glyx@<q%~ZI+rpfMkN7VJkOq(Rc
z8gW?p{XgckWZd}!yh#uHI=Y<6F@T%G<uK-35R8cac$@(_0LK5LBHtpg*$^#mZ*py6
zY-xIBWG!uPWMynFbY*jNE_8DMss6zEiBC*;QOOTT#QNXPLw?N7lgbcT+Pxb4ywL@C
zoYh+WZ`(E+{=I(%;r)^Tv7OI#&9K7-Y3~}eU5CcI!&U?aEipDP5~+#QGOx)0zLy`8
zNQ#o}tj%^sfmjknz9gULc|Rzc7rd0{6C%GAB#{S55+Tt8x-EH*MvID_s~e+lpFN|t
z<uim970uG`d70yk{!Y>vP40+%OWEB4JY>QBi%PC|N#*)FS&<yan!I8%{`@Uj;$&?a
zT~~RI%e8twySjYyYBs<4arXNChpX97^M75vdi(PF;8|_=WHJ?HGEF#>CC|o1h8dZX
z-y~szaweuy_b8^VA>*8<B%4T~rV8)DA|xfjlDwmgLYr{5=sUExkG}f{ShJ^=1R<f#
z{|_nE5a;OVK;ONiEImgfGvLVFqw3CVe0X^H;)T7HV8$6uaCVMNZwSGXWCR+vBO|XD
z7*S$b324F#!kW7hFX7(DoBFyW8J23+D_V%QdxTN~uchKWb6dmaW<0s`dU$BMra6EC
z=YBtCoze>lmK+}*e?2}t86Ta@j=niRJcR!fnCH)<w*RU~`<kD1n%kl6pQ7Zy5{6kq
z+VKHeOUhh(?2^MYaOR9F)<TjT9;|S37Y=|>2JrP}jceTcYj%sPOn#^`;@$?+ct#Uw
zIw}dEEg{ap2;Ec0NC_|awzY#J_vbAoS*k`*tNajKiHCiJ1=1)5v?_w`jT$Hmgpuxl
z%vrX!m;n>y%G_=zR?kL^4h)#}j12f&W&qNM_-N5@hH=rWuCE%TpB}dWwZMKuNa0#~
z&&xaH@7jW=YfS+_an2>tyM&hnt%;m$;K5F?+zFIX;&f@l@AanpcoV!T6@2}>mb0UT
zmt@p*0C4{wXtG{J^?U9wj(z++&Q*V}p+9s{6eABO01srPeQ!v0Cj~AAahmM!Pb7c!
zONBG{=C`rlCM_)|hK=pJpIi}i&F`}DVRP@AqiyFOZ#KWufPLanH?*&Zyo0puGq+Ll
ziQS)YFdE%X7THBLgx<mk!@=7UT#n6p*CeM*a<n91G))|_JTT&RfG|s2_CE#bPdcQ(
z(oqBqpdGcDMM(D#hU<nZirs6`m<_J%R}!H<WpkMDvLr%mp#Vp_D8SLM0yO%zg%o7|
zd>b(c?qeb7k`eU;b|4}DjEaR=vjjG=ez_S;#W^Lz*>z2^p!fQ@-Y0lAKRQ0?JbXjc
zPQ1Rjd^0{hebIURW0@)LN(rIBbZQ2e;G&o+OH&29DHWn3)7~C_aKz2LKevRLAN4i1
zQfHtjP#qcR@CIEf?F?U>5uCe2NVs<T?<%anRGTH%1P+%FXu^;!6X3;Lni1Wx6`rP3
z<>y2JGUFQ7+;psK?z!W?REygpCB+5I^c|7#OJX-BQPeO)z%NBPCnPCKYD1gjczp4<
z@*DMLhOWcgEVT{Jf}Xp;-omwfRzG28v%yge_%+>Yy^})|>t7Ct`?(feYfIajB`;|S
zw&*Nnw4iBy<%AaC4p`mflY^RmQ11Zit$^Lcy(aK;&7d*e0<gpt3zYrQTBR34VtAue
zit9x5Zs_0O)T)IS`nTrB70&!)TML`FHocZ8nHw-8P{E+jZr=B0ROZGHZ*);XG~r84
zdK0@Kxxx~*7%~QH49cxFh*wh3l(adt$)I9cjp_?Ro8J0GoyymgT0+)TE$oyG67^g)
zUgj^pdG0+jK2xD;Y+$8-CK>%IZ0WmCGs-04`84vf0jHR@eZ)Z7Nq<42xU&~}`y;(O
zO)Ln98rki;Y3%5zgsTyX=B=kn5?(RmYANgm&P-Wiz~8l&_#U?xju~E%OvgsHz@x$=
z9VRuH&cQe#IopbE5of3n6uN~*q0L5~hv?{mlhJ2oUc;Jg)cLPk^-zduj0m+150fC&
z<Xs8Sr^~Ju#%Zt>5w@a&Bab(KF*+R)RSGGP@~3`kC~WQLegz|di791EWS|!)?Ng+M
zr=7I$hf1svB(MLb@^!U9_*N;rF<EDEF!e{5dyaQW_Ku&j+++2iKXda0Bgotg^_;cz
zQ@0ocBaI*9iJEQ(lZ7WP3w=DiQT@NeGFiP}s3>dLnMc$&uH$yLPn|=AwI+w;QbAo9
zz^Ov8AdrOto=r`~^8S8BSX~Kj>O&&reD)+|ptBC&-zu}Rb<J9c$fRSFo?6-^{BA{_
zlU;a!@~3&<SKEm)|4-L!oHdP=Y`RZ(tk|6W4JjUG$mWd+*KEHu5drwMy`jw6S(y!q
zvnLG?`;m+#0rN_gnz*?~d%9w>5Qv+8sUV00jITBO>Hxv_w08DAC!68SN18|0wvj5E
z*1ru`>Z`htSYP`Y>PVrn{@tLx=~W|r6q$EPR42kEtU-H<GA$BK(4n)ol!J(<;&hT#
zkfzy_9LU&o9Vxa7^~vh+N${SpH*QwiQJ}A#xUEx)R^pQb_*G2Qv95V79(D`~(CKc+
zpQl|3+ToD4SBUz{%>8n-S&-^PejolQbk0^Kzuz;+*@TOl5+WEypHH+(H&R`Dz)Ly2
zqp);~7bUO_HmXSkV9SJYfOag4bsft;NmTp1<K-HJ>C;#2nS|7t=c8lVvt4}K*%$L|
z!TrzY-JW-z`9}ci5Be{xDhKXfOT2)r<|^&H)Rg~q#jELcYp1qzVb(GHOVnitilNTP
zJC-f`iiQ4~nSTRi!dOi&^b~b)3Nzzn>idU+Qzj8yW0b2PUa7Hdu2y;zg9pFX+4J@~
z;$HfXHtHptOeSsXdg`$cQi7%qoE)j{e6-Sc*fETyJ{VeW7Asb?U%EJbY$}LuV~1BD
z?Uv_tgDCX1dHVyviuo94@2yh_F_u?Cd74{N5?K2_RCRnz4cRu1GpU&cYujPP?ilFf
zc2$%AD|CJifCQC`4nS;feY_b3JzruCe2cZ=YphtZZ3HG>0I132pSyS$@lUp#M!P||
z^M#h`+FEUm?7*7=eyETN-*I4Tzz7v-uoP#U5oefEnQp%kQ%58<<nOJAHNmiUD?qbY
z$Q}i3@aboO*`ECy*t^~K4ZzjefMBbFKsfqApCEExF}DCYu&-|J8=YV8>>fQg`zJQ9
za8?6z3XlIIinz!yK*LLrU{Hk;Rcg`-q0r~RxhstwjoU0Njig|K84f}ry)ueKQGP|J
x)tGMxv`~%#Qui^*3jnx~rDD3B{~wTsJE0wr1po3Pl*l_+jUqm>pHLC<h_2t@&cpx!

literal 0
HcmV?d00001


From 4400bb9be7eda553f502ed2e6e1da2868fe66469 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:08:16 +0000
Subject: [PATCH 063/134] HACK-464: checkpoint merge prep

---
 docs/architecture.md           |   5 +-
 docs/gateway-api.md            |  18 ++
 src/commands/projects.ts       | 252 +++++++++++++++++++---
 src/daemon/client.ts           | 114 ++++++----
 src/daemon/runtime-cache.ts    | 371 +++++++++++++++++++++++++++++----
 src/daemon/runtime-health.ts   |  66 ++++++
 src/daemon/server.ts           |  24 +++
 tests/daemon-client.test.ts    |  78 +++++++
 tests/projects-command.test.ts |  60 ++++++
 tests/runtime-cache.test.ts    | 141 ++++++++++++-
 10 files changed, 1026 insertions(+), 103 deletions(-)
 create mode 100644 tests/daemon-client.test.ts
 create mode 100644 tests/projects-command.test.ts

diff --git a/docs/architecture.md b/docs/architecture.md
index 765336650..f016f2aa6 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -177,8 +177,11 @@ If the daemon is not running (or version-mismatched), the CLI falls back to dire
 Runtime health:
 - The daemon treats the container runtime as ephemeral; it fingerprints the engine (socket + engine id)
   and detects resets.
+- On reset detection, hackd performs one bounded cache refresh to stabilize its view before asking the
+  user to repair anything manually.
 - When the runtime is unavailable, cached state is retained but marked stale; API responses include
-  `runtime_*` metadata and project `status` becomes `unknown`.
+  `runtime_*` metadata, including what changed, what hackd repaired, and the next step when manual
+  recovery is still required. Project `status` becomes `unknown`.
 
 Why optional:
 - The CLI must keep working with zero background processes.
diff --git a/docs/gateway-api.md b/docs/gateway-api.md
index bbe4cd563..e8a305831 100644
--- a/docs/gateway-api.md
+++ b/docs/gateway-api.md
@@ -325,6 +325,12 @@ Response:
 | `runtime_last_ok_at` | string or null | Last successful runtime check |
 | `runtime_reset_at` | string or null | Last detected runtime reset |
 | `runtime_reset_count` | number | Runtime reset counter |
+| `runtime_reset_summary` | string or null | Summary of what changed during the most recent reset |
+| `runtime_reset_changes` | string[] | Machine-readable reset drift fields |
+| `runtime_last_repair_at` | string or null | Last bounded auto-repair attempt timestamp |
+| `runtime_repair_action` | string or null | Last auto-repair action hackd attempted |
+| `runtime_repair_outcome` | string or null | `stabilized` or `manual_action_required` |
+| `runtime_next_step` | string or null | Guided next step when auto-repair cannot finish safely |
 
 ### GET /v1/projects
 
@@ -358,6 +364,12 @@ Response:
 | `runtime_last_ok_at` | string or null | Last successful runtime check |
 | `runtime_reset_at` | string or null | Last detected runtime reset |
 | `runtime_reset_count` | number | Runtime reset counter |
+| `runtime_reset_summary` | string or null | Summary of what changed during the most recent reset |
+| `runtime_reset_changes` | string[] | Machine-readable reset drift fields |
+| `runtime_last_repair_at` | string or null | Last bounded auto-repair attempt timestamp |
+| `runtime_repair_action` | string or null | Last auto-repair action hackd attempted |
+| `runtime_repair_outcome` | string or null | `stabilized` or `manual_action_required` |
+| `runtime_next_step` | string or null | Guided next step when auto-repair cannot finish safely |
 | `projects` | ProjectView[] | Gateway-enabled projects only |
 
 ### GET /v1/ps
@@ -385,6 +397,12 @@ Response:
 | `runtime_last_ok_at` | string or null | Last successful runtime check |
 | `runtime_reset_at` | string or null | Last detected runtime reset |
 | `runtime_reset_count` | number | Runtime reset counter |
+| `runtime_reset_summary` | string or null | Summary of what changed during the most recent reset |
+| `runtime_reset_changes` | string[] | Machine-readable reset drift fields |
+| `runtime_last_repair_at` | string or null | Last bounded auto-repair attempt timestamp |
+| `runtime_repair_action` | string or null | Last auto-repair action hackd attempted |
+| `runtime_repair_outcome` | string or null | `stabilized` or `manual_action_required` |
+| `runtime_next_step` | string or null | Guided next step when auto-repair cannot finish safely |
 | `items` | PsItem[] | `docker compose ps` style rows |
 
 ### POST /control-plane/projects/:projectId/jobs
diff --git a/src/commands/projects.ts b/src/commands/projects.ts
index e48d0bcd1..231a6311c 100644
--- a/src/commands/projects.ts
+++ b/src/commands/projects.ts
@@ -253,6 +253,10 @@ async function runProjects(opts: {
   readonly meta: boolean;
   readonly json: boolean;
 }): Promise<number> {
+  const daemonRuntimeMeta = opts.json
+    ? null
+    : await readDaemonRuntimeRecoveryMeta();
+
   if (opts.json) {
     const daemon = await requestDaemonJson({
       path: "/v1/projects",
@@ -289,35 +293,22 @@ async function runProjects(opts: {
     ? await buildMetaByProjectName({ views })
     : new Map<string, ProjectMeta>();
   if (opts.json) {
-    const runtimeMeta = formatRuntimeMeta({ runtime });
-    const payload = {
-      generated_at: new Date().toISOString(),
+    outputProjectsJson({
       filter: opts.filter,
-      include_global: opts.includeGlobal,
-      include_unregistered: opts.includeUnregistered,
-      include_meta: opts.meta,
-      runtime_ok: runtimeMeta.ok,
-      runtime_error: runtimeMeta.error,
-      runtime_checked_at: runtimeMeta.checkedAt,
-      runtime_last_ok_at: runtimeMeta.lastOkAt,
-      runtime_reset_at: runtimeMeta.lastResetAt,
-      runtime_reset_count: runtimeMeta.resetCount,
-      projects: views.map((view) => ({
-        ...serializeProjectView(view),
-        ...(opts.meta ? { meta: metaByName.get(view.name) ?? null } : {}),
-      })),
-    };
-    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+      includeGlobal: opts.includeGlobal,
+      includeUnregistered: opts.includeUnregistered,
+      includeMeta: opts.meta,
+      runtime,
+      views,
+      metaByName,
+    });
     return 0;
   }
 
-  if (!runtime.ok) {
-    await display.panel({
-      title: "Runtime unavailable",
-      tone: "warn",
-      lines: [runtime.error ?? "Docker runtime is not responding."],
-    });
-  }
+  await renderRuntimeNotices({
+    runtime,
+    daemonRuntimeMeta,
+  });
 
   if (views.length === 0) {
     await display.panel({
@@ -368,6 +359,80 @@ async function runProjects(opts: {
   return 0;
 }
 
+type RuntimeRecoveryMeta = {
+  readonly resetCount: number;
+  readonly lastResetSummary: string | null;
+  readonly lastRepairAction: string | null;
+  readonly lastRepairOutcome: "stabilized" | "manual_action_required" | null;
+  readonly nextStep: string | null;
+};
+
+type RuntimeRecoveryNotice = {
+  readonly title: string;
+  readonly tone: "info" | "warn";
+  readonly lines: readonly string[];
+};
+
+function outputProjectsJson(opts: {
+  readonly filter: string | null;
+  readonly includeGlobal: boolean;
+  readonly includeUnregistered: boolean;
+  readonly includeMeta: boolean;
+  readonly runtime: Awaited<ReturnType<typeof readRuntimeProjects>>;
+  readonly views: readonly ProjectView[];
+  readonly metaByName: ReadonlyMap<string, ProjectMeta>;
+}): void {
+  const runtimeMeta = formatRuntimeMeta({ runtime: opts.runtime });
+  const payload = {
+    generated_at: new Date().toISOString(),
+    filter: opts.filter,
+    include_global: opts.includeGlobal,
+    include_unregistered: opts.includeUnregistered,
+    include_meta: opts.includeMeta,
+    runtime_ok: runtimeMeta.ok,
+    runtime_error: runtimeMeta.error,
+    runtime_checked_at: runtimeMeta.checkedAt,
+    runtime_last_ok_at: runtimeMeta.lastOkAt,
+    runtime_reset_at: runtimeMeta.lastResetAt,
+    runtime_reset_count: runtimeMeta.resetCount,
+    runtime_reset_summary: runtimeMeta.lastResetSummary,
+    runtime_reset_changes: runtimeMeta.lastResetChanges,
+    runtime_last_repair_at: runtimeMeta.lastRepairAt,
+    runtime_repair_action: runtimeMeta.lastRepairAction,
+    runtime_repair_outcome: runtimeMeta.lastRepairOutcome,
+    runtime_next_step: runtimeMeta.nextStep,
+    projects: opts.views.map((view) => ({
+      ...serializeProjectView(view),
+      ...(opts.includeMeta
+        ? { meta: opts.metaByName.get(view.name) ?? null }
+        : {}),
+    })),
+  };
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+async function renderRuntimeNotices(opts: {
+  readonly runtime: Awaited<ReturnType<typeof readRuntimeProjects>>;
+  readonly daemonRuntimeMeta: RuntimeRecoveryMeta | null;
+}): Promise<void> {
+  if (!opts.runtime.ok) {
+    await display.panel({
+      title: "Runtime unavailable",
+      tone: "warn",
+      lines: [opts.runtime.error ?? "Docker runtime is not responding."],
+    });
+  }
+
+  const runtimeRecoveryNotice = buildRuntimeRecoveryNotice({
+    runtimeMeta: opts.daemonRuntimeMeta,
+  });
+  if (!runtimeRecoveryNotice) {
+    return;
+  }
+
+  await display.panel(runtimeRecoveryNotice);
+}
+
 async function renderProjectDetails(opts: {
   readonly project: ProjectView;
   readonly caddyIp: string | null;
@@ -746,6 +811,97 @@ function summarizeServiceState(opts: {
   return "mixed";
 }
 
+async function readDaemonRuntimeRecoveryMeta(): Promise<RuntimeRecoveryMeta | null> {
+  const metrics = await requestDaemonJson({
+    path: "/v1/metrics",
+    autoStart: false,
+  });
+  if (!(metrics?.ok && metrics.json)) {
+    return null;
+  }
+  return parseDaemonRuntimeRecoveryMeta({ json: metrics.json });
+}
+
+function parseDaemonRuntimeRecoveryMeta(opts: {
+  readonly json: Record<string, unknown>;
+}): RuntimeRecoveryMeta | null {
+  const resetCount = readNumberField({
+    json: opts.json,
+    key: "runtime_reset_count",
+  });
+  const lastResetSummary = readStringField({
+    json: opts.json,
+    key: "runtime_reset_summary",
+  });
+  const lastRepairAction = readStringField({
+    json: opts.json,
+    key: "runtime_repair_action",
+  });
+  const lastRepairOutcome = readRepairOutcomeField({
+    json: opts.json,
+    key: "runtime_repair_outcome",
+  });
+  const nextStep = readStringField({
+    json: opts.json,
+    key: "runtime_next_step",
+  });
+
+  if (
+    resetCount === 0 &&
+    lastResetSummary === null &&
+    lastRepairAction === null &&
+    lastRepairOutcome === null &&
+    nextStep === null
+  ) {
+    return null;
+  }
+
+  return {
+    resetCount,
+    lastResetSummary,
+    lastRepairAction,
+    lastRepairOutcome,
+    nextStep,
+  };
+}
+
+function buildRuntimeRecoveryNotice(opts: {
+  readonly runtimeMeta: RuntimeRecoveryMeta | null;
+}): RuntimeRecoveryNotice | null {
+  if (!opts.runtimeMeta) {
+    return null;
+  }
+
+  const lines: string[] = [];
+  if (opts.runtimeMeta.lastResetSummary) {
+    const count =
+      opts.runtimeMeta.resetCount > 0
+        ? `#${opts.runtimeMeta.resetCount}`
+        : "detected";
+    lines.push(`Detected reset ${count}: ${opts.runtimeMeta.lastResetSummary}`);
+  }
+  if (opts.runtimeMeta.lastRepairAction && opts.runtimeMeta.lastRepairOutcome) {
+    lines.push(
+      `hackd repair: ${opts.runtimeMeta.lastRepairAction} -> ${opts.runtimeMeta.lastRepairOutcome}`
+    );
+  }
+  if (opts.runtimeMeta.nextStep) {
+    lines.push(`Next step: ${opts.runtimeMeta.nextStep}`);
+  }
+  if (lines.length === 0) {
+    return null;
+  }
+
+  return {
+    title: "Runtime reset detected",
+    tone:
+      opts.runtimeMeta.lastRepairOutcome === "manual_action_required"
+        ? "warn"
+        : "info",
+    lines,
+  };
+}
+
 function formatRuntimeMeta(opts: {
   readonly runtime: Awaited<ReturnType<typeof readRuntimeProjects>>;
 }): {
@@ -755,6 +911,12 @@ function formatRuntimeMeta(opts: {
   readonly lastOkAt: string | null;
   readonly lastResetAt: string | null;
   readonly resetCount: number;
+  readonly lastResetSummary: string | null;
+  readonly lastResetChanges: readonly string[];
+  readonly lastRepairAt: string | null;
+  readonly lastRepairAction: string | null;
+  readonly lastRepairOutcome: "stabilized" | "manual_action_required" | null;
+  readonly nextStep: string | null;
 } {
   const checkedAt = new Date(opts.runtime.checkedAtMs).toISOString();
   return {
@@ -764,6 +926,12 @@ function formatRuntimeMeta(opts: {
     lastOkAt: opts.runtime.ok ? checkedAt : null,
     lastResetAt: null,
     resetCount: 0,
+    lastResetSummary: null,
+    lastResetChanges: [],
+    lastRepairAt: null,
+    lastRepairAction: null,
+    lastRepairOutcome: null,
+    nextStep: null,
   };
 }
 
@@ -771,6 +939,40 @@ function sanitizeName(value: string): string {
   return value.trim().toLowerCase();
 }
 
+function readNumberField(opts: {
+  readonly json: Record<string, unknown>;
+  readonly key: string;
+}): number {
+  const value = opts.json[opts.key];
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function readStringField(opts: {
+  readonly json: Record<string, unknown>;
+  readonly key: string;
+}): string | null {
+  const value = opts.json[opts.key];
+  if (typeof value !== "string") {
+    return null;
+  }
+  return value.length > 0 ? value : null;
+}
+
+function readRepairOutcomeField(opts: {
+  readonly json: Record<string, unknown>;
+  readonly key: string;
+}): "stabilized" | "manual_action_required" | null {
+  const value = opts.json[opts.key];
+  return value === "stabilized" || value === "manual_action_required"
+    ? value
+    : null;
+}
+
+export const __testOnlyProjectsCommand = {
+  buildRuntimeRecoveryNotice,
+  parseDaemonRuntimeRecoveryMeta,
+};
+
 type MissingRegistryEntry = {
   readonly project: RegisteredProject;
   readonly reason: string;
diff --git a/src/daemon/client.ts b/src/daemon/client.ts
index 8ce231df0..e9b4c1436 100644
--- a/src/daemon/client.ts
+++ b/src/daemon/client.ts
@@ -38,14 +38,16 @@ export async function requestDaemonJson(opts: {
   readonly method?: "GET" | "POST";
   readonly body?: Record<string, unknown>;
   readonly allowIncompatible?: boolean;
+  readonly autoStart?: boolean;
 }): Promise<DaemonJsonResponse | null> {
+  const autoStart = opts.autoStart ?? true;
   const paths = resolveDaemonPaths({});
-  const status = await readDaemonStatus({ paths });
-  if (!status.socketExists) {
-    const started = await ensureDaemonReady({ paths });
-    if (!started) {
-      return null;
-    }
+  const daemonReady = await ensureDaemonSocketReady({
+    paths,
+    autoStart,
+  });
+  if (!daemonReady) {
+    return null;
   }
 
   if (!opts.allowIncompatible) {
@@ -66,36 +68,16 @@ export async function requestDaemonJson(opts: {
     body: opts.body,
     timeoutMs: opts.timeoutMs ?? 1000,
   });
-  if (!raw) {
-    const restarted = await ensureDaemonReady({ paths });
-    if (!restarted) {
-      return null;
-    }
-    const retry = await requestDaemonRaw({
-      socketPath: paths.socketPath,
-      method: opts.method ?? "GET",
-      path: opts.path,
-      query: opts.query,
-      body: opts.body,
-      timeoutMs: opts.timeoutMs ?? 1000,
-    });
-    if (!retry) {
-      return null;
-    }
-    const retryJson = safeJsonParse({ text: retry.body });
-    return {
-      ok: retry.statusCode >= 200 && retry.statusCode < 300,
-      status: retry.statusCode,
-      json: retryJson,
-    };
-  }
-
-  const json = safeJsonParse({ text: raw.body });
-  return {
-    ok: raw.statusCode >= 200 && raw.statusCode < 300,
-    status: raw.statusCode,
-    json,
-  };
+  return await resolveDaemonJsonResponse({
+    raw,
+    autoStart,
+    paths,
+    method: opts.method ?? "GET",
+    path: opts.path,
+    query: opts.query,
+    body: opts.body,
+    timeoutMs: opts.timeoutMs ?? 1000,
+  });
 }
 
 /**
@@ -150,6 +132,20 @@ async function ensureDaemonReady(opts: {
   return false;
 }
 
+async function ensureDaemonSocketReady(opts: {
+  readonly paths: ReturnType<typeof resolveDaemonPaths>;
+  readonly autoStart: boolean;
+}): Promise<boolean> {
+  const status = await readDaemonStatus({ paths: opts.paths });
+  if (status.socketExists) {
+    return true;
+  }
+  if (!opts.autoStart) {
+    return false;
+  }
+  return await ensureDaemonReady({ paths: opts.paths });
+}
+
 /**
  * Ensures launchd manages hackd and kicks it when needed.
  */
@@ -276,6 +272,52 @@ async function requestDaemonRaw(opts: {
   }
 }
 
+async function resolveDaemonJsonResponse(opts: {
+  readonly raw: { readonly statusCode: number; readonly body: string } | null;
+  readonly autoStart: boolean;
+  readonly paths: ReturnType<typeof resolveDaemonPaths>;
+  readonly method: "GET" | "POST";
+  readonly path: string;
+  readonly query?: Record<string, string | boolean | null>;
+  readonly body?: Record<string, unknown>;
+  readonly timeoutMs: number;
+}): Promise<DaemonJsonResponse | null> {
+  if (opts.raw) {
+    return buildDaemonJsonResponse({ raw: opts.raw });
+  }
+  if (!opts.autoStart) {
+    return null;
+  }
+
+  const restarted = await ensureDaemonReady({ paths: opts.paths });
+  if (!restarted) {
+    return null;
+  }
+  const retry = await requestDaemonRaw({
+    socketPath: opts.paths.socketPath,
+    method: opts.method,
+    path: opts.path,
+    query: opts.query,
+    body: opts.body,
+    timeoutMs: opts.timeoutMs,
+  });
+  if (!retry) {
+    return null;
+  }
+  return buildDaemonJsonResponse({ raw: retry });
+}
+
+function buildDaemonJsonResponse(opts: {
+  readonly raw: { readonly statusCode: number; readonly body: string };
+}): DaemonJsonResponse {
+  const json = safeJsonParse({ text: opts.raw.body });
+  return {
+    ok: opts.raw.statusCode >= 200 && opts.raw.statusCode < 300,
+    status: opts.raw.statusCode,
+    json,
+  };
+}
+
 function buildQueryString(opts: {
   readonly query: Record<string, string | boolean | null> | undefined;
 }): string {
diff --git a/src/daemon/runtime-cache.ts b/src/daemon/runtime-cache.ts
index acaf6708d..60bb85857 100644
--- a/src/daemon/runtime-cache.ts
+++ b/src/daemon/runtime-cache.ts
@@ -14,6 +14,9 @@ import {
 } from "../lib/runtime-projects.ts";
 import {
   buildRuntimeFingerprint,
+  detectRuntimeDrift,
+  type RuntimeDriftField,
+  type RuntimeIdentity,
   readRuntimeIdentity,
 } from "./runtime-health.ts";
 
@@ -25,6 +28,14 @@ export type RuntimeHealth = {
   readonly lastResetAtMs: number | null;
   readonly resetCount: number;
   readonly fingerprint: string | null;
+  readonly identity: RuntimeIdentity | null;
+  readonly lastResetChanges: readonly RuntimeDriftField[];
+  readonly lastResetSummary: string | null;
+  readonly lastRepairAtMs: number | null;
+  readonly lastRepairAction: string | null;
+  readonly lastRepairOutcome: "stabilized" | "manual_action_required" | null;
+  readonly nextStep: string | null;
+  readonly resetFromNonEmptyRuntime: boolean;
 };
 
 export type RuntimeSnapshot = {
@@ -45,6 +56,15 @@ export type ProjectsPayload = {
   readonly runtime_last_ok_at: string | null;
   readonly runtime_reset_at: string | null;
   readonly runtime_reset_count: number;
+  readonly runtime_reset_summary: string | null;
+  readonly runtime_reset_changes: readonly RuntimeDriftField[];
+  readonly runtime_last_repair_at: string | null;
+  readonly runtime_repair_action: string | null;
+  readonly runtime_repair_outcome:
+    | "stabilized"
+    | "manual_action_required"
+    | null;
+  readonly runtime_next_step: string | null;
   readonly projects: readonly Record<string, unknown>[];
 };
 
@@ -65,6 +85,15 @@ export type PsPayload = {
   readonly runtime_last_ok_at: string | null;
   readonly runtime_reset_at: string | null;
   readonly runtime_reset_count: number;
+  readonly runtime_reset_summary: string | null;
+  readonly runtime_reset_changes: readonly RuntimeDriftField[];
+  readonly runtime_last_repair_at: string | null;
+  readonly runtime_repair_action: string | null;
+  readonly runtime_repair_outcome:
+    | "stabilized"
+    | "manual_action_required"
+    | null;
+  readonly runtime_next_step: string | null;
   readonly items: readonly PsItem[];
 };
 
@@ -104,7 +133,7 @@ export function createRuntimeCache(opts: {
 
   let snapshot: RuntimeSnapshot | null = null;
   let refreshTask: Promise<void> | null = null;
-  let pending = false;
+  let pendingReason: string | null = null;
   let health: RuntimeHealth = {
     ok: false,
     error: "runtime_not_checked",
@@ -113,6 +142,14 @@ export function createRuntimeCache(opts: {
     lastResetAtMs: null,
     resetCount: 0,
     fingerprint: null,
+    identity: null,
+    lastResetChanges: [],
+    lastResetSummary: null,
+    lastRepairAtMs: null,
+    lastRepairAction: null,
+    lastRepairOutcome: null,
+    nextStep: null,
+    resetFromNonEmptyRuntime: false,
   };
 
   const refresh = async ({
@@ -121,52 +158,30 @@ export function createRuntimeCache(opts: {
     readonly reason: string;
   }): Promise<void> => {
     if (refreshTask) {
-      pending = true;
+      queueRefresh({ reason: `pending:${reason}`, priority: "normal" });
       await refreshTask;
       return;
     }
 
     refreshTask = (async () => {
       const checkedAtMs = Date.now();
+      const previousSnapshot = snapshot;
       const runtimeResult = await readRuntimeProjects({ includeGlobal: true });
-      let nextHealth: RuntimeHealth = {
-        ...health,
+      const refreshed = await resolveRefreshResult({
         checkedAtMs,
-      };
-
-      if (runtimeResult.ok) {
-        const identityResult = await readRuntimeIdentity();
-        let fingerprint = health.fingerprint;
-        let resetCount = health.resetCount;
-        let lastResetAtMs = health.lastResetAtMs;
-        if (identityResult.ok) {
-          fingerprint = buildRuntimeFingerprint({
-            identity: identityResult.identity,
-          });
-          if (health.fingerprint && fingerprint !== health.fingerprint) {
-            resetCount += 1;
-            lastResetAtMs = checkedAtMs;
-          }
-        }
-        nextHealth = {
-          ...nextHealth,
-          ok: true,
-          error: null,
-          lastOkAtMs: checkedAtMs,
-          fingerprint,
-          resetCount,
-          lastResetAtMs,
-        };
-      } else {
-        nextHealth = {
-          ...nextHealth,
-          ok: false,
-          error: runtimeResult.error ?? "runtime_unavailable",
-        };
+        currentHealth: health,
+        previousSnapshot,
+        reason,
+        runtimeResult,
+      });
+      health = refreshed.health;
+      if (refreshed.repairReason) {
+        queueRefresh({
+          reason: refreshed.repairReason,
+          priority: "repair",
+        });
       }
 
-      health = nextHealth;
-
       if (runtimeResult.ok) {
         await autoRegisterRuntimeHackProjects({
           runtime: runtimeResult.runtime,
@@ -190,9 +205,10 @@ export function createRuntimeCache(opts: {
     await refreshTask;
     refreshTask = null;
 
-    if (pending) {
-      pending = false;
-      await refresh({ reason: `pending:${reason}` });
+    if (pendingReason) {
+      const queuedReason = pendingReason;
+      pendingReason = null;
+      await refresh({ reason: queuedReason });
     }
   };
 
@@ -263,6 +279,12 @@ export function createRuntimeCache(opts: {
       runtime_last_ok_at: runtimeMeta.lastOkAt,
       runtime_reset_at: runtimeMeta.lastResetAt,
       runtime_reset_count: runtimeMeta.resetCount,
+      runtime_reset_summary: runtimeMeta.lastResetSummary,
+      runtime_reset_changes: runtimeMeta.lastResetChanges,
+      runtime_last_repair_at: runtimeMeta.lastRepairAt,
+      runtime_repair_action: runtimeMeta.lastRepairAction,
+      runtime_repair_outcome: runtimeMeta.lastRepairOutcome,
+      runtime_next_step: runtimeMeta.nextStep,
       projects: views.map((view, i) => ({
         ...deps.serializeProjectView(view),
         ...(includeMeta ? { meta: metas[i] ?? null } : {}),
@@ -296,10 +318,27 @@ export function createRuntimeCache(opts: {
       runtime_last_ok_at: runtimeMeta.lastOkAt,
       runtime_reset_at: runtimeMeta.lastResetAt,
       runtime_reset_count: runtimeMeta.resetCount,
+      runtime_reset_summary: runtimeMeta.lastResetSummary,
+      runtime_reset_changes: runtimeMeta.lastResetChanges,
+      runtime_last_repair_at: runtimeMeta.lastRepairAt,
+      runtime_repair_action: runtimeMeta.lastRepairAction,
+      runtime_repair_outcome: runtimeMeta.lastRepairOutcome,
+      runtime_next_step: runtimeMeta.nextStep,
       items,
     };
   };
 
+  function queueRefresh(opts: {
+    readonly reason: string;
+    readonly priority: "normal" | "repair";
+  }): void {
+    if (opts.priority === "repair") {
+      pendingReason = opts.reason;
+      return;
+    }
+    pendingReason ??= opts.reason;
+  }
+
   return {
     refresh,
     getProjectsPayload,
@@ -308,6 +347,207 @@ export function createRuntimeCache(opts: {
   };
 }
 
+async function resolveRefreshResult(opts: {
+  readonly checkedAtMs: number;
+  readonly currentHealth: RuntimeHealth;
+  readonly previousSnapshot: RuntimeSnapshot | null;
+  readonly reason: string;
+  readonly runtimeResult: Awaited<ReturnType<typeof readRuntimeProjects>>;
+}): Promise<{
+  readonly health: RuntimeHealth;
+  readonly repairReason: string | null;
+}> {
+  if (opts.runtimeResult.ok) {
+    return await resolveHealthyRefreshResult(opts);
+  }
+  return {
+    health: resolveUnavailableRefreshHealth({
+      checkedAtMs: opts.checkedAtMs,
+      currentHealth: opts.currentHealth,
+      reason: opts.reason,
+      runtimeError: opts.runtimeResult.error ?? "runtime_unavailable",
+    }),
+    repairReason: null,
+  };
+}
+
+async function resolveHealthyRefreshResult(opts: {
+  readonly checkedAtMs: number;
+  readonly currentHealth: RuntimeHealth;
+  readonly previousSnapshot: RuntimeSnapshot | null;
+  readonly reason: string;
+  readonly runtimeResult: Extract<
+    Awaited<ReturnType<typeof readRuntimeProjects>>,
+    { readonly ok: true }
+  >;
+}): Promise<{
+  readonly health: RuntimeHealth;
+  readonly repairReason: string | null;
+}> {
+  const identityResult = await readRuntimeIdentity();
+  const nextHealth = {
+    ...opts.currentHealth,
+    ok: true,
+    error: null,
+    checkedAtMs: opts.checkedAtMs,
+    lastOkAtMs: opts.checkedAtMs,
+  } satisfies RuntimeHealth;
+  if (!identityResult.ok) {
+    return {
+      health: nextHealth,
+      repairReason: null,
+    };
+  }
+
+  const identity = identityResult.identity;
+  const fingerprint = buildRuntimeFingerprint({ identity });
+  const drift = detectRuntimeDrift({
+    previous: opts.currentHealth.identity,
+    current: identity,
+  });
+  const resetDetected =
+    opts.currentHealth.fingerprint !== null &&
+    fingerprint !== opts.currentHealth.fingerprint;
+  if (resetDetected) {
+    return resolveResetRefreshHealth({
+      ...opts,
+      drift,
+      fingerprint,
+      identity,
+    });
+  }
+  if (isAutoRepairReason({ reason: opts.reason })) {
+    return {
+      health: resolveStableAutoRepairHealth({
+        ...opts,
+        fingerprint,
+        identity,
+      }),
+      repairReason: null,
+    };
+  }
+  return {
+    health: {
+      ...nextHealth,
+      fingerprint,
+      identity,
+    },
+    repairReason: null,
+  };
+}
+
+function resolveResetRefreshHealth(opts: {
+  readonly checkedAtMs: number;
+  readonly currentHealth: RuntimeHealth;
+  readonly previousSnapshot: RuntimeSnapshot | null;
+  readonly reason: string;
+  readonly runtimeResult: Extract<
+    Awaited<ReturnType<typeof readRuntimeProjects>>,
+    { readonly ok: true }
+  >;
+  readonly drift: ReturnType<typeof detectRuntimeDrift>;
+  readonly fingerprint: string;
+  readonly identity: RuntimeIdentity;
+}): {
+  readonly health: RuntimeHealth;
+  readonly repairReason: string | null;
+} {
+  const resetFromNonEmptyRuntime =
+    countRuntimeContainers({
+      runtime: opts.previousSnapshot?.runtime ?? [],
+    }) > 0;
+  const health = {
+    ...opts.currentHealth,
+    ok: true,
+    error: null,
+    checkedAtMs: opts.checkedAtMs,
+    lastOkAtMs: opts.checkedAtMs,
+    fingerprint: opts.fingerprint,
+    identity: opts.identity,
+    resetCount: opts.currentHealth.resetCount + 1,
+    lastResetAtMs: opts.checkedAtMs,
+    lastResetChanges: opts.drift.changed,
+    lastResetSummary: opts.drift.summary,
+    lastRepairAtMs: opts.checkedAtMs,
+    lastRepairAction: "refresh_runtime_snapshot",
+    lastRepairOutcome: isAutoRepairReason({ reason: opts.reason })
+      ? "manual_action_required"
+      : null,
+    nextStep: isAutoRepairReason({ reason: opts.reason })
+      ? describeRepairGuidance({
+          hadRuntimeBeforeReset: resetFromNonEmptyRuntime,
+          runtime: opts.runtimeResult.runtime,
+          reason: "still_resetting",
+        })
+      : null,
+    resetFromNonEmptyRuntime,
+  } satisfies RuntimeHealth;
+  return {
+    health,
+    repairReason: isAutoRepairReason({ reason: opts.reason })
+      ? null
+      : `auto-repair:${opts.reason}`,
+  };
+}
+
+function resolveStableAutoRepairHealth(opts: {
+  readonly checkedAtMs: number;
+  readonly currentHealth: RuntimeHealth;
+  readonly runtimeResult: Extract<
+    Awaited<ReturnType<typeof readRuntimeProjects>>,
+    { readonly ok: true }
+  >;
+  readonly fingerprint: string;
+  readonly identity: RuntimeIdentity;
+}): RuntimeHealth {
+  const nextStep = describeRepairGuidance({
+    hadRuntimeBeforeReset: opts.currentHealth.resetFromNonEmptyRuntime,
+    runtime: opts.runtimeResult.runtime,
+    reason: "post_reset",
+  });
+  return {
+    ...opts.currentHealth,
+    ok: true,
+    error: null,
+    checkedAtMs: opts.checkedAtMs,
+    lastOkAtMs: opts.checkedAtMs,
+    fingerprint: opts.fingerprint,
+    identity: opts.identity,
+    lastRepairAtMs: opts.checkedAtMs,
+    lastRepairAction: "refresh_runtime_snapshot",
+    lastRepairOutcome: nextStep ? "manual_action_required" : "stabilized",
+    nextStep,
+  };
+}
+
+function resolveUnavailableRefreshHealth(opts: {
+  readonly checkedAtMs: number;
+  readonly currentHealth: RuntimeHealth;
+  readonly reason: string;
+  readonly runtimeError: string;
+}): RuntimeHealth {
+  const nextHealth = {
+    ...opts.currentHealth,
+    ok: false,
+    error: opts.runtimeError,
+    checkedAtMs: opts.checkedAtMs,
+  } satisfies RuntimeHealth;
+  if (!isAutoRepairReason({ reason: opts.reason })) {
+    return nextHealth;
+  }
+  return {
+    ...nextHealth,
+    lastRepairAtMs: opts.checkedAtMs,
+    lastRepairAction: "refresh_runtime_snapshot",
+    lastRepairOutcome: "manual_action_required",
+    nextStep: describeRepairGuidance({
+      hadRuntimeBeforeReset: opts.currentHealth.resetFromNonEmptyRuntime,
+      runtime: [],
+      reason: "runtime_unavailable",
+    }),
+  };
+}
+
 function buildPsItems(opts: { readonly runtime: RuntimeProject }): PsItem[] {
   const out: PsItem[] = [];
   for (const service of opts.runtime.services.values()) {
@@ -374,10 +614,17 @@ function serializeRuntimeHealth(opts: { readonly health: RuntimeHealth }): {
   readonly lastOkAt: string | null;
   readonly lastResetAt: string | null;
   readonly resetCount: number;
+  readonly lastResetSummary: string | null;
+  readonly lastResetChanges: readonly RuntimeDriftField[];
+  readonly lastRepairAt: string | null;
+  readonly lastRepairAction: string | null;
+  readonly lastRepairOutcome: "stabilized" | "manual_action_required" | null;
+  readonly nextStep: string | null;
 } {
   const checkedAt = toIso({ ms: opts.health.checkedAtMs });
   const lastOkAt = toIso({ ms: opts.health.lastOkAtMs });
   const lastResetAt = toIso({ ms: opts.health.lastResetAtMs });
+  const lastRepairAt = toIso({ ms: opts.health.lastRepairAtMs });
   return {
     ok: opts.health.ok,
     error: opts.health.error,
@@ -385,6 +632,12 @@ function serializeRuntimeHealth(opts: { readonly health: RuntimeHealth }): {
     lastOkAt,
     lastResetAt,
     resetCount: opts.health.resetCount,
+    lastResetSummary: opts.health.lastResetSummary,
+    lastResetChanges: opts.health.lastResetChanges,
+    lastRepairAt,
+    lastRepairAction: opts.health.lastRepairAction,
+    lastRepairOutcome: opts.health.lastRepairOutcome,
+    nextStep: opts.health.nextStep,
   };
 }
 
@@ -394,3 +647,41 @@ function toIso(opts: { readonly ms: number | null }): string | null {
   }
   return new Date(opts.ms).toISOString();
 }
+
+function isAutoRepairReason(opts: { readonly reason: string }): boolean {
+  return opts.reason.startsWith("auto-repair:");
+}
+
+function describeRepairGuidance(opts: {
+  readonly hadRuntimeBeforeReset: boolean;
+  readonly runtime: readonly RuntimeProject[];
+  readonly reason: "post_reset" | "runtime_unavailable" | "still_resetting";
+}): string | null {
+  const currentContainers = countRuntimeContainers({ runtime: opts.runtime });
+
+  if (opts.reason === "runtime_unavailable") {
+    return "Docker is still unavailable. Run `hack doctor` and retry your command.";
+  }
+
+  if (currentContainers === 0 && opts.hadRuntimeBeforeReset) {
+    return "Docker restarted and cleared previously detected project containers. Restart affected projects with `hack up`.";
+  }
+
+  if (opts.reason === "still_resetting") {
+    return "Docker runtime identity is still changing. Run `hack doctor` and retry your command.";
+  }
+
+  return null;
+}
+
+function countRuntimeContainers(opts: {
+  readonly runtime: readonly RuntimeProject[];
+}): number {
+  let count = 0;
+  for (const project of opts.runtime) {
+    for (const service of project.services.values()) {
+      count += service.containers.length;
+    }
+  }
+  return count;
+}
diff --git a/src/daemon/runtime-health.ts b/src/daemon/runtime-health.ts
index 20450b886..1e42e2d06 100644
--- a/src/daemon/runtime-health.ts
+++ b/src/daemon/runtime-health.ts
@@ -13,6 +13,19 @@ export type RuntimeIdentityResult =
   | { readonly ok: true; readonly identity: RuntimeIdentity }
   | { readonly ok: false; readonly error: string };
 
+export type RuntimeDriftField =
+  | "docker_host"
+  | "socket_path"
+  | "socket_inode"
+  | "engine_id"
+  | "engine_name"
+  | "engine_version";
+
+export type RuntimeDrift = {
+  readonly changed: readonly RuntimeDriftField[];
+  readonly summary: string | null;
+};
+
 export async function readRuntimeIdentity(opts?: {
   readonly env?: Record<string, string | undefined>;
 }): Promise<RuntimeIdentityResult> {
@@ -50,6 +63,43 @@ export function buildRuntimeFingerprint(opts: {
   return [dockerHost, socketPath, socketInode, engineId].join("|");
 }
 
+export function detectRuntimeDrift(opts: {
+  readonly previous: RuntimeIdentity | null;
+  readonly current: RuntimeIdentity;
+}): RuntimeDrift {
+  if (!opts.previous) {
+    return {
+      changed: [],
+      summary: null,
+    };
+  }
+
+  const changed: RuntimeDriftField[] = [];
+  if (opts.previous.dockerHost !== opts.current.dockerHost) {
+    changed.push("docker_host");
+  }
+  if (opts.previous.socketPath !== opts.current.socketPath) {
+    changed.push("socket_path");
+  }
+  if (opts.previous.socketInode !== opts.current.socketInode) {
+    changed.push("socket_inode");
+  }
+  if (opts.previous.engineId !== opts.current.engineId) {
+    changed.push("engine_id");
+  }
+  if (opts.previous.engineName !== opts.current.engineName) {
+    changed.push("engine_name");
+  }
+  if (opts.previous.engineVersion !== opts.current.engineVersion) {
+    changed.push("engine_version");
+  }
+
+  return {
+    changed,
+    summary: changed.length > 0 ? summarizeRuntimeDrift({ changed }) : null,
+  };
+}
+
 function resolveDockerHost(opts: {
   readonly env: Record<string, string | undefined>;
 }): { readonly dockerHost: string | null; readonly socketPath: string | null } {
@@ -169,3 +219,19 @@ function formatDockerError(opts: {
   }
   return `docker info failed (exit ${opts.exitCode})`;
 }
+
+function summarizeRuntimeDrift(opts: {
+  readonly changed: readonly RuntimeDriftField[];
+}): string {
+  const labels = opts.changed.map((field) => runtimeDriftLabels[field]);
+  return `${labels.join(", ")} changed`;
+}
+
+const runtimeDriftLabels: Record<RuntimeDriftField, string> = {
+  docker_host: "docker host",
+  socket_path: "socket path",
+  socket_inode: "socket inode",
+  engine_id: "engine id",
+  engine_name: "engine name",
+  engine_version: "engine version",
+};
diff --git a/src/daemon/server.ts b/src/daemon/server.ts
index f9bff1ef0..6f623d9e6 100644
--- a/src/daemon/server.ts
+++ b/src/daemon/server.ts
@@ -423,6 +423,12 @@ async function handleRequest({
       runtime_last_ok_at: runtimeHealth.lastOkAt,
       runtime_reset_at: runtimeHealth.lastResetAt,
       runtime_reset_count: runtimeHealth.resetCount,
+      runtime_reset_summary: runtimeHealth.lastResetSummary,
+      runtime_reset_changes: runtimeHealth.lastResetChanges,
+      runtime_last_repair_at: runtimeHealth.lastRepairAt,
+      runtime_repair_action: runtimeHealth.lastRepairAction,
+      runtime_repair_outcome: runtimeHealth.lastRepairOutcome,
+      runtime_next_step: runtimeHealth.nextStep,
     });
   }
 
@@ -1493,6 +1499,12 @@ function formatRuntimeHealth(opts: { readonly health: RuntimeHealth | null }): {
   readonly lastOkAt: string | null;
   readonly lastResetAt: string | null;
   readonly resetCount: number;
+  readonly lastResetSummary: string | null;
+  readonly lastResetChanges: readonly string[];
+  readonly lastRepairAt: string | null;
+  readonly lastRepairAction: string | null;
+  readonly lastRepairOutcome: "stabilized" | "manual_action_required" | null;
+  readonly nextStep: string | null;
 } {
   if (!opts.health) {
     return {
@@ -1502,6 +1514,12 @@ function formatRuntimeHealth(opts: { readonly health: RuntimeHealth | null }): {
       lastOkAt: null,
       lastResetAt: null,
       resetCount: 0,
+      lastResetSummary: null,
+      lastResetChanges: [],
+      lastRepairAt: null,
+      lastRepairAction: null,
+      lastRepairOutcome: null,
+      nextStep: null,
     };
   }
   return {
@@ -1511,6 +1529,12 @@ function formatRuntimeHealth(opts: { readonly health: RuntimeHealth | null }): {
     lastOkAt: toIso({ ms: opts.health.lastOkAtMs }),
     lastResetAt: toIso({ ms: opts.health.lastResetAtMs }),
     resetCount: opts.health.resetCount,
+    lastResetSummary: opts.health.lastResetSummary,
+    lastResetChanges: opts.health.lastResetChanges,
+    lastRepairAt: toIso({ ms: opts.health.lastRepairAtMs }),
+    lastRepairAction: opts.health.lastRepairAction,
+    lastRepairOutcome: opts.health.lastRepairOutcome,
+    nextStep: opts.health.nextStep,
   };
 }
 
diff --git a/tests/daemon-client.test.ts b/tests/daemon-client.test.ts
new file mode 100644
index 000000000..08fd1e800
--- /dev/null
+++ b/tests/daemon-client.test.ts
@@ -0,0 +1,78 @@
+import { afterAll, beforeEach, expect, mock, test } from "bun:test";
+
+const readControlPlaneConfigMock = mock(async () => {
+  throw new Error("should not attempt daemon autostart");
+});
+
+mock.module("../src/control-plane/sdk/config.ts", () => ({
+  readControlPlaneConfig: readControlPlaneConfigMock,
+}));
+
+mock.module("../src/lib/hack-cli.ts", () => ({
+  resolveHackInvocation: async () => ({
+    bin: "hack",
+    args: [],
+  }),
+}));
+
+mock.module("../src/lib/shell.ts", () => ({
+  exec: async () => ({
+    exitCode: 0,
+    stdout: "",
+    stderr: "",
+  }),
+}));
+
+mock.module("../src/daemon/launchd.ts", () => ({
+  getLaunchdServiceStatus: async () => ({
+    installed: false,
+    loaded: false,
+    running: false,
+    pid: null,
+    exitStatus: null,
+  }),
+  installLaunchdService: async () => ({ ok: true }),
+  kickstartLaunchdService: async () => ({ ok: true }),
+}));
+
+mock.module("../src/daemon/paths.ts", () => ({
+  resolveDaemonPaths: () => ({
+    root: "/tmp/hackd",
+    socketPath: "/tmp/hackd.sock",
+    pidPath: "/tmp/hackd.pid",
+    logPath: "/tmp/hackd.log",
+    launchdPlistPath: "/tmp/hackd.plist",
+  }),
+}));
+
+const readDaemonStatusMock = mock(async () => ({
+  running: false,
+  pid: null,
+  socketExists: false,
+  logExists: false,
+}));
+
+mock.module("../src/daemon/status.ts", () => ({
+  readDaemonStatus: readDaemonStatusMock,
+}));
+
+import { requestDaemonJson } from "../src/daemon/client.ts";
+
+beforeEach(() => {
+  readControlPlaneConfigMock.mockClear();
+  readDaemonStatusMock.mockClear();
+});
+
+afterAll(() => {
+  mock.restore();
+});
+
+test("requestDaemonJson skips daemon autostart when autoStart is false", async () => {
+  const response = await requestDaemonJson({
+    path: "/v1/metrics",
+    autoStart: false,
+  });
+
+  expect(response).toBeNull();
+  expect(readControlPlaneConfigMock).not.toHaveBeenCalled();
+});
diff --git a/tests/projects-command.test.ts b/tests/projects-command.test.ts
new file mode 100644
index 000000000..57029e613
--- /dev/null
+++ b/tests/projects-command.test.ts
@@ -0,0 +1,60 @@
+import { expect, test } from "bun:test";
+
+import { __testOnlyProjectsCommand } from "../src/commands/projects.ts";
+
+test("buildRuntimeRecoveryNotice reports manual action guidance", () => {
+  const notice = __testOnlyProjectsCommand.buildRuntimeRecoveryNotice({
+    runtimeMeta: {
+      resetCount: 2,
+      lastResetSummary: "engine id changed",
+      lastRepairAction: "refresh_runtime_snapshot",
+      lastRepairOutcome: "manual_action_required",
+      nextStep: "Restart affected projects with `hack up`.",
+    },
+  });
+
+  expect(notice).toEqual({
+    title: "Runtime reset detected",
+    tone: "warn",
+    lines: [
+      "Detected reset #2: engine id changed",
+      "hackd repair: refresh_runtime_snapshot -> manual_action_required",
+      "Next step: Restart affected projects with `hack up`.",
+    ],
+  });
+});
+
+test("buildRuntimeRecoveryNotice reports stabilized repairs", () => {
+  const notice = __testOnlyProjectsCommand.buildRuntimeRecoveryNotice({
+    runtimeMeta: {
+      resetCount: 1,
+      lastResetSummary: "socket inode changed",
+      lastRepairAction: "refresh_runtime_snapshot",
+      lastRepairOutcome: "stabilized",
+      nextStep: null,
+    },
+  });
+
+  expect(notice).toEqual({
+    title: "Runtime reset detected",
+    tone: "info",
+    lines: [
+      "Detected reset #1: socket inode changed",
+      "hackd repair: refresh_runtime_snapshot -> stabilized",
+    ],
+  });
+});
+
+test("buildRuntimeRecoveryNotice returns null without recovery metadata", () => {
+  const notice = __testOnlyProjectsCommand.buildRuntimeRecoveryNotice({
+    runtimeMeta: {
+      resetCount: 0,
+      lastResetSummary: null,
+      lastRepairAction: null,
+      lastRepairOutcome: null,
+      nextStep: null,
+    },
+  });
+
+  expect(notice).toBeNull();
+});
diff --git a/tests/runtime-cache.test.ts b/tests/runtime-cache.test.ts
index 97cc72ccf..98fab6922 100644
--- a/tests/runtime-cache.test.ts
+++ b/tests/runtime-cache.test.ts
@@ -85,7 +85,30 @@ test("runtime cache refresh records healthy snapshot", async () => {
     {
       project: "alpha",
       workingDir: null,
-      services: new Map(),
+      services: new Map([
+        [
+          "app",
+          {
+            service: "app",
+            containers: [
+              {
+                id: "alpha-app-1",
+                project: "alpha",
+                service: "app",
+                state: "running",
+                status: "Up 10 seconds",
+                name: "alpha-app-1",
+                ports: "",
+                workingDir: "/tmp/alpha/.hack",
+                image: "imbios/bun-node:latest",
+                labels: null,
+                mounts: [],
+                networks: [],
+              },
+            ],
+          },
+        ],
+      ]),
       isGlobal: false,
     },
   ];
@@ -321,6 +344,23 @@ test("runtime cache detects runtime resets via fingerprint", async () => {
       engineVersion: null,
     },
   });
+  runtimeQueue.push({
+    ok: true,
+    runtime,
+    error: null,
+    checkedAtMs: Date.now(),
+  });
+  identityQueue.push({
+    ok: true,
+    identity: {
+      dockerHost: null,
+      socketPath: null,
+      socketInode: null,
+      engineId: "engine-b",
+      engineName: "docker-desktop",
+      engineVersion: "27.0.0",
+    },
+  });
 
   const cache = createRuntimeCache({});
   await cache.refresh({ reason: "prime" });
@@ -329,6 +369,105 @@ test("runtime cache detects runtime resets via fingerprint", async () => {
   const snapshot = cache.getSnapshot();
   expect(snapshot?.health.resetCount).toBe(1);
   expect(snapshot?.health.lastResetAtMs).not.toBeNull();
+  expect(snapshot?.health.lastResetSummary).toContain("engine id");
+  expect(snapshot?.health.lastResetChanges).toEqual(["engine_id"]);
+  expect(snapshot?.health.lastRepairAction).toBe("refresh_runtime_snapshot");
+  expect(snapshot?.health.lastRepairOutcome).toBe("stabilized");
+  expect(snapshot?.health.nextStep).toBe(null);
+  expect(autoRegisterCalls.length).toBe(3);
+});
+
+test("runtime cache gives a clear next step when reset repair cannot restore prior runtime", async () => {
+  const runtime: RuntimeProject[] = [
+    {
+      project: "alpha",
+      workingDir: null,
+      services: new Map([
+        [
+          "app",
+          {
+            service: "app",
+            containers: [
+              {
+                id: "alpha-app-1",
+                project: "alpha",
+                service: "app",
+                state: "running",
+                status: "Up 10 seconds",
+                name: "alpha-app-1",
+                ports: "",
+                workingDir: "/tmp/alpha/.hack",
+                image: "imbios/bun-node:latest",
+                labels: null,
+                mounts: [],
+                networks: [],
+              },
+            ],
+          },
+        ],
+      ]),
+      isGlobal: false,
+    },
+  ];
+  runtimeQueue.push({
+    ok: true,
+    runtime,
+    error: null,
+    checkedAtMs: Date.now(),
+  });
+  identityQueue.push({
+    ok: true,
+    identity: {
+      dockerHost: null,
+      socketPath: null,
+      socketInode: null,
+      engineId: "engine-a",
+      engineName: null,
+      engineVersion: null,
+    },
+  });
+  runtimeQueue.push({
+    ok: true,
+    runtime: [],
+    error: null,
+    checkedAtMs: Date.now(),
+  });
+  identityQueue.push({
+    ok: true,
+    identity: {
+      dockerHost: null,
+      socketPath: null,
+      socketInode: null,
+      engineId: "engine-b",
+      engineName: null,
+      engineVersion: null,
+    },
+  });
+  runtimeQueue.push({
+    ok: true,
+    runtime: [],
+    error: null,
+    checkedAtMs: Date.now(),
+  });
+  identityQueue.push({
+    ok: true,
+    identity: {
+      dockerHost: null,
+      socketPath: null,
+      socketInode: null,
+      engineId: "engine-b",
+      engineName: null,
+      engineVersion: null,
+    },
+  });
+
+  const cache = createRuntimeCache({});
+  await cache.refresh({ reason: "prime" });
+  await cache.refresh({ reason: "reset" });
+
+  const snapshot = cache.getSnapshot();
+  expect(snapshot?.health.lastRepairOutcome).toBe("manual_action_required");
+  expect(snapshot?.health.nextStep).toContain("hack up");
 });
 
 test("getPsPayload matches normalized compose project names", async () => {

From fc35b0882b5e85c1e3c7ee0c2722190847bf06d6 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:14:31 +0000
Subject: [PATCH 064/134] HACK-468: checkpoint merge prep

---
 docs/cli.md                                   |   2 +-
 .../tests/org-team-membership.test.ts         | 198 ++++++++++++++++++
 src/commands/org.ts                           |   2 +-
 3 files changed, 200 insertions(+), 2 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index f88d07d30..763f31f44 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -318,7 +318,7 @@ Lifecycle semantics:
 - `invite` creates `pending`
 - `add` creates `active`
 - `remove` transitions `pending` or `active` membership to `removed`
-- Removing org access is expected to preview and cascade affected team memberships in the same org
+- Current behavior removes only the org-level membership record; preview-and-cascade admin UX is tracked separately
 
 #### hack org member list
 
diff --git a/services/auth-broker/tests/org-team-membership.test.ts b/services/auth-broker/tests/org-team-membership.test.ts
index 3a57f86b0..b6977e6ce 100644
--- a/services/auth-broker/tests/org-team-membership.test.ts
+++ b/services/auth-broker/tests/org-team-membership.test.ts
@@ -305,6 +305,204 @@ describe("org and team membership broker routes", () => {
     expect(inviteResponse.status).toBe(409);
   });
 
+  test("org member removal cascades matching team memberships and invites to removed", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const ownerApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "cli",
+          org: "hack",
+          name: "CLI",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "user-456",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "user-456",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "person@example.com",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/invite", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "person@example.com",
+        }),
+      })
+    );
+
+    const removeActiveResponse = await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/remove", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "user-456",
+        }),
+      })
+    );
+    expect(removeActiveResponse.status).toBe(200);
+
+    const removePendingResponse = await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/remove", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "person@example.com",
+        }),
+      })
+    );
+    expect(removePendingResponse.status).toBe(200);
+
+    const teamRemovedResponse = await ownerApp.handle(
+      new Request(
+        "http://localhost/v1/auth/teams/cli/members?org=hack&state=removed"
+      )
+    );
+    expect(teamRemovedResponse.status).toBe(200);
+    const removedPayload = (await teamRemovedResponse.json()) as {
+      readonly memberships?: ReadonlyArray<{
+        readonly target?: string;
+        readonly state?: string;
+      }>;
+    };
+    const removedTargets = new Set(
+      (removedPayload.memberships ?? []).map((membership) => membership.target)
+    );
+    expect(removedTargets.has("user-456")).toBe(true);
+    expect(removedTargets.has("person@example.com")).toBe(true);
+    expect(
+      (removedPayload.memberships ?? []).every(
+        (membership) => membership.state === "removed"
+      )
+    ).toBe(true);
+  });
+
+  test("member list hides removed memberships by default and exposes them with state filters", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const ownerApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "user-456",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/remove", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "user-456",
+        }),
+      })
+    );
+
+    const defaultListResponse = await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members")
+    );
+    expect(defaultListResponse.status).toBe(200);
+    const defaultListPayload = (await defaultListResponse.json()) as {
+      readonly memberships?: ReadonlyArray<{
+        readonly target?: string;
+        readonly state?: string;
+      }>;
+    };
+    expect(
+      (defaultListPayload.memberships ?? []).some(
+        (membership) => membership.target === "user-456"
+      )
+    ).toBe(false);
+    expect(
+      (defaultListPayload.memberships ?? []).every(
+        (membership) =>
+          membership.state === "pending" || membership.state === "active"
+      )
+    ).toBe(true);
+
+    const removedListResponse = await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members?state=removed")
+    );
+    expect(removedListResponse.status).toBe(200);
+    const removedListPayload = (await removedListResponse.json()) as {
+      readonly memberships?: ReadonlyArray<{
+        readonly target?: string;
+        readonly state?: string;
+      }>;
+    };
+    expect(
+      (removedListPayload.memberships ?? []).some(
+        (membership) =>
+          membership.target === "user-456" && membership.state === "removed"
+      )
+    ).toBe(true);
+  });
+
   test("recipient invitation accept and decline are scoped to the signed-in email", async () => {
     const store = new InMemoryOrgTeamsStore();
     const session = createSession({
diff --git a/src/commands/org.ts b/src/commands/org.ts
index eba63e5b4..b7ba814e7 100644
--- a/src/commands/org.ts
+++ b/src/commands/org.ts
@@ -109,7 +109,7 @@ const memberRemoveSpec = defineCommand({
   name: "remove",
   summary: "Remove org membership or cancel a pending org invite",
   description:
-    "Admin-side revoke verb. Removing org access is expected to preview and cascade affected team memberships in the same org.",
+    "Admin-side revoke verb. Current behavior removes only the org-level membership record; preview-and-cascade admin UX is tracked separately.",
   group: "Global",
   options: [optJson, optBrokerUrl] as const,
   positionals: orgMemberTargetPositionals,

From 5fe5859f88f3dfdaab4259ff6a874fbc84186e3f Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:17:28 +0000
Subject: [PATCH 065/134] docs(tickets): define normalized sync idempotency

---
 docs/guides/tickets.md                        |  29 +-
 ...kets-normalized-sync-idempotency-design.md | 298 ++++++++++++++++++
 2 files changed, 318 insertions(+), 9 deletions(-)
 create mode 100644 docs/plans/2026-03-14-tickets-normalized-sync-idempotency-design.md

diff --git a/docs/guides/tickets.md b/docs/guides/tickets.md
index 279f60a02..55ad49492 100644
--- a/docs/guides/tickets.md
+++ b/docs/guides/tickets.md
@@ -1,8 +1,6 @@
 # Tickets (git-backed)
 
-The tickets extension is a lightweight, git-backed ticket log intended for small teams and solo dev.
-It stores events in a dedicated git ref (`refs/hack/tickets` by default, hidden from branch lists) so
-ticket history is versioned and syncable without requiring an external service.
+The tickets extension is a lightweight, git-backed ticket log intended for small teams and solo dev. It stores events in a dedicated git ref (`refs/hack/tickets` by default, hidden from branch lists) so ticket history is versioned and syncable without requiring an external service.
 
 - CLI namespace: `tickets`
 - Extension id: `dance.hack.tickets`
@@ -40,13 +38,14 @@ hack x tickets setup
 ```
 
 Options:
+
 - `--global` installs the Codex skill into `~/.codex/skills/hack-tickets/` instead of the repo.
 - `--agents` / `--claude` / `--all` control which agent-doc files get a tickets snippet.
 - `--check` and `--remove` work as expected.
 
 Notes:
-- Most tickets commands prompt to run setup if `.hack/tickets/` is tracked, missing from `.gitignore`,
-  or if agent docs/skills are missing (TTY + gum only).
+
+- Most tickets commands prompt to run setup if `.hack/tickets/` is tracked, missing from `.gitignore`, or if agent docs/skills are missing (TTY + gum only).
 - Setup also prompts to repair legacy tickets branches or stray files in the tickets ref.
 - In non-interactive or `--json` modes, the CLI prints a warning instead of prompting.
 
@@ -116,8 +115,11 @@ Recommended body template (Markdown):
 
 ```md
 ## Context
+
 ## Goals
+
 ## Notes
+
 ## Links
 ```
 
@@ -130,6 +132,14 @@ Tip: use `--body-stdin` for multi-line markdown.
 - Ticket writes automatically commit and push to the tickets ref when git sync is enabled and a remote exists.
 - `sync` normalizes the event logs, commits, and pushes the tickets ref.
 
+### Sync guarantees
+
+- Log normalization dedupes repeated raw events by `eventId`.
+- Normalized logs are ordered by `ts`, then `eventId`, so every machine folds the same log in the same order.
+- When adding external sync adapters, treat `eventId` as transport dedupe only. The logical external change also needs a deterministic operation identity so repeated deliveries and multi-machine replays collapse safely.
+- If two systems disagree on a shared field, record an explicit sync conflict instead of silently overwriting one side.
+- Detailed design guidance for normalized external sync lives in `docs/plans/2026-03-14-tickets-normalized-sync-idempotency-design.md`.
+
 ### Storage layout
 
 In your project repo:
@@ -140,8 +150,7 @@ In your project repo:
 
 ## Configuration
 
-Tickets git configuration lives under `controlPlane.tickets.git`.
-Defaults:
+Tickets git configuration lives under `controlPlane.tickets.git`. Defaults:
 
 - `enabled: true`
 - `branch: "hack/tickets"`
@@ -158,16 +167,18 @@ hack config set --global 'controlPlane.tickets.git.refMode' 'hidden'
 ```
 
 Notes:
-- If your remote rejects hidden refs, set `refMode` to `heads` to use `refs/heads/<branch>` and
-  protect the branch in your git hosting UI.
+
+- If your remote rejects hidden refs, set `refMode` to `heads` to use `refs/heads/<branch>` and protect the branch in your git hosting UI.
 
 ## When to use this
 
 Use tickets when you want:
+
 - A local-first backlog that works offline.
 - A shared ticket stream without adding Jira/Linear.
 - A simple paper trail for small projects.
 
 Don’t use it when:
+
 - You need multi-user assignment, workflow states, or strict permissions.
 - You need rich issue templates or deep integrations.
diff --git a/docs/plans/2026-03-14-tickets-normalized-sync-idempotency-design.md b/docs/plans/2026-03-14-tickets-normalized-sync-idempotency-design.md
new file mode 100644
index 000000000..0b03d942b
--- /dev/null
+++ b/docs/plans/2026-03-14-tickets-normalized-sync-idempotency-design.md
@@ -0,0 +1,298 @@
+# Tickets Normalized Sync Idempotency Design
+
+## Goal
+
+Define how normalized ticket sync behaves when the same external change is observed multiple times across multiple machines, while making conflicts explicit and preventing silent corruption.
+
+## Existing State
+
+- The tickets ref is an append-only event log stored in monthly JSONL files under `.hack/tickets/events/`.
+- Ticket log merge and normalization already dedupe raw log lines by `eventId` and sort by `ts`, then `eventId`.
+- The ticket store already has append-only events for sync checkpoints, sync conflicts, and sync conflict resolution.
+- Current store helpers generate random ids for checkpoints and conflicts, which is fine for local writes but does not yet define a deterministic identity for the same external change replayed on different machines.
+- Current Linear conflict dedupe is pragmatic and narrow. It avoids creating the same open conflict more than once for the same observed field/value pair, but it is not yet the system-wide contract for normalized sync.
+- Current Linear authority is binary and ticket-scoped: `owner === "linear"` or `source === "linear"` makes Linear authoritative for the main mirrored fields; everything else is treated as Hack-authoritative.
+- Current conflict detection only covers a small shared-field set: `title`, `body`, `status`, and `project`. Manual resolution records a resolution event, but it does not itself mutate either side.
+
+## Approaches Considered
+
+### 1. Document the current behavior as-is
+
+Keep random sync ids and describe the current Linear-specific dedupe rules.
+
+Why not:
+
+- repeated logical external writes would still produce distinct checkpoint and conflict events on different machines
+- correctness would continue depending on provider-specific ad hoc logic
+- the normalized store would not have a cross-provider convergence contract
+
+### 2. Add deterministic logical operation identity on top of transport dedupe
+
+Keep the append-only event log and event-fold materialization model, but define a deterministic identity for each normalized external operation and for each materialized conflict.
+
+Why this is the recommended direction:
+
+- it matches the current store architecture
+- it works with the existing `eventId`-based merge pipeline
+- it makes multi-machine replay converge without introducing a sidecar sync database
+
+### 3. Introduce a heavier sync shadow state or CRDT layer
+
+Add a separate replicated sync state model with richer merge semantics.
+
+Why not:
+
+- it is disproportionate to the current tickets architecture
+- it adds a second source of truth for sync state
+- the current acceptance criteria do not require arbitrary automatic merges
+
+## Approved Direction
+
+Treat transport dedupe and logical sync dedupe as separate concerns.
+
+- `eventId` is the transport-level identity. Duplicate log lines with the same `eventId` must always collapse safely.
+- `operationKey` is the logical identity of a normalized external change. Every machine that observes the same remote change must derive the same `operationKey`.
+- External sync writers must derive deterministic event ids from that `operationKey` so the same logical write collapses during merge, retry, and replay.
+- Conflict handling must be checkpoint-based and explicit. When both sides changed and policy does not allow auto-resolution, the system records an open conflict and stops short of destructive mutation.
+- This extends the current append-only store; it does not replace normalization, git-ref sync, or fold-based materialization.
+
+## Design Decisions
+
+### 1. Define the idempotency unit
+
+The unit of idempotency is a normalized sync operation, not a webhook delivery, process invocation, or git commit.
+
+Each normalized external change should derive an `operationKey` from:
+
+- provider identity, such as `linear`
+- provider profile or connection scope when relevant
+- external entity kind and id, such as `issue:123`
+- remote change token, version, or stable updated-at marker
+- normalized mutation kind, such as `ticket.pull.field_update`
+- field scope when a single remote change fans out into multiple local decisions
+
+Example shape:
+
+```text
+linear:default:issue:LIN-123:update:2026-03-14T10:15:00.000Z:title
+```
+
+This key must be deterministic across machines. If two machines see the same remote change and derive different keys, that is a bug in the adapter.
+
+### 2. Derive deterministic event ids from the operation
+
+Every normalized event emitted from an external change should use a deterministic `eventId`, not a random UUID.
+
+Recommended rule:
+
+- build `eventId` from `operationKey` plus a stable suffix for the emitted event kind
+- use one suffix per materialized effect, such as `apply`, `checkpoint`, `conflict`, or `resolution`
+
+Example:
+
+```text
+sha256("${operationKey}:checkpoint")
+sha256("${operationKey}:conflict")
+```
+
+That gives the system three safety properties:
+
+- retrying the same write on one machine is a no-op
+- replaying the same external delivery on another machine is a no-op
+- merging diverged ticket refs collapses duplicate logical writes without special-case reconciliation
+
+### 3. Keep checkpoints as the baseline for three-way decisions
+
+Conflict decisions must be based on the last acknowledged sync baseline, not only on wall-clock timestamps.
+
+For each synchronized field:
+
+- the last applied checkpoint defines the remote baseline
+- current local materialized state defines the local candidate
+- incoming normalized external state defines the remote candidate
+
+`remoteUpdatedAt` or provider cursors are useful evidence, but they are advisory. The baseline checkpoint is the real decision boundary.
+
+### 4. Apply a fixed conflict matrix
+
+For each synchronized field, normalized sync should follow this matrix:
+
+| Condition | Behavior |
+| --- | --- |
+| Incoming remote value equals current local value | No-op, optionally record a fresher checkpoint |
+| Only the remote side changed since the baseline | Apply the remote value and record a checkpoint |
+| Only the local side changed since the baseline | Keep the local value; do not manufacture a conflict on pull |
+| Both sides changed to the same normalized value | No conflict, just advance the checkpoint |
+| Both sides changed to different values | Record a conflict or an explicit auto-resolution event according to field authority |
+| One side cleared a value and the other edited it | Treat as a divergent two-sided change |
+
+The important rule is that a divergent two-sided change must never silently overwrite the losing side.
+
+### 5. Make authority decisions explicit
+
+Each synchronized field must declare one of three authority modes. Adapters should not improvise this case-by-case.
+
+This is intentionally stricter than the current Linear integration, which derives authority from ticket-level `owner` and `source`. Normalized sync should move authority decisions to the field contract so multi-provider behavior stays predictable.
+
+#### External-authoritative
+
+Use for identity and provenance fields that mirror the provider:
+
+- external id
+- external key
+- external url
+- provider project or team bindings
+
+Behavior:
+
+- remote wins
+- if a local value diverged, record an explicit audit trail before or alongside the overwrite
+- the resolution should be visible as `accept_remote`, not implied by absence of a conflict
+
+#### Local-authoritative
+
+Use for Hack-only fields that external systems do not own:
+
+- review notes
+- local workflow metadata
+- machine-local or repo-local annotations that are not mirrored upstream
+
+Behavior:
+
+- local wins
+- incoming external attempts are ignored or mapped to another field
+- if needed, emit a resolved conflict or review note so the discard is visible
+
+#### Shared-manual
+
+Use for fields where both systems can legitimately change the value:
+
+- title
+- body
+- status
+- assignee
+- dependency edges
+
+Behavior:
+
+- auto-apply one-sided changes
+- when both sides changed to different values, create an open conflict and stop automatic mutation for that field
+- require either a user resolution or a documented provider-specific merge rule
+
+### 6. Make conflicts idempotent too
+
+Conflict records need their own stable identity.
+
+An open conflict should be unique by a deterministic `conflictKey` built from:
+
+- ticket id
+- provider
+- field
+- baseline checkpoint id or remote version
+- local normalized value
+- remote normalized value
+
+Repeated observation of the same divergence must not create duplicate open conflicts. It should:
+
+- return the existing open conflict if it is still unresolved
+- no-op if the same conflict record is already present
+
+When a resolution is applied:
+
+- repeated application of the same resolution to the same open conflict must be a no-op
+- a later, different divergence must create a new conflict with a new key instead of reopening the old one implicitly
+
+### 7. Preserve convergence under multi-machine replay
+
+The convergence contract for normalized sync is:
+
+1. Multiple machines may append the same deterministic events.
+2. Ticket log merge collapses duplicates by `eventId`.
+3. Materialization is a pure fold over the normalized log.
+4. Therefore every machine converges to the same ticket state after sync.
+
+This means correctness cannot depend on:
+
+- which machine saw the external change first
+- whether a push was retried
+- exact wall-clock ordering between two copies of the same logical external operation
+
+Clock skew may change presentation order for unrelated events with similar timestamps, but it must not change conflict outcomes or authority decisions.
+
+## Required Event Metadata
+
+Normalized external sync events should carry enough metadata to explain why they exist and to make replay deterministic.
+
+Recommended fields:
+
+- `provider`
+- `profileId`
+- `operationKey`
+- `externalEntityId`
+- `externalVersion` or equivalent provider change token
+- `baselineCheckpointId`
+- `authority`
+- `origin`, such as `manual_apply`, `autosync`, or `webhook_replay`
+
+This metadata belongs on checkpoint, conflict, and explicit resolution events, even if some fields remain optional for local-only writes.
+
+When available, providers should also persist the specific remote field scope that fed the operation. That keeps one remote entity update that fans out into multiple field decisions debuggable during replay.
+
+## Guidance For Specific Cases
+
+### Repeated webhook delivery
+
+- Same provider event, same remote version, same normalized field change
+- Derive the same `operationKey`
+- Emit the same deterministic `eventId`s
+- Result: safe no-op after merge or replay
+
+### Retry after uncertain push outcome
+
+- Reuse the same generated ids for the pending normalized events
+- Do not generate fresh UUIDs on each retry
+- Result: safe retry even if the first push actually landed
+
+### Same remote change observed on two laptops
+
+- Both laptops derive the same ids
+- Both can append locally
+- Later sync collapses duplicate lines by `eventId`
+- Result: converged state without manual cleanup
+
+### Divergent local and remote edit on a shared field
+
+- Detect against the last checkpoint
+- Record one open conflict with a stable `conflictKey`
+- Leave the current field unchanged until the conflict is resolved
+- Result: no silent overwrite
+
+### Divergent edit on an external-authoritative field
+
+- Record visible authority handling
+- Apply the remote value
+- Mark the outcome as an explicit `accept_remote` resolution
+- Result: authority is enforced without hiding the disagreement
+
+## Implementation Consequences
+
+This design implies follow-up changes in the normalized sync core:
+
+- external sync helpers must accept caller-provided stable ids instead of always generating random UUIDs
+- checkpoint and conflict events should persist `operationKey` and baseline metadata
+- conflict dedupe should move from ad hoc field/value matching to deterministic conflict keys
+- conflict resolution helpers should become idempotent when the same resolution is replayed
+- provider adapters must define and test their field authority map
+- `tickets show --json` and related inspection surfaces should expose the new sync metadata so operators can explain why a conflict or checkpoint exists
+
+## Non-Goals
+
+- CRDT-style automatic merge for arbitrary ticket fields
+- last-writer-wins based only on wall-clock time
+- hidden authority decisions that discard one side without recording what happened
+
+## Acceptance Criteria Mapping
+
+- Repeated application of the same external change is safe because every machine derives the same logical operation key and deterministic event ids.
+- Conflicts are detectable because each synchronized field is evaluated against a checkpoint baseline with explicit two-sided divergence rules.
+- Multi-machine synchronization converges because duplicate logical writes collapse by `eventId`, while true disagreements materialize as explicit conflicts instead of silent corruption.

From 271c1441dc3e000701a238457046ed3617fae669 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:22:55 +0000
Subject: [PATCH 066/134] fix(session): honor mux fallback for workspace flows

---
 docs/cli.md                   |   8 +-
 docs/sessions.md              |   5 +-
 src/commands/session.ts       | 412 +++++++++++++++++++++++-----------
 tests/session-command.test.ts |  36 +++
 tests/session-help.test.ts    |   7 +-
 5 files changed, 324 insertions(+), 144 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 294260e40..063fbdadb 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -570,9 +570,9 @@ Subcommands:
 
 | Subcommand | Summary |
 | --- | --- |
-| `list` | List active tmux workspaces |
+| `list` | List active workspaces |
 | `start` | Reuse the default project workspace or create an isolated one |
-| `stop` | Stop a tmux-backed workspace |
+| `stop` | Stop a workspace |
 | `attach` | Attach to an existing workspace |
 | `exec` | Send a command to a running workspace |
 | `panes` | List panes in a tmux workspace |
@@ -599,13 +599,13 @@ Options:
 
 Usage: `hack session attach <workspace>`
 
-Attach to a running tmux workspace by name. When you are already inside tmux, hack switches clients instead of nesting tmux inside tmux.
+Attach to a running workspace by name. Tmux switches clients instead of nesting tmux inside tmux, while zellij attaches to the named session directly.
 
 #### hack session exec
 
 Usage: `hack session exec <workspace> <command>`
 
-Queue a command in the workspace's active pane without opening a new shell. This is useful for long-running agents, background checks, or remote follow-up work.
+Queue a command in the workspace without opening a new interactive attach flow. Tmux sends it to the active pane; zellij opens a new pane for the command. This is useful for long-running agents, background checks, or remote follow-up work.
 
 #### hack session panes
 
diff --git a/docs/sessions.md b/docs/sessions.md
index 852463298..8c8851f85 100644
--- a/docs/sessions.md
+++ b/docs/sessions.md
@@ -18,7 +18,7 @@ hack session
 # Reuse the default workspace for a project, or create it if needed
 hack session start <project>
 
-# List active tmux workspaces
+# List active workspaces
 hack session list
 
 # Attach to an existing workspace by name
@@ -45,7 +45,7 @@ hack session panes <workspace>
 ### Interactive picker
 
 Running `hack session` without arguments opens an interactive picker showing:
-- **Active workspaces**: running tmux workspaces, with attached/detached status
+- **Active workspaces**: running workspaces from the configured mux backend(s), with attached status when the backend can report it
 - **Available projects**: registered projects that do not currently have a default workspace
 
 When selecting an attached session, you can choose to:
@@ -91,6 +91,7 @@ hack session attach my-project
 ```
 
 Use `attach` when you already know which workspace you want. If you are already inside tmux, hack switches clients instead of nesting tmux inside tmux. When attaching, tmux detaches other clients to avoid terminal size conflicts across multiple devices.
+If the workspace is running in zellij, hack attaches to that named session directly instead.
 
 ### Exec
 
diff --git a/src/commands/session.ts b/src/commands/session.ts
index b4a8aacbf..7659cf774 100644
--- a/src/commands/session.ts
+++ b/src/commands/session.ts
@@ -7,14 +7,27 @@ import type {
 } from "../cli/command.ts";
 import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
 import { optJson, optPretty } from "../cli/options.ts";
+import { findProjectContext, type ProjectContext } from "../lib/project.ts";
 import type { RegisteredProject } from "../lib/projects-registry.ts";
 import { readProjectsRegistry } from "../lib/projects-registry.ts";
 import { exec, run } from "../lib/shell.ts";
+import type {
+  MuxBackend,
+  MuxBackendName,
+  MuxSession,
+} from "../mux/mux-backend.ts";
+import {
+  listMuxSessions,
+  resolveDefaultBackendName,
+  resolveMux,
+} from "../mux/mux-resolver.ts";
 import {
   buildSessionName,
   getNextNumericSessionSuffix,
   parseSessionBase,
 } from "../mux/session-names.ts";
+import { attachTmuxSession } from "../mux/tmux-backend.ts";
+import { attachZellijSession } from "../mux/zellij-backend.ts";
 import { logger } from "../ui/logger.ts";
 import {
   buildSessionPanesEndEvent,
@@ -31,15 +44,6 @@ import {
   writeSessionStreamEvent,
 } from "./session-utils.ts";
 
-/**
- * Parsed tmux session info.
- */
-interface TmuxSession {
-  readonly name: string;
-  readonly attached: boolean;
-  readonly path: string | null;
-}
-
 const optUp = defineOption({
   name: "up",
   type: "boolean",
@@ -110,7 +114,7 @@ const optMaxMs = defineOption({
 // Subcommand specs
 const listSpec = defineCommand({
   name: "list",
-  summary: "List active tmux workspaces",
+  summary: "List active workspaces",
   group: "Project",
   options: [],
   positionals: [],
@@ -132,7 +136,7 @@ const startSpec = defineCommand({
 
 const stopSpec = defineCommand({
   name: "stop",
-  summary: "Stop a tmux-backed workspace",
+  summary: "Stop a workspace",
   group: "Project",
   options: [],
   positionals: [
@@ -146,7 +150,7 @@ const attachSpec = defineCommand({
   summary: "Attach to an existing workspace",
   group: "Project",
   description:
-    "Attach to a running tmux workspace by name. When you are already inside tmux, hack switches clients instead of nesting tmux inside tmux.",
+    "Attach to a running workspace by name. Tmux switches clients instead of nesting tmux inside tmux, while zellij attaches to the named session directly.",
   options: [],
   positionals: [
     { name: "workspace", description: "Workspace name", required: true },
@@ -159,7 +163,7 @@ const execSpec = defineCommand({
   summary: "Send a command to a running workspace",
   group: "Project",
   description:
-    "Queue a command in the workspace's active pane without opening a new shell. This is useful for long-running agents, background checks, or remote follow-up work.",
+    "Queue a command in the workspace without opening a new interactive attach flow. Tmux sends it to the active pane; zellij opens a new pane for the command. This is useful for long-running agents, background checks, or remote follow-up work.",
   options: [],
   positionals: [
     { name: "workspace", description: "Workspace name", required: true },
@@ -260,17 +264,17 @@ function shortenPathForDisplay(opts: {
 }
 
 function buildSessionPickerOptions(opts: {
-  readonly sessions: readonly TmuxSession[];
+  readonly sessions: readonly MuxSession[];
   readonly projects: readonly RegisteredProject[];
   readonly home: string;
 }): SessionPickerOption[] {
   const options: SessionPickerOption[] = [];
 
-  for (const session of opts.sessions.filter((s) => s.attached)) {
+  for (const session of opts.sessions.filter((s) => s.attached === true)) {
     options.push({
       value: `session:${session.name}`,
       label: session.name,
-      hint: `attached${
+      hint: `${session.backend} attached${
         session.path
           ? ` • ${shortenPathForDisplay({ path: session.path, home: opts.home })}`
           : ""
@@ -278,13 +282,13 @@ function buildSessionPickerOptions(opts: {
     });
   }
 
-  for (const session of opts.sessions.filter((s) => !s.attached)) {
+  for (const session of opts.sessions.filter((s) => s.attached !== true)) {
     options.push({
       value: `session:${session.name}`,
       label: session.name,
       hint: session.path
-        ? shortenPathForDisplay({ path: session.path, home: opts.home })
-        : "detached",
+        ? `${session.backend} • ${shortenPathForDisplay({ path: session.path, home: opts.home })}`
+        : session.backend,
     });
   }
 
@@ -331,12 +335,17 @@ async function promptAttachedWorkspaceAction(opts: {
 
 async function handleSelectedSession(opts: {
   readonly name: string;
-  readonly sessions: readonly TmuxSession[];
+  readonly sessions: readonly MuxSession[];
   readonly projects: readonly RegisteredProject[];
 }): Promise<number> {
   const session = opts.sessions.find((s) => s.name === opts.name);
-  if (!session?.attached) {
-    return await attachToSession(opts.name);
+  if (!session) {
+    p.log.error(`Workspace not found: ${opts.name}`);
+    return 1;
+  }
+
+  if (session.attached !== true) {
+    return await attachToSession(session);
   }
 
   const baseName = resolveWorkspaceBaseName({ workspaceName: opts.name });
@@ -352,13 +361,28 @@ async function handleSelectedSession(opts: {
     return 0;
   }
   if (action !== "new") {
-    return await attachToSession(opts.name);
+    return await attachToSession(session);
   }
 
   const project = opts.projects.find(
     (proj: RegisteredProject) => proj.name === baseName
   );
+  const projectContext = project
+    ? await findProjectContext(project.repoRoot)
+    : await resolveCurrentProjectContext();
+  const resolvedBackend = await resolveWorkspaceBackendForCreate({
+    project: projectContext,
+    fallback: session.backend,
+  });
+  if (!resolvedBackend) {
+    logger.error({
+      message:
+        "No session mux backend available. Install tmux or zellij, or set sessions.mux to auto|tmux|zellij.",
+    });
+    return 1;
+  }
   return await createAndAttachSession({
+    backend: resolvedBackend.backend,
     name: nextWorkspaceName,
     cwd: project?.repoRoot ?? session.path ?? process.cwd(),
   });
@@ -376,7 +400,20 @@ async function handleSelectedProject(opts: {
     return 1;
   }
 
+  const projectContext = await findProjectContext(project.repoRoot);
+  const resolvedBackend = await resolveWorkspaceBackendForCreate({
+    project: projectContext,
+  });
+  if (!resolvedBackend) {
+    logger.error({
+      message:
+        "No session mux backend available. Install tmux or zellij, or set sessions.mux to auto|tmux|zellij.",
+    });
+    return 1;
+  }
+
   return await createAndAttachSession({
+    backend: resolvedBackend.backend,
     name: project.name,
     cwd: project.repoRoot,
   });
@@ -416,6 +453,7 @@ async function resolveSessionNameForStart(opts: {
   readonly baseName: string;
   readonly forceNew: boolean;
   readonly customName: string | undefined;
+  readonly project: ProjectContext | null;
 }): Promise<string> {
   if (opts.customName) {
     return buildSessionName({ base: opts.baseName, suffix: opts.customName });
@@ -425,7 +463,7 @@ async function resolveSessionNameForStart(opts: {
     return opts.baseName;
   }
 
-  const sessions = await listTmuxSessions();
+  const sessions = await listWorkspaceSessions({ project: opts.project });
   const nextSuffix = getNextNumericSessionSuffix({
     sessions,
     base: opts.baseName,
@@ -439,6 +477,7 @@ async function resolveSessionNameForStart(opts: {
 async function maybeReuseExistingWorkspace(opts: {
   readonly baseName: string;
   readonly project: RegisteredProject;
+  readonly projectContext: ProjectContext | null;
   readonly detach: boolean;
   readonly runUp: boolean;
   readonly forceNew: boolean;
@@ -448,7 +487,9 @@ async function maybeReuseExistingWorkspace(opts: {
     return null;
   }
 
-  const sessions = await listTmuxSessions();
+  const sessions = await listWorkspaceSessions({
+    project: opts.projectContext,
+  });
   const existing = sessions.find((s) => s.name === opts.baseName);
   if (!existing) {
     return null;
@@ -470,7 +511,104 @@ async function maybeReuseExistingWorkspace(opts: {
     return 0;
   }
 
-  return await attachToSession(opts.baseName);
+  return await attachToSession(existing);
+}
+
+async function resolveCurrentProjectContext(): Promise<ProjectContext | null> {
+  return await findProjectContext(process.cwd());
+}
+
+async function listWorkspaceSessions(opts: {
+  readonly project: ProjectContext | null;
+}): Promise<readonly MuxSession[]> {
+  const mux = await resolveMux({ project: opts.project });
+  return await listMuxSessions({
+    mode: mux.mode,
+    backends: mux.backends,
+  });
+}
+
+async function resolveWorkspaceBackendForCreate(opts: {
+  readonly project: ProjectContext | null;
+  readonly fallback?: MuxBackendName;
+}): Promise<{
+  readonly backendName: MuxBackendName;
+  readonly backend: MuxBackend;
+} | null> {
+  const mux = await resolveMux({ project: opts.project });
+  const backendName =
+    resolveDefaultBackendName({
+      mode: mux.mode,
+      backends: mux.backends,
+    }) ??
+    opts.fallback ??
+    null;
+  if (!backendName) {
+    return null;
+  }
+  const backend = mux.backends.get(backendName);
+  if (!backend?.available) {
+    return null;
+  }
+  return { backendName, backend };
+}
+
+function resolveWorkspaceBackendName(opts: {
+  readonly workspaceName: string;
+  readonly sessions: readonly MuxSession[];
+}): MuxBackendName | null {
+  return (
+    opts.sessions.find((session) => session.name === opts.workspaceName)
+      ?.backend ?? null
+  );
+}
+
+function resolveTmuxOnlyWorkspaceError(opts: {
+  readonly workspaceName: string;
+  readonly sessions: readonly MuxSession[];
+}): string {
+  const backendName = resolveWorkspaceBackendName(opts);
+  if (backendName === "zellij") {
+    return `Workspace '${opts.workspaceName}' is running in zellij. Pane inspection is tmux-only.`;
+  }
+  return `Workspace '${opts.workspaceName}' does not support tmux-only pane inspection.`;
+}
+
+async function resolveRequiredWorkspaceSession(opts: {
+  readonly workspaceName: string;
+}): Promise<MuxSession | null> {
+  const projectContext = await resolveCurrentProjectContext();
+  const sessions = await listWorkspaceSessions({ project: projectContext });
+  const session =
+    sessions.find((candidate) => candidate.name === opts.workspaceName) ?? null;
+  if (!session) {
+    logger.error({ message: `Workspace not found: ${opts.workspaceName}` });
+    return null;
+  }
+  return session;
+}
+
+async function requireTmuxWorkspaceSession(opts: {
+  readonly workspaceName: string;
+}): Promise<MuxSession | null> {
+  const projectContext = await resolveCurrentProjectContext();
+  const sessions = await listWorkspaceSessions({ project: projectContext });
+  const session =
+    sessions.find((candidate) => candidate.name === opts.workspaceName) ?? null;
+  if (!session) {
+    logger.error({ message: `Workspace not found: ${opts.workspaceName}` });
+    return null;
+  }
+  if (session.backend !== "tmux") {
+    logger.error({
+      message: resolveTmuxOnlyWorkspaceError({
+        workspaceName: opts.workspaceName,
+        sessions,
+      }),
+    });
+    return null;
+  }
+  return session;
 }
 
 function ensureStreamOutputMode(opts: {
@@ -594,7 +732,8 @@ async function streamTailOutput(opts: {
  * Uses clack prompts with grouped options for sessions and projects.
  */
 async function handleSessionPicker(): Promise<number> {
-  const sessions = await listTmuxSessions();
+  const projectContext = await resolveCurrentProjectContext();
+  const sessions = await listWorkspaceSessions({ project: projectContext });
   p.intro("Workspaces");
   const projects = (await readProjectsRegistry()).projects;
   const options = buildSessionPickerOptions({
@@ -645,7 +784,7 @@ function resolveWorkspaceBaseName(opts: {
 
 function resolveNextIsolatedWorkspaceName(opts: {
   readonly workspaceName: string;
-  readonly sessions: readonly TmuxSession[];
+  readonly sessions: readonly Pick<MuxSession, "name">[];
 }): string {
   const baseName = resolveWorkspaceBaseName({
     workspaceName: opts.workspaceName,
@@ -679,17 +818,18 @@ function resolveRunUpCwd(opts: {
 const handleList: CommandHandlerFor<
   typeof listSpec
 > = async (): Promise<number> => {
-  const sessions = await listTmuxSessions();
+  const projectContext = await resolveCurrentProjectContext();
+  const sessions = await listWorkspaceSessions({ project: projectContext });
   const registry = await readProjectsRegistry();
   const projects = registry.projects;
 
   if (sessions.length === 0) {
-    logger.info({ message: "No active tmux workspaces" });
+    logger.info({ message: "No active workspaces" });
     return 0;
   }
 
   console.log(
-    `${"Workspace".padEnd(20) + "Project".padEnd(20) + "Node".padEnd(10)}Status`
+    `${"Workspace".padEnd(20) + "Project".padEnd(20) + "Backend".padEnd(10)}Status`
   );
   console.log("-".repeat(60));
 
@@ -698,11 +838,11 @@ const handleList: CommandHandlerFor<
       workspaceName: session.name,
       projects,
     });
-    const status = session.attached ? "attached" : "detached";
+    const status = session.attached === true ? "attached" : "detached";
     console.log(
       session.name.padEnd(20) +
         projectName.padEnd(20) +
-        "local".padEnd(10) +
+        session.backend.padEnd(10) +
         status
     );
   }
@@ -735,9 +875,11 @@ const handleStart = async ({
   }
 
   const baseName = project.name;
+  const projectContext = await findProjectContext(project.repoRoot);
   const reused = await maybeReuseExistingWorkspace({
     baseName,
     project,
+    projectContext,
     detach,
     runUp,
     forceNew,
@@ -751,8 +893,20 @@ const handleStart = async ({
     baseName,
     forceNew,
     customName,
+    project: projectContext,
   });
 
+  const resolvedBackend = await resolveWorkspaceBackendForCreate({
+    project: projectContext,
+  });
+  if (!resolvedBackend) {
+    logger.error({
+      message:
+        "No session mux backend available. Install tmux or zellij, or set sessions.mux to auto|tmux|zellij.",
+    });
+    return 1;
+  }
+
   // Run hack up if requested
   if (runUp) {
     await runHackUp(resolveRunUpCwd({ project }));
@@ -761,11 +915,13 @@ const handleStart = async ({
   // Use repoRoot (project root), not projectDir (.hack/)
   if (detach) {
     return await createSessionDetached({
+      backend: resolvedBackend.backend,
       name: sessionName,
       cwd: project.repoRoot,
     });
   }
   return await createAndAttachSession({
+    backend: resolvedBackend.backend,
     name: sessionName,
     cwd: project.repoRoot,
   });
@@ -778,10 +934,21 @@ const handleStop = async ({
   readonly args: StopArgs;
 }): Promise<number> => {
   const workspaceName = args.positionals.workspace;
+  const session = await resolveRequiredWorkspaceSession({ workspaceName });
+  if (!session) {
+    return 1;
+  }
 
-  const result = await exec(["tmux", "kill-session", "-t", workspaceName], {
-    stdin: "ignore",
+  const mux = await resolveMux({
+    project: await resolveCurrentProjectContext(),
   });
+  const backend = mux.backends.get(session.backend);
+  if (!backend?.available) {
+    logger.error({ message: `Backend unavailable: ${session.backend}` });
+    return 1;
+  }
+
+  const result = await backend.killSession({ name: workspaceName });
   if (result.exitCode !== 0) {
     logger.error({ message: `Failed to stop workspace: ${workspaceName}` });
     return 1;
@@ -798,7 +965,11 @@ const handleAttach = async ({
   readonly args: AttachArgs;
 }): Promise<number> => {
   const workspaceName = args.positionals.workspace;
-  return await attachToSession(workspaceName);
+  const session = await resolveRequiredWorkspaceSession({ workspaceName });
+  if (!session) {
+    return 1;
+  }
+  return await attachToSession(session);
 };
 
 const handleExec = async ({
@@ -809,13 +980,24 @@ const handleExec = async ({
 }): Promise<number> => {
   const workspaceName = args.positionals.workspace;
   const command = args.positionals.command;
+  const session = await resolveRequiredWorkspaceSession({ workspaceName });
+  if (!session) {
+    return 1;
+  }
 
-  const result = await exec(
-    ["tmux", "send-keys", "-t", workspaceName, command, "Enter"],
-    {
-      stdin: "ignore",
-    }
-  );
+  const mux = await resolveMux({
+    project: await resolveCurrentProjectContext(),
+  });
+  const backend = mux.backends.get(session.backend);
+  if (!backend?.available) {
+    logger.error({ message: `Backend unavailable: ${session.backend}` });
+    return 1;
+  }
+
+  const result = await backend.execInSession({
+    name: workspaceName,
+    command,
+  });
 
   if (result.exitCode !== 0) {
     logger.error({
@@ -845,13 +1027,20 @@ const handlePanes = async ({
 
   const context = { session: sessionName };
 
+  const tmuxSession = await requireTmuxWorkspaceSession({
+    workspaceName: sessionName,
+  });
+  if (!tmuxSession) {
+    return 1;
+  }
+
   if (json) {
     writeSessionStreamEvent({
       event: buildSessionPanesStartEvent({ context }),
     });
   }
 
-  const result = await listTmuxPanes(sessionName);
+  const result = await listTmuxPanes(tmuxSession.name);
   if (result.exitCode !== 0) {
     const message = result.stderr || `Failed to list panes for ${sessionName}`;
     if (json) {
@@ -894,8 +1083,14 @@ const handleCapture = async ({
   readonly args: CaptureArgs;
 }): Promise<number> => {
   const sessionName = args.positionals.workspace;
+  const tmuxSession = await requireTmuxWorkspaceSession({
+    workspaceName: sessionName,
+  });
+  if (!tmuxSession) {
+    return 1;
+  }
   const target =
-    args.options.target ?? (await resolveActiveTarget(sessionName));
+    args.options.target ?? (await resolveActiveTarget(tmuxSession.name));
   const lines = args.options.lines ?? 200;
   const pretty = args.options.pretty === true;
   const json = args.options.json === true || !pretty;
@@ -956,8 +1151,14 @@ const handleTail = async ({
   readonly args: TailArgs;
 }): Promise<number> => {
   const sessionName = args.positionals.workspace;
+  const tmuxSession = await requireTmuxWorkspaceSession({
+    workspaceName: sessionName,
+  });
+  if (!tmuxSession) {
+    return 1;
+  }
   const target =
-    args.options.target ?? (await resolveActiveTarget(sessionName));
+    args.options.target ?? (await resolveActiveTarget(tmuxSession.name));
   const lines = args.options.lines ?? 200;
   const intervalMs = args.options.intervalMs ?? 500;
   const maxMs = args.options.maxMs ?? 5000;
@@ -1106,93 +1307,13 @@ function delay(ms: number): Promise<void> {
   });
 }
 
-/**
- * List all tmux sessions.
- */
-async function listTmuxSessions(): Promise<TmuxSession[]> {
-  const separator = "|||HACK_SESSION_FIELD|||";
-  const format = [
-    "#{session_name}",
-    "#{session_attached}",
-    "#{session_path}",
-  ].join(separator);
-  const result = await exec(["tmux", "list-sessions", "-F", format], {
-    stdin: "ignore",
-  });
-
-  if (result.exitCode !== 0) {
-    return [];
-  }
-
-  const sessions: TmuxSession[] = [];
-  for (const line of result.stdout.split("\n")) {
-    if (!line.trim()) {
-      continue;
-    }
-    const fields = parseTmuxSessionFields(line, separator, 3);
-    if (!fields) {
-      continue;
-    }
-    const [name, attached, path] = fields;
-    if (name) {
-      sessions.push({
-        name,
-        attached: attached === "1",
-        path: path || null,
-      });
-    }
-  }
-
-  return sessions;
-}
-
-function parseTmuxSessionFields(
-  line: string,
-  separator: string,
-  expectedCount: number
-): readonly string[] | null {
-  const bySeparator = line.split(separator);
-  if (bySeparator.length === expectedCount) {
-    return bySeparator;
-  }
-  const byTab = line.split("\t");
-  if (byTab.length === expectedCount) {
-    return byTab;
-  }
-  return null;
-}
-
-/**
- * Attach to or switch to an existing tmux session.
- * Uses switch-client when already inside tmux to avoid nesting.
- * Uses -d to detach other clients (avoids size conflicts from different terminals).
- */
-async function attachToSession(name: string): Promise<number> {
-  const insideTmux = Boolean(process.env.TMUX);
-
-  if (insideTmux) {
-    // Already in tmux - switch to the session instead of nesting
-    const exitCode = await run(["tmux", "switch-client", "-t", name], {
-      stdin: "inherit",
-    });
-    return exitCode;
-  }
-
-  // Outside tmux - attach with -d to detach other clients
-  const exitCode = await run(["tmux", "attach", "-d", "-t", name], {
-    stdin: "inherit",
-  });
-  return exitCode;
-}
-
-/**
- * Create a new tmux session and attach/switch to it.
- */
 async function createAndAttachSession(opts: {
+  readonly backend: MuxBackend;
   readonly name: string;
   readonly cwd: string;
 }): Promise<number> {
   const createExitCode = await createSessionDetached({
+    backend: opts.backend,
     name: opts.name,
     cwd: opts.cwd,
   });
@@ -1201,20 +1322,22 @@ async function createAndAttachSession(opts: {
     return createExitCode;
   }
 
-  // Switch or attach depending on context (attachToSession handles this)
-  return await attachToSession(opts.name);
+  return await attachToSession({
+    backend: opts.backend.name,
+    name: opts.name,
+  });
 }
 
 async function createSessionDetached(opts: {
+  readonly backend: MuxBackend;
   readonly name: string;
   readonly cwd: string;
 }): Promise<number> {
-  const createResult = await exec(
-    ["tmux", "new-session", "-d", "-s", opts.name, "-c", opts.cwd],
-    { stdin: "ignore" }
-  );
-
-  if (createResult.exitCode !== 0) {
+  const createResult = await opts.backend.createSession({
+    name: opts.name,
+    cwd: opts.cwd,
+  });
+  if (!createResult.ok) {
     logger.error({ message: `Failed to create workspace: ${opts.name}` });
     return 1;
   }
@@ -1223,6 +1346,23 @@ async function createSessionDetached(opts: {
   return 0;
 }
 
+async function attachToSession(opts: {
+  readonly backend: MuxBackendName;
+  readonly name: string;
+}): Promise<number> {
+  if (opts.backend === "zellij") {
+    return await attachZellijSession({
+      name: opts.name,
+      createIfMissing: false,
+      run,
+    });
+  }
+  return await attachTmuxSession({
+    name: opts.name,
+    run,
+  });
+}
+
 /**
  * Run hack up -d in a project directory.
  */
@@ -1233,6 +1373,8 @@ async function runHackUp(projectPath: string): Promise<void> {
 
 export const __testOnlySessionCommand = {
   resolveNextIsolatedWorkspaceName,
+  resolveTmuxOnlyWorkspaceError,
   resolveRunUpCwd,
+  resolveWorkspaceBackendName,
   resolveWorkspaceProjectName,
 };
diff --git a/tests/session-command.test.ts b/tests/session-command.test.ts
index cdba2e6f8..ba6dff7da 100644
--- a/tests/session-command.test.ts
+++ b/tests/session-command.test.ts
@@ -61,3 +61,39 @@ test("resolveRunUpCwd uses the repo root instead of the .hack directory", () =>
     })
   ).toBe("/tmp/alpha");
 });
+
+test("resolveWorkspaceBackendName detects zellij-backed workspaces", () => {
+  expect(
+    __testOnlySessionCommand.resolveWorkspaceBackendName({
+      workspaceName: "alpha--agent-1",
+      sessions: [
+        {
+          backend: "zellij",
+          name: "alpha--agent-1",
+          attached: null,
+          path: null,
+          windows: null,
+          createdAt: null,
+        },
+      ],
+    })
+  ).toBe("zellij");
+});
+
+test("resolveTmuxOnlyWorkspaceError explains tmux-only pane tooling on zellij", () => {
+  expect(
+    __testOnlySessionCommand.resolveTmuxOnlyWorkspaceError({
+      workspaceName: "alpha--agent-1",
+      sessions: [
+        {
+          backend: "zellij",
+          name: "alpha--agent-1",
+          attached: null,
+          path: null,
+          windows: null,
+          createdAt: null,
+        },
+      ],
+    })
+  ).toContain("tmux-only");
+});
diff --git a/tests/session-help.test.ts b/tests/session-help.test.ts
index d7a520b25..bd176de91 100644
--- a/tests/session-help.test.ts
+++ b/tests/session-help.test.ts
@@ -25,9 +25,10 @@ test("hack session attach and exec help explain workspace-oriented flows", () =>
   const attachHelp = renderHelpMarkdownForPath(CLI_SPEC, ["session", "attach"]);
   const execHelp = renderHelpMarkdownForPath(CLI_SPEC, ["session", "exec"]);
 
-  expect(attachHelp).toContain("Attach to a running tmux workspace by name");
-  expect(attachHelp).toContain("switches clients instead of nesting");
-  expect(execHelp).toContain("Queue a command in the workspace's active pane");
+  expect(attachHelp).toContain("Attach to a running workspace by name");
+  expect(attachHelp).toContain("zellij attaches to the named session directly");
+  expect(execHelp).toContain("Queue a command in the workspace");
+  expect(execHelp).toContain("zellij opens a new pane");
   expect(execHelp).toContain("long-running agents");
 });
 

From 51c5295a95a695fd65f6ec9031bb1c5d1ea7d633 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:24:54 +0000
Subject: [PATCH 067/134] HACK-468: checkpoint merge prep

---
 docs/cli.md                                   |  2 +-
 .../auth-broker/src/modules/orgs/plugin.ts    |  4 +-
 .../auth-broker/src/modules/orgs/service.ts   | 80 ++++++++++++++++++-
 src/commands/org.ts                           |  2 +-
 4 files changed, 82 insertions(+), 6 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 763f31f44..5a3dffead 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -318,7 +318,7 @@ Lifecycle semantics:
 - `invite` creates `pending`
 - `add` creates `active`
 - `remove` transitions `pending` or `active` membership to `removed`
-- Current behavior removes only the org-level membership record; preview-and-cascade admin UX is tracked separately
+- Removing org access also transitions matching team memberships and team invites in that organization to `removed`
 
 #### hack org member list
 
diff --git a/services/auth-broker/src/modules/orgs/plugin.ts b/services/auth-broker/src/modules/orgs/plugin.ts
index e44a67ffb..06a6ad69c 100644
--- a/services/auth-broker/src/modules/orgs/plugin.ts
+++ b/services/auth-broker/src/modules/orgs/plugin.ts
@@ -602,7 +602,7 @@ function normalizeOptionalString(value: unknown): string | null {
 
 function normalizeState(input: {
   readonly value: string | undefined;
-}): MembershipState | "all" {
+}): MembershipState | "all" | "actionable" {
   const normalized = normalizeOptionalString(input.value);
   if (
     normalized === "pending" ||
@@ -612,7 +612,7 @@ function normalizeState(input: {
   ) {
     return normalized;
   }
-  return "all";
+  return "actionable";
 }
 
 async function hasActiveParentOrgMembership(input: {
diff --git a/services/auth-broker/src/modules/orgs/service.ts b/services/auth-broker/src/modules/orgs/service.ts
index 5993cd250..20f0522a2 100644
--- a/services/auth-broker/src/modules/orgs/service.ts
+++ b/services/auth-broker/src/modules/orgs/service.ts
@@ -86,7 +86,7 @@ export type OrgTeamsStore = {
     readonly scope: "organization" | "team";
     readonly orgKey: string;
     readonly teamKey?: string | null;
-    readonly state: MembershipState | "all";
+    readonly state: MembershipState | "all" | "actionable";
   }) => MaybePromise<readonly MembershipRecord[]>;
   readonly inviteMember: (input: {
     readonly scope: "organization" | "team";
@@ -279,7 +279,7 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
     readonly scope: "organization" | "team";
     readonly orgKey: string;
     readonly teamKey?: string | null;
-    readonly state: MembershipState | "all";
+    readonly state: MembershipState | "all" | "actionable";
   }): MaybePromise<readonly MembershipRecord[]> {
     const organization = this.findOrganization({ orgKey: input.orgKey });
     if (!organization) {
@@ -319,6 +319,9 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
     if (input.state === "removed") {
       return removed;
     }
+    if (input.state === "actionable") {
+      return [...pending, ...active];
+    }
     return [...pending, ...active, ...removed];
   }
 
@@ -430,6 +433,12 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
           target: invitation.email,
         });
         this.removedMemberships.set(membership.id, membership);
+        if (input.scope === "organization") {
+          this.cascadeRemovedOrganizationTarget({
+            organizationId: organization.id,
+            target: normalizedTarget,
+          });
+        }
         return membership;
       }
     }
@@ -451,6 +460,12 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
           target: membership.target,
         });
         this.removedMemberships.set(removed.id, removed);
+        if (input.scope === "organization") {
+          this.cascadeRemovedOrganizationTarget({
+            organizationId: organization.id,
+            target: normalizedTarget,
+          });
+        }
         return removed;
       }
     }
@@ -620,4 +635,65 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
       updatedAt: now,
     };
   }
+
+  private cascadeRemovedOrganizationTarget(input: {
+    readonly organizationId: string;
+    readonly target: string;
+  }): void {
+    const normalizedTarget = input.target.trim();
+
+    for (const invitation of this.invitations.values()) {
+      if (
+        invitation.status !== "pending" ||
+        invitation.scope !== "team" ||
+        invitation.organizationId !== input.organizationId ||
+        invitation.email !== normalizedTarget
+      ) {
+        continue;
+      }
+
+      this.invitations.set(invitation.id, {
+        ...invitation,
+        status: "removed",
+        updatedAt: new Date().toISOString(),
+      });
+      const removed = this.toRemovedMembership({
+        scope: invitation.scope,
+        organizationId: invitation.organizationId,
+        teamId: invitation.teamId,
+        userId: null,
+        email: invitation.email,
+        target: invitation.email,
+      });
+      this.removedMemberships.set(removed.id, removed);
+    }
+
+    for (const [key, membership] of this.activeMemberships.entries()) {
+      if (
+        membership.scope !== "team" ||
+        membership.organizationId !== input.organizationId
+      ) {
+        continue;
+      }
+
+      const membershipEmail = membership.email?.trim() ?? "";
+      if (
+        membership.target !== normalizedTarget &&
+        membershipEmail !== normalizedTarget
+      ) {
+        continue;
+      }
+
+      this.activeMemberships.delete(key);
+      const removed = this.toRemovedMembership({
+        scope: membership.scope,
+        organizationId: membership.organizationId,
+        teamId: membership.teamId,
+        userId: membership.userId,
+        email: membership.email,
+        target: membership.target,
+      });
+      this.removedMemberships.set(removed.id, removed);
+    }
+  }
 }
diff --git a/src/commands/org.ts b/src/commands/org.ts
index b7ba814e7..41eb6acfe 100644
--- a/src/commands/org.ts
+++ b/src/commands/org.ts
@@ -109,7 +109,7 @@ const memberRemoveSpec = defineCommand({
   name: "remove",
   summary: "Remove org membership or cancel a pending org invite",
   description:
-    "Admin-side revoke verb. Current behavior removes only the org-level membership record; preview-and-cascade admin UX is tracked separately.",
+    "Admin-side revoke verb. Removing org access also removes matching team memberships and invites in that organization.",
   group: "Global",
   options: [optJson, optBrokerUrl] as const,
   positionals: orgMemberTargetPositionals,

From 7f5581a5d94fdc3b4e9d50ade807f56dc719eaac Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:26:50 +0000
Subject: [PATCH 068/134] docs(tickets): add normalized sync implementation
 plan

---
 ...kets-normalized-sync-idempotency-design.md |   1 +
 ...ickets-normalized-sync-idempotency-plan.md | 465 ++++++++++++++++++
 2 files changed, 466 insertions(+)
 create mode 100644 docs/plans/2026-03-14-tickets-normalized-sync-idempotency-plan.md

diff --git a/docs/plans/2026-03-14-tickets-normalized-sync-idempotency-design.md b/docs/plans/2026-03-14-tickets-normalized-sync-idempotency-design.md
index 0b03d942b..6ef60915d 100644
--- a/docs/plans/2026-03-14-tickets-normalized-sync-idempotency-design.md
+++ b/docs/plans/2026-03-14-tickets-normalized-sync-idempotency-design.md
@@ -278,6 +278,7 @@ When available, providers should also persist the specific remote field scope th
 
 This design implies follow-up changes in the normalized sync core:
 
+- The execution plan for those changes lives in `docs/plans/2026-03-14-tickets-normalized-sync-idempotency-plan.md`.
 - external sync helpers must accept caller-provided stable ids instead of always generating random UUIDs
 - checkpoint and conflict events should persist `operationKey` and baseline metadata
 - conflict dedupe should move from ad hoc field/value matching to deterministic conflict keys
diff --git a/docs/plans/2026-03-14-tickets-normalized-sync-idempotency-plan.md b/docs/plans/2026-03-14-tickets-normalized-sync-idempotency-plan.md
new file mode 100644
index 000000000..443a3203b
--- /dev/null
+++ b/docs/plans/2026-03-14-tickets-normalized-sync-idempotency-plan.md
@@ -0,0 +1,465 @@
+# Tickets Normalized Sync Idempotency Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Implement deterministic external sync identity, explicit checkpoint-based conflict handling, and idempotent conflict resolution for normalized ticket sync.
+
+**Architecture:** Extend the tickets store so external sync writers can supply stable operation-derived ids and metadata, then move the Linear adapter onto that contract. Keep transport-level merge dedupe by `eventId`, but make external sync events and conflicts deterministic so multi-machine replay converges without duplicate checkpoints or silent overwrites.
+
+**Tech Stack:** Bun, TypeScript, git-backed tickets event log, Linear sync adapter tests, Bun test
+
+---
+
+### Task 1: Add deterministic sync event metadata to the tickets store
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Test: `tests/tickets-store.test.ts`
+
+**Step 1: Write the failing store test**
+
+Add a store-level test next to `tickets store materializes assignee, review notes, comments, checkpoints, and conflicts` that records the same logical checkpoint twice with stable metadata and expects one logical result after materialization.
+
+```ts
+test("recordSyncCheckpoint reuses deterministic ids for the same external operation", async () => {
+  const checkpointA = await store.recordSyncCheckpoint({
+    ticketId,
+    provider: "linear",
+    profileId: "default",
+    operationKey: "linear:default:issue:ENG-123:update:v5:title",
+    checkpointId: "checkpoint-linear-eng-123-v5-title",
+    eventId: "event-linear-eng-123-v5-title-checkpoint",
+    externalEntityId: "issue-1",
+    externalVersion: "v5",
+    baselineCheckpointId: "checkpoint-linear-eng-123-v4-title",
+    direction: "linear_to_hack",
+    remoteCursor: "ENG-123"
+  })
+
+  const checkpointB = await store.recordSyncCheckpoint({
+    ticketId,
+    provider: "linear",
+    profileId: "default",
+    operationKey: "linear:default:issue:ENG-123:update:v5:title",
+    checkpointId: "checkpoint-linear-eng-123-v5-title",
+    eventId: "event-linear-eng-123-v5-title-checkpoint",
+    externalEntityId: "issue-1",
+    externalVersion: "v5",
+    baselineCheckpointId: "checkpoint-linear-eng-123-v4-title",
+    direction: "linear_to_hack",
+    remoteCursor: "ENG-123"
+  })
+
+  expect(checkpointA.ok).toBe(true)
+  expect(checkpointB.ok).toBe(true)
+})
+```
+
+**Step 2: Run the focused store test to verify it fails**
+
+Run: `bun test tests/tickets-store.test.ts`
+
+Expected: a type or assertion failure because `recordSyncCheckpoint` does not yet accept stable ids or persist normalized sync metadata.
+
+**Step 3: Implement deterministic checkpoint/conflict metadata plumbing**
+
+Update `TicketSyncCheckpoint`, `TicketSyncConflict`, and the write helpers in `store.ts` so external sync calls can pass stable ids and metadata instead of always generating random ids.
+
+```ts
+type TicketSyncCheckpoint = {
+  readonly checkpointId: string
+  readonly ticketId: string
+  readonly provider: string
+  readonly profileId?: string
+  readonly operationKey?: string
+  readonly externalEntityId?: string
+  readonly externalVersion?: string
+  readonly baselineCheckpointId?: string
+  readonly authority?: string
+  readonly origin?: string
+  readonly direction?: string
+  readonly remoteCursor?: string
+  readonly remoteUpdatedAt?: string
+  readonly localUpdatedAt?: string
+  readonly actor: string
+  readonly createdAt: string
+}
+
+type TicketEventInput = {
+  readonly ticketId: string
+  readonly type: string
+  readonly payload: Record<string, unknown>
+  readonly actor?: string
+  readonly eventId?: string
+}
+```
+
+Use the caller-provided `eventId` when present, and fall back to `randomUUID()` only for local-only ticket events.
+
+**Step 4: Extend sync conflict writes and fold materialization**
+
+Teach `recordSyncConflict`, `resolveSyncConflict`, `applyTicketSyncCheckpointRecordedEvent`, `applyTicketSyncConflictRecordedEvent`, and `applyTicketSyncConflictResolvedEvent` to persist and materialize:
+
+- `operationKey`
+- `conflictKey`
+- `externalEntityId`
+- `externalVersion`
+- `baselineCheckpointId`
+- `authority`
+- `origin`
+
+Use stable ids from the caller when provided, and keep fallback generation for older local call sites.
+
+**Step 5: Run the store test suite again**
+
+Run: `bun test tests/tickets-store.test.ts`
+
+Expected: the new deterministic-id test passes and existing sync metadata tests still pass.
+
+**Step 6: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/store.ts tests/tickets-store.test.ts
+git commit -m "feat(tickets): add deterministic sync event metadata"
+```
+
+### Task 2: Make sync conflicts and resolutions idempotent in the store
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Test: `tests/tickets-store.test.ts`
+
+**Step 1: Write failing tests for duplicate conflict and duplicate resolution replay**
+
+Add tests that record the same `conflictKey` twice and resolve the same conflict twice with the same deterministic resolution event id.
+
+```ts
+test("recordSyncConflict collapses repeated conflictKey replays", async () => {
+  const first = await store.recordSyncConflict({
+    ticketId,
+    provider: "linear",
+    field: "title",
+    conflictKey: 'linear|T-00001|title|checkpoint-4|"Local"|"Remote"',
+    conflictId: "conflict-linear-title-checkpoint-4",
+    eventId: "event-linear-title-checkpoint-4-conflict",
+    baselineCheckpointId: "checkpoint-4",
+    operationKey: "linear:default:issue:ENG-123:update:v5:title",
+    localValue: "Local",
+    remoteValue: "Remote"
+  })
+
+  const second = await store.recordSyncConflict({
+    ticketId,
+    provider: "linear",
+    field: "title",
+    conflictKey: 'linear|T-00001|title|checkpoint-4|"Local"|"Remote"',
+    conflictId: "conflict-linear-title-checkpoint-4",
+    eventId: "event-linear-title-checkpoint-4-conflict",
+    baselineCheckpointId: "checkpoint-4",
+    operationKey: "linear:default:issue:ENG-123:update:v5:title",
+    localValue: "Local",
+    remoteValue: "Remote"
+  })
+
+  expect(first.ok).toBe(true)
+  expect(second.ok).toBe(true)
+})
+```
+
+**Step 2: Run the focused store tests to verify they fail**
+
+Run: `bun test tests/tickets-store.test.ts`
+
+Expected: duplicate conflict and duplicate resolution replay still produce duplicate materialized records or duplicate events.
+
+**Step 3: Implement idempotent conflict and resolution behavior**
+
+Change `recordSyncConflict` and `resolveSyncConflict` so they can no-op when the same deterministic event or the same open conflict already exists.
+
+```ts
+const existingOpenConflict = conflicts.find(
+  conflict => conflict.status === "open" && conflict.conflictKey === input.conflictKey
+)
+
+if (existingOpenConflict) {
+  return { ok: true, conflict: existingOpenConflict }
+}
+```
+
+For resolutions:
+
+- return success when the same conflict already has the same resolution
+- reject or ignore only when the replay attempts a different resolution for the same already-resolved conflict
+
+**Step 4: Preserve compatibility for old events**
+
+Keep the fold tolerant of older events that do not have `operationKey`, `conflictKey`, or `baselineCheckpointId`, but prefer the explicit keys when they exist.
+
+**Step 5: Run the store tests again**
+
+Run: `bun test tests/tickets-store.test.ts`
+
+Expected: the new idempotency tests pass along with the existing store coverage.
+
+**Step 6: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/store.ts tests/tickets-store.test.ts
+git commit -m "feat(tickets): make sync conflicts idempotent"
+```
+
+### Task 3: Move the Linear adapter onto checkpoint-based conflict decisions
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/linear/commands.ts`
+- Test: `tests/linear-commands.test.ts`
+
+**Step 1: Write failing Linear adapter tests**
+
+Add tests near `detectAuthoritativeFieldConflicts reports divergence for hack-owned tickets` and the sync direction tests that cover:
+
+- repeated application of the same remote change derives the same ids
+- two-sided divergence uses the last checkpoint baseline instead of raw current-vs-remote comparison
+- repeated sync of the same conflict only records one conflict
+
+```ts
+test("recordAuthoritativeConflicts reuses conflictKey for repeated Linear divergence", async () => {
+  const recorded = await __testOnly.recordAuthoritativeConflicts({
+    tickets,
+    ticketId: "T-00001",
+    conflicts: [
+      {
+        field: "title",
+        authority: "shared_manual",
+        operationKey: "linear:default:issue:ENG-123:update:v5:title",
+        conflictKey: 'linear|T-00001|title|checkpoint-4|"Local"|"Remote"',
+        baselineCheckpointId: "checkpoint-4",
+        localValue: "Local",
+        remoteValue: "Remote"
+      }
+    ]
+  })
+
+  expect(recorded.ok).toBe(true)
+  expect(recorded.recorded).toBe(1)
+})
+```
+
+**Step 2: Run the Linear test file to verify it fails**
+
+Run: `bun test tests/linear-commands.test.ts`
+
+Expected: the adapter tests fail because Linear sync still uses ad hoc field/value dedupe and does not derive deterministic operation metadata.
+
+**Step 3: Add normalized sync helpers in `linear/commands.ts`**
+
+Introduce small helpers for:
+
+- deriving `operationKey`
+- deriving deterministic checkpoint event ids
+- deriving deterministic `conflictKey`
+- reading the last relevant baseline checkpoint for a ticket/profile/field
+
+```ts
+function buildLinearOperationKey(input: {
+  readonly profileId: string
+  readonly issue: LinearIssue
+  readonly mutationKind: "linear_to_hack" | "hack_to_linear"
+  readonly field: string
+}): string {
+  return [
+    "linear",
+    input.profileId,
+    "issue",
+    input.issue.id,
+    input.mutationKind,
+    input.issue.updatedAt ?? input.issue.identifier,
+    input.field
+  ].join(":")
+}
+```
+
+Use these helpers inside `recordAuthoritativeConflicts`, `recordLinearSyncCheckpoint`, `syncTicketToLinearIssue`, `upsertTicketFromLinearIssue`, `applyLinearIssueToExistingTicket`, and `createTicketFromLinearIssueProjection`.
+
+**Step 4: Replace ad hoc conflict dedupe with normalized keys**
+
+Remove reliance on `buildConflictDedupKey` as the system contract. Instead:
+
+- compare against the last checkpoint baseline when deciding whether a change is remote-only, local-only, same-value, or divergent
+- pass `operationKey`, `conflictKey`, `baselineCheckpointId`, and deterministic ids into the tickets store
+
+Keep the current field scope conservative for this pass: `title`, `body`, `status`, and `project`.
+
+**Step 5: Re-run the Linear test file**
+
+Run: `bun test tests/linear-commands.test.ts`
+
+Expected: the new replay/baseline tests pass and the existing Linear sync tests still pass.
+
+**Step 6: Commit**
+
+```bash
+git add src/control-plane/extensions/linear/commands.ts tests/linear-commands.test.ts
+git commit -m "feat(linear): use normalized sync ids and baselines"
+```
+
+### Task 4: Expose the new sync metadata in ticket inspection surfaces
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/tickets/commands.ts`
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Test: `tests/tickets-store.test.ts`
+- Test: `tests/tickets-extension.test.ts`
+
+**Step 1: Write the failing surface tests**
+
+Extend the existing `tickets show json includes materialized sync metadata` coverage so the JSON payload includes the new metadata, and add a CLI assertion that the text table shows enough information to explain a checkpoint or conflict.
+
+```ts
+expect(payload.syncCheckpoints[0]).toMatchObject({
+  provider: "linear",
+  operationKey: "linear:default:issue:ENG-123:update:v5:title",
+  externalVersion: "v5",
+  baselineCheckpointId: "checkpoint-linear-eng-123-v4-title"
+})
+
+expect(payload.conflicts[0]).toMatchObject({
+  field: "title",
+  conflictKey: 'linear|T-00001|title|checkpoint-4|"Local"|"Remote"',
+  authority: "shared_manual"
+})
+```
+
+**Step 2: Run the tickets command tests to verify they fail**
+
+Run: `bun test tests/tickets-store.test.ts tests/tickets-extension.test.ts`
+
+Expected: the payload and CLI output do not yet expose the new metadata fields.
+
+**Step 3: Update the JSON and text surfaces**
+
+In `tickets/commands.ts`, extend the checkpoint and conflict tables so operators can see:
+
+- `operationKey`
+- `baselineCheckpointId`
+- `externalVersion`
+- `conflictKey`
+- `authority`
+
+Keep the JSON surface exhaustive and the text surface concise.
+
+**Step 4: Re-run the tickets command tests**
+
+Run: `bun test tests/tickets-store.test.ts tests/tickets-extension.test.ts`
+
+Expected: JSON output includes the new metadata and the CLI still renders correctly.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/commands.ts src/control-plane/extensions/tickets/store.ts tests/tickets-store.test.ts tests/tickets-extension.test.ts
+git commit -m "feat(tickets): expose normalized sync metadata"
+```
+
+### Task 5: Prove convergence with merge-level replay tests and run the focused validation suite
+
+**Files:**
+
+- Modify: `tests/tickets-git-channel.test.ts`
+- Test: `tests/tickets-store.test.ts`
+- Test: `tests/linear-commands.test.ts`
+- Test: `tests/tickets-extension.test.ts`
+- Test: `tests/tickets-git-channel.test.ts`
+
+**Step 1: Write the replay/convergence test**
+
+Add a merge-level test that simulates two machines appending the same deterministic external sync event ids and verifies that merged logs collapse to one logical operation.
+
+```ts
+test("mergeTicketEventLogs collapses repeated deterministic external sync events", () => {
+  const merged = __testOnly.mergeTicketEventLogs({
+    existing: [
+      JSON.stringify({
+        eventId: "event-linear-eng-123-v5-title-checkpoint",
+        ts: 10,
+        ticketId: "T-00001",
+        type: "ticket.sync_checkpoint_recorded"
+      }),
+      ""
+    ].join("\\n"),
+    incoming: [
+      JSON.stringify({
+        eventId: "event-linear-eng-123-v5-title-checkpoint",
+        ts: 10,
+        ticketId: "T-00001",
+        type: "ticket.sync_checkpoint_recorded"
+      }),
+      ""
+    ].join("\\n")
+  })
+
+  expect(merged.trim().split("\\n")).toHaveLength(1)
+})
+```
+
+**Step 2: Run the focused validation suite**
+
+Run:
+
+- `bun test tests/tickets-store.test.ts`
+- `bun test tests/linear-commands.test.ts`
+- `bun test tests/tickets-extension.test.ts`
+- `bun test tests/tickets-git-channel.test.ts`
+
+Expected: all focused sync and tickets tests pass.
+
+**Step 3: Run the repo-level quality gates for the touched area**
+
+Run:
+
+- `bun run test`
+- `bun run typecheck`
+- `bun run check`
+
+Expected: workspace tests, typechecking, and checks pass after the focused sync changes land.
+
+**Step 4: Commit**
+
+```bash
+git add tests/tickets-git-channel.test.ts
+git commit -m "test(tickets): cover normalized sync replay convergence"
+```
+
+### Task 6: Final review and handoff
+
+**Files:**
+
+- Review: `docs/plans/2026-03-14-tickets-normalized-sync-idempotency-design.md`
+- Review: `docs/plans/2026-03-14-tickets-normalized-sync-idempotency-plan.md`
+
+**Step 1: Verify the implementation against the design checklist**
+
+Confirm the final code satisfies:
+
+- deterministic `operationKey` and `eventId` reuse
+- baseline-aware conflict decisions
+- explicit authority handling
+- stable `conflictKey` and idempotent conflict resolution
+- operator-visible sync metadata
+
+**Step 2: Capture any remaining follow-up**
+
+If the implementation deliberately leaves out broader shared fields like `assignee` or dependency edges, file a follow-up ticket before ending the session.
+
+**Step 3: Prepare the branch for review**
+
+Run:
+
+- `git status --short`
+- `git log --oneline -n 10`
+
+Expected: only intentional commits are present and the worktree is clean.

From 434975138d056b7582478ae415d7038ad7535fa4 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:27:38 +0000
Subject: [PATCH 069/134] HACK-441: checkpoint merge prep

---
 docs/guides/prerequisite-detection-matrix.md |  2 +-
 src/cli/prerequisites.ts                     | 10 ++++++++++
 tests/prerequisites-matrix.test.ts           | 20 ++++++++++++++++++++
 3 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/docs/guides/prerequisite-detection-matrix.md b/docs/guides/prerequisite-detection-matrix.md
index b4ca50619..7182363bf 100644
--- a/docs/guides/prerequisite-detection-matrix.md
+++ b/docs/guides/prerequisite-detection-matrix.md
@@ -157,6 +157,6 @@ alias path.
 
 - Preserve the current distinction between diagnostics and actions. Status commands should not disappear behind setup wizards.
 - Keep conditional checks conditional. `mux_backend` only matters for lifecycle-backed `hack up`/`hack restart` when lifecycle host processes are configured.
-- Keep cleanup and local-only config commands out of shared interception. `x github disconnect`, `linear disconnect`, `linear assignee-mappings`, and `linear project-unlink` should use command-local validation instead of the prerequisite matrix.
+- Keep cleanup and local-only config commands out of shared interception. `x github disconnect`, `linear disconnect`, `linear assignee-mappings`, `linear set-assignee-mapping`, `linear remove-assignee-mapping`, and `linear project-unlink` should use command-local validation instead of the prerequisite matrix.
 - Docker detection should distinguish CLI missing from daemon unavailable because the repair path is different.
 - GitHub and Linear setup flows already contain parts of this guidance. Interception should centralize the decision, not duplicate every downstream error string.
diff --git a/src/cli/prerequisites.ts b/src/cli/prerequisites.ts
index 4d6cc40ee..ad34e1c8f 100644
--- a/src/cli/prerequisites.ts
+++ b/src/cli/prerequisites.ts
@@ -654,6 +654,16 @@ export const COMMANDS_WITH_LOCAL_PREREQUISITE_HANDLING = [
     reason:
       "Assignee mapping inspection should continue to rely on command-local validation rather than shared prerequisite interception.",
   },
+  {
+    command: "linear set-assignee-mapping",
+    reason:
+      "Assignee mapping updates are local config mutations and should continue to rely on command-local validation.",
+  },
+  {
+    command: "linear remove-assignee-mapping",
+    reason:
+      "Assignee mapping cleanup is local config mutation state and should not be hidden behind shared setup guidance.",
+  },
   {
     command: "linear project-unlink",
     reason:
diff --git a/tests/prerequisites-matrix.test.ts b/tests/prerequisites-matrix.test.ts
index 008c6679b..0c94525fa 100644
--- a/tests/prerequisites-matrix.test.ts
+++ b/tests/prerequisites-matrix.test.ts
@@ -165,12 +165,30 @@ test("cleanup and local-config commands stay out of shared prerequisite intercep
   expect(
     getCommandPrerequisiteContracts({ command: "linear assignee-mappings" })
   ).toEqual([]);
+  expect(
+    getCommandPrerequisiteContracts({ command: "linear set-assignee-mapping" })
+  ).toEqual([]);
+  expect(
+    getCommandPrerequisiteContracts({
+      command: "linear remove-assignee-mapping",
+    })
+  ).toEqual([]);
   expect(
     getCommandPrerequisiteContracts({ command: "linear project-unlink" })
   ).toEqual([]);
   expect(
     getCommandPrerequisiteContracts({ command: "x linear disconnect" })
   ).toEqual([]);
+  expect(
+    getCommandPrerequisiteContracts({
+      command: "x linear set-assignee-mapping",
+    })
+  ).toEqual([]);
+  expect(
+    getCommandPrerequisiteContracts({
+      command: "x linear remove-assignee-mapping",
+    })
+  ).toEqual([]);
 });
 
 test("major setup commands can be explicitly excluded from shared interception", () => {
@@ -182,6 +200,8 @@ test("major setup commands can be explicitly excluded from shared interception",
     "x github disconnect",
     "linear disconnect",
     "linear assignee-mappings",
+    "linear set-assignee-mapping",
+    "linear remove-assignee-mapping",
     "linear project-unlink",
   ]);
 

From ea08c7f417e27ada6a8b6f8b12039514cb21180b Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:30:59 +0000
Subject: [PATCH 070/134] fix: close linear project artifact edge cases

---
 .../extensions/linear/commands.ts             |   8 +-
 .../extensions/linear/project-artifacts.ts    | 195 ++++++++++++++++--
 tests/linear-commands.test.ts                 | 193 +++++++++++++++++
 tests/linear-project-artifacts.test.ts        |  58 ++++++
 4 files changed, 434 insertions(+), 20 deletions(-)

diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index 7aae1945f..e889971af 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -3336,7 +3336,7 @@ async function applyManagedProjectArtifactCreate(input: {
     const created = await input.runtime.linear.createProjectDocument({
       projectId: input.runtime.projectId,
       title: input.artifact.title,
-      ...(input.artifact.body ? { content: input.artifact.body } : {}),
+      content: input.artifact.body,
       ...(input.artifact.icon ? { icon: input.artifact.icon } : {}),
       ...(input.artifact.sortOrder !== undefined
         ? { sortOrder: input.artifact.sortOrder }
@@ -3366,7 +3366,7 @@ async function applyManagedProjectArtifactCreate(input: {
   const created = await input.runtime.linear.createProjectMilestone({
     projectId: input.runtime.projectId,
     title: input.artifact.title,
-    ...(input.artifact.body ? { description: input.artifact.body } : {}),
+    description: input.artifact.body,
     ...(input.artifact.targetDate
       ? { targetDate: input.artifact.targetDate }
       : {}),
@@ -3410,7 +3410,7 @@ async function applyManagedProjectArtifactUpdate(input: {
     const updated = await input.runtime.linear.updateProjectDocument({
       documentId: input.artifact.linearId,
       title: input.artifact.title,
-      ...(input.artifact.body ? { content: input.artifact.body } : {}),
+      content: input.artifact.body,
       ...(input.artifact.icon ? { icon: input.artifact.icon } : {}),
       ...(input.artifact.sortOrder !== undefined
         ? { sortOrder: input.artifact.sortOrder }
@@ -3443,7 +3443,7 @@ async function applyManagedProjectArtifactUpdate(input: {
   const updated = await input.runtime.linear.updateProjectMilestone({
     milestoneId: input.artifact.linearId,
     title: input.artifact.title,
-    ...(input.artifact.body ? { description: input.artifact.body } : {}),
+    description: input.artifact.body,
     ...(input.artifact.targetDate
       ? { targetDate: input.artifact.targetDate }
       : {}),
diff --git a/src/control-plane/extensions/linear/project-artifacts.ts b/src/control-plane/extensions/linear/project-artifacts.ts
index 5651f4d0a..d0e41a9f4 100644
--- a/src/control-plane/extensions/linear/project-artifacts.ts
+++ b/src/control-plane/extensions/linear/project-artifacts.ts
@@ -65,6 +65,11 @@ export type LinearProjectArtifactPlan = {
 };
 
 const FRONTMATTER_PATTERN = /^---\n([\s\S]*?)\n---\n?/;
+const YAML_EDGE_WHITESPACE_PATTERN = /^\s|\s$/;
+const YAML_COMMENT_PATTERN = /(^|\s)#/;
+const YAML_COLON_SPACE_PATTERN = /:\s/;
+const YAML_SPECIAL_CHARACTER_PATTERN = /[\n\r[\]{}&,*!|>'"%@`]/;
+const YAML_RESERVED_LITERAL_PATTERN = /^(?:true|false|null|~)$/i;
 
 /** Resolve the repo-backed root for all managed artifacts of a bound Linear project. */
 export const resolveLinearProjectArtifactsRoot = ({
@@ -208,8 +213,19 @@ export const planLinearProjectArtifactChanges = ({
   }
 
   const remoteByKey = new Map<string, LinearProjectArtifactSnapshot>();
+  const remoteBySlugKey = new Map<string, LinearProjectArtifactSnapshot>();
+  const remoteByTitleKey = new Map<
+    string,
+    LinearProjectArtifactSnapshot | null
+  >();
   for (const artifact of remoteArtifacts) {
     remoteByKey.set(buildArtifactKey({ artifact }), artifact);
+    if (artifact.slug) {
+      remoteBySlugKey.set(buildArtifactSlugKey({ artifact }), artifact);
+    }
+    const titleKey = buildArtifactTitleKey({ artifact });
+    const existing = remoteByTitleKey.get(titleKey);
+    remoteByTitleKey.set(titleKey, existing ? null : artifact);
   }
 
   const create: LocalLinearProjectArtifact[] = [];
@@ -227,6 +243,17 @@ export const planLinearProjectArtifactChanges = ({
     const key = buildArtifactKey({ artifact: local });
     const remote = remoteByKey.get(key);
     if (!remote) {
+      const matchedRemote = findRemoteArtifactAliasMatch({
+        artifact: local,
+        remoteBySlugKey,
+        remoteByTitleKey,
+      });
+      if (matchedRemote) {
+        errors.push(
+          `Local artifact ${local.path} matches remote linearId "${matchedRemote.linearId}" by slug/title. Pull first or add the remote linearId before apply.`
+        );
+        continue;
+      }
       create.push(local);
       continue;
     }
@@ -242,8 +269,18 @@ export const planLinearProjectArtifactChanges = ({
     (artifact) => !seenRemoteKeys.has(buildArtifactKey({ artifact }))
   );
 
+  if (errors.length > 0) {
+    return {
+      errors,
+      create: [],
+      update: [],
+      noop: [],
+      remoteOnly: [],
+    };
+  }
+
   return {
-    errors: [],
+    errors,
     create,
     update,
     noop,
@@ -503,20 +540,34 @@ const serializeCommonFrontmatter = ({
   readonly artifact: LocalLinearProjectArtifact;
 }): string[] => {
   const lines = [
-    `kind: ${artifact.kind}`,
-    `linearProjectId: ${artifact.linearProjectId}`,
-    `title: ${artifact.title}`,
+    serializeFrontmatterValue({ key: "kind", value: artifact.kind }),
+    serializeFrontmatterValue({
+      key: "linearProjectId",
+      value: artifact.linearProjectId,
+    }),
+    serializeFrontmatterValue({ key: "title", value: artifact.title }),
   ];
 
   if (artifact.linearId) {
-    lines.push(`linearId: ${artifact.linearId}`);
+    lines.push(
+      serializeFrontmatterValue({ key: "linearId", value: artifact.linearId })
+    );
   }
   if (artifact.slug) {
-    lines.push(`slug: ${artifact.slug}`);
+    lines.push(
+      serializeFrontmatterValue({ key: "slug", value: artifact.slug })
+    );
   }
-  lines.push(`archived: ${artifact.archived ? "true" : "false"}`);
+  lines.push(
+    serializeFrontmatterValue({ key: "archived", value: artifact.archived })
+  );
   if (artifact.updatedAt) {
-    lines.push(`updatedAt: ${artifact.updatedAt}`);
+    lines.push(
+      serializeFrontmatterValue({
+        key: "updatedAt",
+        value: artifact.updatedAt,
+      })
+    );
   }
 
   return lines;
@@ -548,10 +599,14 @@ const serializeDocumentFrontmatter = ({
 }): string[] => {
   const lines: string[] = [];
   if (artifact.sortOrder !== undefined) {
-    lines.push(`sortOrder: ${artifact.sortOrder}`);
+    lines.push(
+      serializeFrontmatterValue({ key: "sortOrder", value: artifact.sortOrder })
+    );
   }
   if (artifact.icon) {
-    lines.push(`icon: ${artifact.icon}`);
+    lines.push(
+      serializeFrontmatterValue({ key: "icon", value: artifact.icon })
+    );
   }
   return lines;
 };
@@ -566,13 +621,22 @@ const serializeMilestoneFrontmatter = ({
 }): string[] => {
   const lines: string[] = [];
   if (artifact.targetDate) {
-    lines.push(`targetDate: ${artifact.targetDate}`);
+    lines.push(
+      serializeFrontmatterValue({
+        key: "targetDate",
+        value: artifact.targetDate,
+      })
+    );
   }
   if (artifact.state) {
-    lines.push(`state: ${artifact.state}`);
+    lines.push(
+      serializeFrontmatterValue({ key: "state", value: artifact.state })
+    );
   }
   if (artifact.sortOrder !== undefined) {
-    lines.push(`sortOrder: ${artifact.sortOrder}`);
+    lines.push(
+      serializeFrontmatterValue({ key: "sortOrder", value: artifact.sortOrder })
+    );
   }
   return lines;
 };
@@ -587,20 +651,54 @@ const serializeStatusUpdateFrontmatter = ({
 }): string[] => {
   const lines: string[] = [];
   if (artifact.date) {
-    lines.push(`date: ${artifact.date}`);
+    lines.push(
+      serializeFrontmatterValue({ key: "date", value: artifact.date })
+    );
   }
   if (artifact.health) {
-    lines.push(`health: ${artifact.health}`);
+    lines.push(
+      serializeFrontmatterValue({ key: "health", value: artifact.health })
+    );
   }
   if (artifact.linkedMilestoneIds && artifact.linkedMilestoneIds.length > 0) {
     lines.push("linkedMilestoneIds:");
     for (const milestoneId of artifact.linkedMilestoneIds) {
-      lines.push(`  - ${milestoneId}`);
+      lines.push(`  - ${serializeYamlString({ value: milestoneId })}`);
     }
   }
   return lines;
 };
 
+const serializeFrontmatterValue = ({
+  key,
+  value,
+}: {
+  readonly key: string;
+  readonly value: boolean | number | string;
+}): string => `${key}: ${serializeYamlPrimitive({ value })}`;
+
+const serializeYamlPrimitive = ({
+  value,
+}: {
+  readonly value: boolean | number | string;
+}): string => {
+  if (typeof value === "string") {
+    return serializeYamlString({ value });
+  }
+  return String(value);
+};
+
+const serializeYamlString = ({ value }: { readonly value: string }): string =>
+  needsYamlQuoting({ value }) ? JSON.stringify(value) : value;
+
+const needsYamlQuoting = ({ value }: { readonly value: string }): boolean =>
+  value.length === 0 ||
+  YAML_EDGE_WHITESPACE_PATTERN.test(value) ||
+  YAML_COMMENT_PATTERN.test(value) ||
+  YAML_COLON_SPACE_PATTERN.test(value) ||
+  YAML_SPECIAL_CHARACTER_PATTERN.test(value) ||
+  YAML_RESERVED_LITERAL_PATTERN.test(value);
+
 const detectLocalDuplicates = ({
   artifacts,
 }: {
@@ -645,6 +743,7 @@ const detectRemoteDuplicates = ({
 }): string[] => {
   const errors: string[] = [];
   const seenKeys = new Set<string>();
+  const seenSlugKeys = new Set<string>();
   for (const artifact of artifacts) {
     const key = buildArtifactKey({ artifact });
     if (seenKeys.has(key)) {
@@ -652,10 +751,54 @@ const detectRemoteDuplicates = ({
       continue;
     }
     seenKeys.add(key);
+
+    if (artifact.slug) {
+      const slugKey = buildArtifactSlugKey({ artifact });
+      if (seenSlugKeys.has(slugKey)) {
+        errors.push(`Duplicate remote artifact slug mapping for ${slugKey}`);
+      } else {
+        seenSlugKeys.add(slugKey);
+      }
+    }
   }
   return errors;
 };
 
+const findRemoteArtifactAliasMatch = ({
+  artifact,
+  remoteBySlugKey,
+  remoteByTitleKey,
+}: {
+  readonly artifact: LocalLinearProjectArtifact;
+  readonly remoteBySlugKey: ReadonlyMap<string, LinearProjectArtifactSnapshot>;
+  readonly remoteByTitleKey: ReadonlyMap<
+    string,
+    LinearProjectArtifactSnapshot | null
+  >;
+}): LinearProjectArtifactSnapshot | null => {
+  if (artifact.linearId) {
+    return null;
+  }
+
+  if (artifact.slug) {
+    const matchedBySlug = remoteBySlugKey.get(
+      buildArtifactSlugKey({ artifact })
+    );
+    if (matchedBySlug?.linearId) {
+      return matchedBySlug;
+    }
+  }
+
+  const matchedByTitle = remoteByTitleKey.get(
+    buildArtifactTitleKey({ artifact })
+  );
+  if (matchedByTitle?.linearId) {
+    return matchedByTitle;
+  }
+
+  return null;
+};
+
 const buildArtifactKey = ({
   artifact,
 }: {
@@ -670,6 +813,26 @@ const buildArtifactKey = ({
   return `${artifact.kind}:title:${artifact.linearProjectId}:${artifact.title}`;
 };
 
+const buildArtifactSlugKey = ({
+  artifact,
+}: {
+  readonly artifact: Pick<
+    LinearProjectArtifactSnapshot,
+    "kind" | "linearProjectId" | "slug"
+  >;
+}): string =>
+  `${artifact.kind}:slug:${artifact.linearProjectId}:${artifact.slug}`;
+
+const buildArtifactTitleKey = ({
+  artifact,
+}: {
+  readonly artifact: Pick<
+    LinearProjectArtifactSnapshot,
+    "kind" | "linearProjectId" | "title"
+  >;
+}): string =>
+  `${artifact.kind}:title:${artifact.linearProjectId}:${artifact.title}`;
+
 const artifactsEqual = ({
   local,
   remote,
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index 027cf60f0..31131b1e0 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -2147,6 +2147,128 @@ archived: false
   expect(await Bun.file(oldPath).exists()).toBe(false);
 });
 
+test("runProjectArtifactCommand apply refuses to create a duplicate document when a matching remote slug already exists", async () => {
+  const projectDir = ensureTempDir();
+  const documentsDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/documents"
+  );
+  await mkdir(documentsDir, { recursive: true });
+  await writeFile(
+    resolve(documentsDir, "launch-plan.md"),
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: Launch plan
+slug: launch-plan
+archived: false
+---
+# Launch plan
+`
+  );
+
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "documents",
+    verb: "apply",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectDocuments: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "doc_123",
+              title: "Launch plan",
+              content: "# Remote launch plan\n",
+              slugId: "launch-plan",
+              archived: false,
+            },
+          ],
+        }),
+        createProjectDocument: async () => {
+          throw new Error("createProjectDocument should not be called");
+        },
+      },
+    },
+  });
+
+  expect(result.ok).toBe(false);
+  if (result.ok) {
+    return;
+  }
+
+  expect(result.error).toContain('matches remote linearId "doc_123"');
+});
+
+test("runProjectArtifactCommand apply sends empty document bodies to clear remote content", async () => {
+  const projectDir = ensureTempDir();
+  const documentsDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/documents"
+  );
+  await mkdir(documentsDir, { recursive: true });
+  await writeFile(
+    resolve(documentsDir, "launch-plan.md"),
+    `---
+kind: linear-project-document
+linearProjectId: proj_123
+title: Launch plan
+linearId: doc_123
+slug: launch-plan
+archived: false
+---
+`
+  );
+
+  const updateCalls: string[] = [];
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "documents",
+    verb: "apply",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectDocuments: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "doc_123",
+              title: "Launch plan",
+              content: "# Remote launch plan\n",
+              slugId: "launch-plan",
+              archived: false,
+            },
+          ],
+        }),
+        updateProjectDocument: async ({ documentId, content }) => {
+          updateCalls.push(`${documentId}:${content ?? "<missing>"}`);
+          return {
+            ok: true as const,
+            data: {
+              id: documentId,
+              title: "Launch plan",
+              content: content ?? "",
+              slugId: "launch-plan",
+              archived: false,
+              updatedAt: "2026-03-15T10:00:00.000Z",
+            },
+          };
+        },
+      },
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(updateCalls).toEqual(["doc_123:"]);
+});
+
 test("runProjectArtifactCommand pulls project milestones into repo state", async () => {
   const projectDir = ensureTempDir();
   const result = await __testOnly.runProjectArtifactCommand({
@@ -2326,6 +2448,77 @@ Prepare launch checklist.
   expect(updatedText).toContain("state: planned");
 });
 
+test("runProjectArtifactCommand apply sends empty milestone notes to clear remote content", async () => {
+  const projectDir = ensureTempDir();
+  const milestonesDir = resolve(
+    projectDir,
+    ".hack/linear/projects/proj_123/milestones"
+  );
+  await mkdir(milestonesDir, { recursive: true });
+  await writeFile(
+    resolve(milestonesDir, "launch.md"),
+    `---
+kind: linear-project-milestone
+linearProjectId: proj_123
+title: Launch
+linearId: milestone_launch
+slug: launch
+targetDate: 2026-05-01
+state: planned
+archived: false
+---
+`
+  );
+
+  const updateCalls: string[] = [];
+  const result = await __testOnly.runProjectArtifactCommand({
+    family: "milestones",
+    verb: "apply",
+    runtime: {
+      profileId: "work",
+      projectDir,
+      projectId: "proj_123",
+      linear: {
+        listProjectMilestones: async () => ({
+          ok: true as const,
+          data: [
+            {
+              id: "milestone_launch",
+              title: "Launch",
+              description: "Old launch notes.\n",
+              status: "planned",
+              targetDate: "2026-05-01",
+              archived: false,
+            },
+          ],
+        }),
+        updateProjectMilestone: async ({ milestoneId, description }) => {
+          updateCalls.push(`${milestoneId}:${description ?? "<missing>"}`);
+          return {
+            ok: true as const,
+            data: {
+              id: milestoneId,
+              title: "Launch",
+              description: description ?? "",
+              status: "planned",
+              targetDate: "2026-05-01",
+              archived: false,
+              updatedAt: "2026-03-15T10:00:00.000Z",
+            },
+          };
+        },
+      },
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(updateCalls).toEqual(["milestone_launch:"]);
+});
+
 test("runProjectArtifactCommand publishes draft status updates and moves them to published", async () => {
   const projectDir = ensureTempDir();
   const draftsDir = resolve(
diff --git a/tests/linear-project-artifacts.test.ts b/tests/linear-project-artifacts.test.ts
index 151d2eef8..5a48f6dff 100644
--- a/tests/linear-project-artifacts.test.ts
+++ b/tests/linear-project-artifacts.test.ts
@@ -213,6 +213,41 @@ test("planLinearProjectArtifactChanges distinguishes create update noop and remo
   expect(plan.remoteOnly.map((item) => item.title)).toEqual(["Remote only"]);
 });
 
+test("planLinearProjectArtifactChanges flags slug-matched remotes when local linearId is missing", () => {
+  const plan = planLinearProjectArtifactChanges({
+    localArtifacts: [
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "Launch plan",
+        slug: "launch-plan",
+        body: "# Launch plan\n",
+        path: "/repo/.hack/linear/projects/proj_123/documents/launch-plan.md",
+        archived: false,
+      },
+    ],
+    remoteArtifacts: [
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "Launch plan",
+        linearId: "doc_123",
+        slug: "launch-plan",
+        body: "# Remote launch plan\n",
+        archived: false,
+      },
+    ],
+  });
+
+  expect(plan.errors).toEqual([
+    'Local artifact /repo/.hack/linear/projects/proj_123/documents/launch-plan.md matches remote linearId "doc_123" by slug/title. Pull first or add the remote linearId before apply.',
+  ]);
+  expect(plan.create).toEqual([]);
+  expect(plan.update).toEqual([]);
+  expect(plan.noop).toEqual([]);
+  expect(plan.remoteOnly).toEqual([]);
+});
+
 test("serializeLinearProjectArtifactFile writes stable frontmatter", () => {
   const text = serializeLinearProjectArtifactFile({
     artifact: {
@@ -245,3 +280,26 @@ linkedMilestoneIds:
 Still on track for dogfooding.
 `);
 });
+
+test("serializeLinearProjectArtifactFile round-trips YAML-sensitive string fields", () => {
+  const text = serializeLinearProjectArtifactFile({
+    artifact: {
+      kind: "linear-project-document",
+      linearProjectId: "proj_123",
+      title: "API: Launch #1",
+      linearId: "doc_123",
+      slug: "api-launch",
+      body: "# API launch\n",
+      archived: false,
+      path: "/repo/.hack/linear/projects/proj_123/documents/api-launch.md",
+    },
+  });
+
+  const reparsed = parseLinearProjectArtifactFile({
+    filePath: "/repo/.hack/linear/projects/proj_123/documents/api-launch.md",
+    text,
+  });
+
+  expect(reparsed.title).toBe("API: Launch #1");
+  expect(reparsed.slug).toBe("api-launch");
+});

From 2f4239f1076f5e54ee3c20573f3c633f2e0ca810 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:31:48 +0000
Subject: [PATCH 071/134] fix(ssh): respect mux backend for workspace attach

---
 docs/sessions.md           |   4 +-
 src/commands/ssh.ts        | 215 ++++++++++++++++++++++---------------
 tests/session-help.test.ts |   1 +
 tests/ssh-command.test.ts  |  21 ++++
 4 files changed, 155 insertions(+), 86 deletions(-)
 create mode 100644 tests/ssh-command.test.ts

diff --git a/docs/sessions.md b/docs/sessions.md
index 8c8851f85..590f5745d 100644
--- a/docs/sessions.md
+++ b/docs/sessions.md
@@ -172,9 +172,11 @@ hack ssh my-session
 
 1. **SSH command**: Copy-paste command to connect
 2. **QR code**: Scan with mobile SSH apps (Blink, Termius)
-3. **Active workspaces**: List of active tmux workspaces on this machine (currently tmux-only)
+3. **Active workspaces**: List of active workspaces on this machine, including the active mux backend when known
 4. **Action picker**: Done or connect to a workspace
 
+When you connect to an existing workspace, hack uses that workspace's backend. When you create a new one from the SSH flow, hack uses the configured default backend (`sessions.mux`).
+
 ### Tailscale setup
 
 If Tailscale is stopped or not connected, `hack ssh` will prompt to start it:
diff --git a/src/commands/ssh.ts b/src/commands/ssh.ts
index 9bf364c2f..575d200a7 100644
--- a/src/commands/ssh.ts
+++ b/src/commands/ssh.ts
@@ -2,12 +2,19 @@ import * as p from "@clack/prompts";
 import qrcode from "qrcode-terminal";
 import type { CliContext, CommandArgs } from "../cli/command.ts";
 import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
-import { exec, run } from "../lib/shell.ts";
+import { findProjectContext, type ProjectContext } from "../lib/project.ts";
+import { run } from "../lib/shell.ts";
 import {
   buildDirectSshCommand,
   buildTailscaleSshCommand,
   validateTailscaleSetup,
 } from "../lib/tailscale.ts";
+import type { MuxBackendName, MuxSession } from "../mux/mux-backend.ts";
+import {
+  listMuxSessions,
+  resolveDefaultBackendName,
+  resolveMux,
+} from "../mux/mux-resolver.ts";
 
 /** Connection method: Tailscale or direct SSH */
 type ConnectionMethod = "tailscale" | "direct";
@@ -15,15 +22,6 @@ type ConnectionMethod = "tailscale" | "direct";
 /** Valid session name pattern: alphanumeric, dash, underscore, or dot */
 const SESSION_NAME_PATTERN = /^[\w.-]+$/;
 
-/**
- * Parsed tmux session info.
- */
-interface TmuxSession {
-  readonly name: string;
-  readonly attached: boolean;
-  readonly path: string | null;
-}
-
 const optHost = defineOption({
   name: "host",
   type: "string",
@@ -67,6 +65,8 @@ const sshSpec = defineCommand({
   name: "ssh",
   summary: "Show SSH connection info for remote access to this machine",
   group: "Project",
+  description:
+    "Show SSH connection info for this machine and optionally connect to a persistent workspace. Existing workspaces reuse their current mux backend, and newly created workspaces use the configured default backend.",
   options: [optHost, optUser, optTailscale, optDirect, optPort],
   positionals: [
     {
@@ -135,15 +135,19 @@ async function handleSsh(opts: {
   console.log("");
 
   // Step 4: Show active workspaces
-  const sessions = await listTmuxSessions();
+  const projectContext = await resolveCurrentProjectContext();
+  const sessions = await listWorkspaceSessions({ project: projectContext });
 
   if (sessions.length > 0) {
     const sessionList = sessions
-      .map((s) => `  • ${s.name}${s.attached ? " (attached)" : ""}`)
+      .map(
+        (s) =>
+          `  • ${s.name} [${s.backend}]${s.attached === true ? " (attached)" : ""}`
+      )
       .join("\n");
-    p.log.info(`Active tmux workspaces:\n${sessionList}`);
+    p.log.info(`Active workspaces:\n${sessionList}`);
   } else {
-    p.log.info("No active tmux workspaces");
+    p.log.info("No active workspaces");
   }
 
   // Step 5: Ask what to do
@@ -157,7 +161,19 @@ async function handleSsh(opts: {
       return 1;
     }
     // Direct connect to specified workspace
+    const backend = await resolveWorkspaceBackendForSsh({
+      workspaceName: workspaceArg,
+      project: projectContext,
+      sessions,
+    });
+    if (!backend) {
+      p.log.error(
+        "No session mux backend available. Install tmux or zellij, or set sessions.mux to auto|tmux|zellij."
+      );
+      return 1;
+    }
     return await connectToSession({
+      backend,
       hostname,
       user,
       port,
@@ -165,13 +181,22 @@ async function handleSsh(opts: {
     });
   }
 
-  const sessionName = await resolveSessionNameToConnect({ sessions });
-  if (!sessionName) {
+  const selection = await resolveSessionNameToConnect({
+    project: projectContext,
+    sessions,
+  });
+  if (!selection) {
     p.outro("Copy the SSH command above to connect from other devices");
     return 0;
   }
 
-  return await connectToSession({ hostname, user, port, sessionName });
+  return await connectToSession({
+    backend: selection.backend,
+    hostname,
+    user,
+    port,
+    sessionName: selection.sessionName,
+  });
 }
 
 async function resolveConnection(opts: {
@@ -276,9 +301,49 @@ async function resolveDirectHost(opts: {
   return hostInput.trim();
 }
 
+async function resolveCurrentProjectContext(): Promise<ProjectContext | null> {
+  return await findProjectContext(process.cwd());
+}
+
+async function listWorkspaceSessions(opts: {
+  readonly project: ProjectContext | null;
+}): Promise<readonly MuxSession[]> {
+  const mux = await resolveMux({ project: opts.project });
+  return await listMuxSessions({
+    mode: mux.mode,
+    backends: mux.backends,
+  });
+}
+
+async function resolveDefaultWorkspaceBackend(opts: {
+  readonly project: ProjectContext | null;
+}): Promise<MuxBackendName | null> {
+  const mux = await resolveMux({ project: opts.project });
+  return resolveDefaultBackendName({
+    mode: mux.mode,
+    backends: mux.backends,
+  });
+}
+
+async function resolveWorkspaceBackendForSsh(opts: {
+  readonly workspaceName: string;
+  readonly project: ProjectContext | null;
+  readonly sessions: readonly MuxSession[];
+}): Promise<MuxBackendName | null> {
+  return (
+    opts.sessions.find((session) => session.name === opts.workspaceName)
+      ?.backend ??
+    (await resolveDefaultWorkspaceBackend({ project: opts.project }))
+  );
+}
+
 async function resolveSessionNameToConnect(opts: {
-  readonly sessions: readonly TmuxSession[];
-}): Promise<string | null> {
+  readonly project: ProjectContext | null;
+  readonly sessions: readonly MuxSession[];
+}): Promise<{
+  readonly backend: MuxBackendName;
+  readonly sessionName: string;
+} | null> {
   const action = await p.select({
     message: "What would you like to do?",
     options: [
@@ -290,7 +355,7 @@ async function resolveSessionNameToConnect(opts: {
       {
         value: "connect" as const,
         label: "Connect to workspace",
-        hint: "SSH into a tmux workspace",
+        hint: "SSH into a persistent workspace",
       },
     ],
   });
@@ -303,7 +368,7 @@ async function resolveSessionNameToConnect(opts: {
     ...opts.sessions.map((s) => ({
       value: s.name,
       label: s.name,
-      hint: s.attached ? "attached" : undefined,
+      hint: s.attached === true ? `${s.backend} attached` : s.backend,
     })),
     { value: "__new__", label: "Create new workspace" },
   ];
@@ -318,7 +383,18 @@ async function resolveSessionNameToConnect(opts: {
   }
 
   if (selectedSession !== "__new__") {
-    return selectedSession;
+    const backend = await resolveWorkspaceBackendForSsh({
+      workspaceName: selectedSession,
+      project: opts.project,
+      sessions: opts.sessions,
+    });
+    if (!backend) {
+      p.log.error(
+        "No session mux backend available. Install tmux or zellij, or set sessions.mux to auto|tmux|zellij."
+      );
+      return null;
+    }
+    return { backend, sessionName: selectedSession };
   }
 
   const name = await p.text({
@@ -337,7 +413,17 @@ async function resolveSessionNameToConnect(opts: {
     return null;
   }
 
-  return (name || "main").trim();
+  const backend = await resolveDefaultWorkspaceBackend({
+    project: opts.project,
+  });
+  if (!backend) {
+    p.log.error(
+      "No session mux backend available. Install tmux or zellij, or set sessions.mux to auto|tmux|zellij."
+    );
+    return null;
+  }
+
+  return { backend, sessionName: (name || "main").trim() };
 }
 
 /**
@@ -407,9 +493,10 @@ async function setupTailscale(): Promise<
 }
 
 /**
- * Connect to a tmux workspace via SSH.
+ * Connect to a workspace via SSH.
  */
 async function connectToSession(opts: {
+  readonly backend: MuxBackendName;
   readonly hostname: string;
   readonly user?: string;
   readonly port?: number;
@@ -426,11 +513,10 @@ async function connectToSession(opts: {
   p.log.step(`Connecting to workspace ${sessionName}...`);
   console.log("");
 
-  // Use login shell to ensure PATH includes homebrew etc.
-  // -d detaches other clients to avoid size conflicts from different terminals
-  const quotedSessionName = shellQuote({ value: sessionName });
-  const tmuxInnerCommand = `tmux attach -d -t ${quotedSessionName} 2>/dev/null || tmux new -s ${quotedSessionName}`;
-  const tmuxCmd = `$SHELL -l -c ${shellQuote({ value: tmuxInnerCommand })}`;
+  const attachCommand = buildWorkspaceAttachShellCommand({
+    backend: opts.backend,
+    workspaceName: sessionName,
+  });
 
   const sshArgs = [
     "ssh",
@@ -438,70 +524,29 @@ async function connectToSession(opts: {
     ...(opts.user ? ["-l", opts.user] : []),
     opts.hostname,
     "-t",
-    tmuxCmd,
+    `$SHELL -l -c ${shellQuote({ value: attachCommand })}`,
   ];
 
   return await run(sshArgs, { stdin: "inherit" });
 }
 
-function shellQuote(opts: { readonly value: string }): string {
-  return `'${opts.value.split("'").join(`'"'"'`)}'`;
-}
-
-/**
- * List all tmux sessions.
- */
-async function listTmuxSessions(): Promise<TmuxSession[]> {
-  const separator = "|||HACK_SESSION_FIELD|||";
-  const format = [
-    "#{session_name}",
-    "#{session_attached}",
-    "#{session_path}",
-  ].join(separator);
-  const result = await exec(["tmux", "list-sessions", "-F", format], {
-    stdin: "ignore",
-  });
-
-  if (result.exitCode !== 0) {
-    return [];
-  }
-
-  const sessions: TmuxSession[] = [];
-  for (const line of result.stdout.split("\n")) {
-    if (!line.trim()) {
-      continue;
-    }
-    const fields = parseTmuxSessionFields(line, separator, 3);
-    if (!fields) {
-      continue;
-    }
-    const [name, attached, path] = fields;
-    if (name) {
-      sessions.push({
-        name,
-        attached: attached === "1",
-        path: path || null,
-      });
-    }
+function buildWorkspaceAttachShellCommand(opts: {
+  readonly backend: MuxBackendName;
+  readonly workspaceName: string;
+}): string {
+  const quotedSessionName = shellQuote({ value: opts.workspaceName });
+  if (opts.backend === "zellij") {
+    return `zellij attach ${quotedSessionName} 2>/dev/null || zellij attach --create ${quotedSessionName}`;
   }
-
-  return sessions;
+  return `tmux attach -d -t ${quotedSessionName} 2>/dev/null || tmux new -s ${quotedSessionName}`;
 }
 
-function parseTmuxSessionFields(
-  line: string,
-  separator: string,
-  expectedCount: number
-): readonly string[] | null {
-  const bySeparator = line.split(separator);
-  if (bySeparator.length === expectedCount) {
-    return bySeparator;
-  }
-  const byTab = line.split("\t");
-  if (byTab.length === expectedCount) {
-    return byTab;
-  }
-  return null;
+function shellQuote(opts: { readonly value: string }): string {
+  return `'${opts.value.split("'").join(`'"'"'`)}'`;
 }
 
 export const sshCommand = withHandler(sshSpec, handleSsh);
+
+export const __testOnlySshCommand = {
+  buildWorkspaceAttachShellCommand,
+};
diff --git a/tests/session-help.test.ts b/tests/session-help.test.ts
index bd176de91..8cad739f9 100644
--- a/tests/session-help.test.ts
+++ b/tests/session-help.test.ts
@@ -46,4 +46,5 @@ test("hack ssh help uses workspace terminology", () => {
 
   expect(help).toContain("hack ssh [workspace]");
   expect(help).toContain("Workspace to connect to");
+  expect(help).toContain("reuse their current mux backend");
 });
diff --git a/tests/ssh-command.test.ts b/tests/ssh-command.test.ts
new file mode 100644
index 000000000..5807b8a95
--- /dev/null
+++ b/tests/ssh-command.test.ts
@@ -0,0 +1,21 @@
+import { expect, test } from "bun:test";
+
+import { __testOnlySshCommand } from "../src/commands/ssh.ts";
+
+test("buildWorkspaceAttachShellCommand uses tmux attach semantics", () => {
+  expect(
+    __testOnlySshCommand.buildWorkspaceAttachShellCommand({
+      backend: "tmux",
+      workspaceName: "alpha",
+    })
+  ).toContain("tmux attach -d -t 'alpha'");
+});
+
+test("buildWorkspaceAttachShellCommand uses zellij attach semantics", () => {
+  expect(
+    __testOnlySshCommand.buildWorkspaceAttachShellCommand({
+      backend: "zellij",
+      workspaceName: "alpha",
+    })
+  ).toContain("zellij attach 'alpha'");
+});

From 4ddc13034a794ca460bf7560864176f9d007efbb Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:43:11 +0000
Subject: [PATCH 072/134] fix: tighten linear artifact conflict handling

---
 .../extensions/linear/project-artifacts.ts    |  6 +-
 tests/linear-commands.test.ts                 | 10 +--
 tests/linear-project-artifacts.test.ts        | 62 ++++++++++++++++++-
 3 files changed, 68 insertions(+), 10 deletions(-)

diff --git a/src/control-plane/extensions/linear/project-artifacts.ts b/src/control-plane/extensions/linear/project-artifacts.ts
index d0e41a9f4..6338e24bc 100644
--- a/src/control-plane/extensions/linear/project-artifacts.ts
+++ b/src/control-plane/extensions/linear/project-artifacts.ts
@@ -68,6 +68,7 @@ const FRONTMATTER_PATTERN = /^---\n([\s\S]*?)\n---\n?/;
 const YAML_EDGE_WHITESPACE_PATTERN = /^\s|\s$/;
 const YAML_COMMENT_PATTERN = /(^|\s)#/;
 const YAML_COLON_SPACE_PATTERN = /:\s/;
+const YAML_PLAIN_SAFE_PATTERN = /^[A-Za-z_./][A-Za-z0-9_./ -]*$/;
 const YAML_SPECIAL_CHARACTER_PATTERN = /[\n\r[\]{}&,*!|>'"%@`]/;
 const YAML_RESERVED_LITERAL_PATTERN = /^(?:true|false|null|~)$/i;
 
@@ -693,6 +694,7 @@ const serializeYamlString = ({ value }: { readonly value: string }): string =>
 
 const needsYamlQuoting = ({ value }: { readonly value: string }): boolean =>
   value.length === 0 ||
+  !YAML_PLAIN_SAFE_PATTERN.test(value) ||
   YAML_EDGE_WHITESPACE_PATTERN.test(value) ||
   YAML_COMMENT_PATTERN.test(value) ||
   YAML_COLON_SPACE_PATTERN.test(value) ||
@@ -776,10 +778,6 @@ const findRemoteArtifactAliasMatch = ({
     LinearProjectArtifactSnapshot | null
   >;
 }): LinearProjectArtifactSnapshot | null => {
-  if (artifact.linearId) {
-    return null;
-  }
-
   if (artifact.slug) {
     const matchedBySlug = remoteBySlugKey.get(
       buildArtifactSlugKey({ artifact })
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index 31131b1e0..ff632f5ad 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -2076,7 +2076,7 @@ archived: false
     resolve(documentsDir, "create-me.md")
   ).text();
   expect(createdText).toContain("linearId: doc_create");
-  expect(createdText).toContain("updatedAt: 2026-03-15T09:00:00.000Z");
+  expect(createdText).toContain('updatedAt: "2026-03-15T09:00:00.000Z"');
 });
 
 test("runProjectArtifactCommand apply rewrites renamed managed documents to the canonical path", async () => {
@@ -2314,7 +2314,7 @@ test("runProjectArtifactCommand pulls project milestones into repo state", async
   const file = await Bun.file(result.payload.writtenPaths[0] ?? "").text();
   expect(file).toContain("kind: linear-project-milestone");
   expect(file).toContain("linearId: milestone_123");
-  expect(file).toContain("targetDate: 2026-04-01");
+  expect(file).toContain('targetDate: "2026-04-01"');
   expect(file).toContain("state: pending");
 });
 
@@ -2437,14 +2437,14 @@ Prepare launch checklist.
     resolve(milestonesDir, "private-beta.md")
   ).text();
   expect(createdText).toContain("linearId: milestone_private_beta");
-  expect(createdText).toContain("updatedAt: 2026-03-15T09:00:00.000Z");
+  expect(createdText).toContain('updatedAt: "2026-03-15T09:00:00.000Z"');
   expect(createdText).toContain("state: pending");
 
   const updatedText = await Bun.file(
     resolve(milestonesDir, "launch.md")
   ).text();
   expect(updatedText).toContain("linearId: milestone_launch");
-  expect(updatedText).toContain("updatedAt: 2026-03-15T10:00:00.000Z");
+  expect(updatedText).toContain('updatedAt: "2026-03-15T10:00:00.000Z"');
   expect(updatedText).toContain("state: planned");
 });
 
@@ -2586,7 +2586,7 @@ Still on track for dogfooding.
     result.payload.movedPaths[0]?.to ?? ""
   ).text();
   expect(publishedText).toContain("linearId: update_123");
-  expect(publishedText).toContain("updatedAt: 2026-03-14T10:15:00.000Z");
+  expect(publishedText).toContain('updatedAt: "2026-03-14T10:15:00.000Z"');
 });
 
 test("runProjectArtifactCommand publish fails for drafts that already have a remote id", async () => {
diff --git a/tests/linear-project-artifacts.test.ts b/tests/linear-project-artifacts.test.ts
index 5a48f6dff..8c7f0db49 100644
--- a/tests/linear-project-artifacts.test.ts
+++ b/tests/linear-project-artifacts.test.ts
@@ -248,6 +248,42 @@ test("planLinearProjectArtifactChanges flags slug-matched remotes when local lin
   expect(plan.remoteOnly).toEqual([]);
 });
 
+test("planLinearProjectArtifactChanges flags slug-matched remotes when local linearId is stale", () => {
+  const plan = planLinearProjectArtifactChanges({
+    localArtifacts: [
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "Launch plan",
+        linearId: "doc_stale",
+        slug: "launch-plan",
+        body: "# Launch plan\n",
+        path: "/repo/.hack/linear/projects/proj_123/documents/launch-plan.md",
+        archived: false,
+      },
+    ],
+    remoteArtifacts: [
+      {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title: "Launch plan",
+        linearId: "doc_123",
+        slug: "launch-plan",
+        body: "# Remote launch plan\n",
+        archived: false,
+      },
+    ],
+  });
+
+  expect(plan.errors).toEqual([
+    'Local artifact /repo/.hack/linear/projects/proj_123/documents/launch-plan.md matches remote linearId "doc_123" by slug/title. Pull first or add the remote linearId before apply.',
+  ]);
+  expect(plan.create).toEqual([]);
+  expect(plan.update).toEqual([]);
+  expect(plan.noop).toEqual([]);
+  expect(plan.remoteOnly).toEqual([]);
+});
+
 test("serializeLinearProjectArtifactFile writes stable frontmatter", () => {
   const text = serializeLinearProjectArtifactFile({
     artifact: {
@@ -272,7 +308,7 @@ title: Weekly update
 linearId: update_123
 slug: weekly
 archived: false
-date: 2026-03-14
+date: "2026-03-14"
 health: onTrack
 linkedMilestoneIds:
   - milestone_123
@@ -303,3 +339,27 @@ test("serializeLinearProjectArtifactFile round-trips YAML-sensitive string field
   expect(reparsed.title).toBe("API: Launch #1");
   expect(reparsed.slug).toBe("api-launch");
 });
+
+test("serializeLinearProjectArtifactFile round-trips YAML edge-case scalars", () => {
+  for (const title of ["- bad", "? question", "1e3"]) {
+    const text = serializeLinearProjectArtifactFile({
+      artifact: {
+        kind: "linear-project-document",
+        linearProjectId: "proj_123",
+        title,
+        linearId: "doc_123",
+        slug: "edge-case",
+        body: "# Edge case\n",
+        archived: false,
+        path: "/repo/.hack/linear/projects/proj_123/documents/edge-case.md",
+      },
+    });
+
+    const reparsed = parseLinearProjectArtifactFile({
+      filePath: "/repo/.hack/linear/projects/proj_123/documents/edge-case.md",
+      text,
+    });
+
+    expect(reparsed.title).toBe(title);
+  }
+});

From 954e8b2340a146c92bf9eca5f7ff18cbe255303d Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 18:46:11 +0000
Subject: [PATCH 073/134] docs: format github workflow scope docs

---
 docs/cli.md        | 832 ++++++++++++++++++++++-----------------------
 docs/extensions.md | 218 ++++++------
 2 files changed, 520 insertions(+), 530 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 247f0f85c..61e0c0e35 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,7 +1,6 @@
 # CLI Reference
 
-This reference mirrors the CLI spec in `src/cli/spec.ts`.
-Run `hack help` or `hack help <command>` for interactive help.
+This reference mirrors the CLI spec in `src/cli/spec.ts`. Run `hack help` or `hack help <command>` for interactive help.
 
 ## Conventions
 
@@ -61,17 +60,17 @@ Usage: `hack global <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `install` | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy |
-| `up` | Start global infra containers |
-| `down` | Stop global infra containers |
-| `status` | Show status for global infra (containers + networks) |
-| `logs` | Tail global infra logs (caddy|grafana|loki|alloy) |
-| `ca` | Export Caddy Local CA cert (print path or PEM) |
-| `cert` | Generate local TLS certs via mkcert (for non-Caddy services) |
-| `trust` | Trust Caddy Local CA (macOS) so https://*.hack is trusted |
-| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards) |
+| Subcommand   | Summary                                                      |
+| ------------ | ------------------------------------------------------------ | ------- | ---- | ------ |
+| `install`    | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy     |
+| `up`         | Start global infra containers                                |
+| `down`       | Stop global infra containers                                 |
+| `status`     | Show status for global infra (containers + networks)         |
+| `logs`       | Tail global infra logs (caddy                                | grafana | loki | alloy) |
+| `ca`         | Export Caddy Local CA cert (print path or PEM)               |
+| `cert`       | Generate local TLS certs via mkcert (for non-Caddy services) |
+| `trust`      | Trust Caddy Local CA (macOS) so https://\*.hack is trusted   |
+| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards)          |
 
 #### hack global logs
 
@@ -79,18 +78,18 @@ Usage: `hack global logs [service] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | no | Filter to one global service (caddy, grafana, loki, alloy) |
+| Name      | Type   | Required | Description                                                |
+| --------- | ------ | -------- | ---------------------------------------------------------- |
+| `service` | string | no       | Filter to one global service (caddy, grafana, loki, alloy) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-f`, `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--tail <n>` | number | 200 | Tail last N log lines |
-| `--pretty` | boolean | false | Pretty-print logs (best-effort JSON parsing + formatting) |
+| Flag             | Type    | Default | Description                                               |
+| ---------------- | ------- | ------- | --------------------------------------------------------- |
+| `-f`, `--follow` | boolean | true    | Follow logs (default)                                     |
+| `--no-follow`    | boolean | false   | Print logs and exit                                       |
+| `--tail <n>`     | number  | 200     | Tail last N log lines                                     |
+| `--pretty`       | boolean | false   | Pretty-print logs (best-effort JSON parsing + formatting) |
 
 #### hack global ca
 
@@ -98,9 +97,9 @@ Usage: `hack global ca [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--print` | boolean | false | Print the CA cert PEM to stdout (instead of printing its path) |
+| Flag      | Type    | Default | Description                                                    |
+| --------- | ------- | ------- | -------------------------------------------------------------- |
+| `--print` | boolean | false   | Print the CA cert PEM to stdout (instead of printing its path) |
 
 #### hack global cert
 
@@ -108,16 +107,16 @@ Usage: `hack global cert <hosts...> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `hosts` | string[] | yes | One or more hostnames to generate certs for |
+| Name    | Type     | Required | Description                                 |
+| ------- | -------- | -------- | ------------------------------------------- |
+| `hosts` | string[] | yes      | One or more hostnames to generate certs for |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--install` | boolean | false | Run mkcert -install before generating certs |
-| `--out <dir>` | string | `~/.hack/certs` | Directory for generated cert/key |
+| Flag          | Type    | Default         | Description                                 |
+| ------------- | ------- | --------------- | ------------------------------------------- |
+| `--install`   | boolean | false           | Run mkcert -install before generating certs |
+| `--out <dir>` | string  | `~/.hack/certs` | Directory for generated cert/key            |
 
 ### hack projects
 
@@ -142,9 +141,9 @@ Usage: `hack projects prune [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
+| Flag               | Type    | Default | Description                                   |
+| ------------------ | ------- | ------- | --------------------------------------------- |
+| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
 
 ### hack status
 
@@ -152,12 +151,12 @@ Usage: `hack status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Filter to a registered project name |
-| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
-| `--all` | boolean | false | Include unregistered docker compose projects |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag               | Type    | Default | Description                                   |
+| ------------------ | ------- | ------- | --------------------------------------------- |
+| `--project <name>` | string  | -       | Filter to a registered project name           |
+| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
+| `--all`            | boolean | false   | Include unregistered docker compose projects  |
+| `--json`           | boolean | false   | Output JSON (machine-readable)                |
 
 ### hack usage
 
@@ -200,13 +199,13 @@ Usage: `hack up [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `-d`, `--detach` | boolean | false | Run in background (docker compose up -d) |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack down
 
@@ -215,12 +214,12 @@ Usage: `hack down [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack restart
 
@@ -229,12 +228,12 @@ Usage: `hack restart [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack ps
 
@@ -256,9 +255,9 @@ Usage: `hack logs [service] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | no | Filter logs by service (shortcut for `--services`) |
+| Name      | Type   | Required | Description                                        |
+| --------- | ------ | -------- | -------------------------------------------------- |
+| `service` | string | no       | Filter logs by service (shortcut for `--services`) |
 
 Options:
 
@@ -292,10 +291,10 @@ Usage: `hack run <service> [-- <cmd...>] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | yes | Compose service name |
-| `cmd` | string[] | no | Command to run (defaults to service entrypoint) |
+| Name      | Type     | Required | Description                                     |
+| --------- | -------- | -------- | ----------------------------------------------- |
+| `service` | string   | yes      | Compose service name                            |
+| `cmd`     | string[] | no       | Command to run (defaults to service entrypoint) |
 
 Options:
 
@@ -313,18 +312,18 @@ Usage: `hack open [target] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `target` | string | no | `www` (default), `logs`, a subdomain, or a full URL |
+| Name     | Type   | Required | Description                                         |
+| -------- | ------ | -------- | --------------------------------------------------- |
+| `target` | string | no       | `www` (default), `logs`, a subdomain, or a full URL |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--branch <name>` | string | - | Run against a branch-specific instance |
-| `--json` | boolean | false | Output JSON with `{ "url": "..." }` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--branch <name>`    | string  | -       | Run against a branch-specific instance         |
+| `--json`             | boolean | false   | Output JSON with `{ "url": "..." }`            |
 
 Notes:
 
@@ -339,10 +338,10 @@ Usage: `hack tui [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 Notes:
 
@@ -354,12 +353,12 @@ Usage: `hack branch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `add` | Register a branch alias for this project |
-| `list` | List registered branch aliases |
-| `remove` | Remove a branch alias |
-| `open` | Open the branch host in a browser |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `add`      | Register a branch alias for this project |
+| `list`     | List registered branch aliases           |
+| `remove`   | Remove a branch alias                    |
+| `open`     | Open the branch host in a browser        |
 
 #### hack branch add
 
@@ -367,17 +366,17 @@ Usage: `hack branch add <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--note <text>` | string | - | Optional note for the branch entry |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
+| `--note <text>`      | string | -       | Optional note for the branch entry             |
 
 #### hack branch list
 
@@ -385,10 +384,10 @@ Usage: `hack branch list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack branch remove
 
@@ -396,16 +395,16 @@ Usage: `hack branch remove <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack branch open
 
@@ -413,16 +412,16 @@ Usage: `hack branch open <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 ### hack config
 
@@ -430,10 +429,10 @@ Usage: `hack config <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `get` | Read a value from hack.config.json |
-| `set` | Update a value in hack.config.json |
+| Subcommand | Summary                            |
+| ---------- | ---------------------------------- |
+| `get`      | Read a value from hack.config.json |
+| `set`      | Update a value in hack.config.json |
 
 #### hack config get
 
@@ -441,17 +440,17 @@ Usage: `hack config get <key> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
+| Name  | Type   | Required | Description                             |
+| ----- | ------ | -------- | --------------------------------------- |
+| `key` | string | yes      | Dot path (e.g. `logs.snapshot_backend`) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--global` | boolean | false | Read global `~/.hack/hack.config.json` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--global`           | boolean | false   | Read global `~/.hack/hack.config.json`         |
 
 #### hack config set
 
@@ -459,18 +458,18 @@ Usage: `hack config set <key> <value> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
-| `value` | string | yes | JSON value or raw string (parsed as JSON when valid) |
+| Name    | Type   | Required | Description                                          |
+| ------- | ------ | -------- | ---------------------------------------------------- |
+| `key`   | string | yes      | Dot path (e.g. `logs.snapshot_backend`)              |
+| `value` | string | yes      | JSON value or raw string (parsed as JSON when valid) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--global` | boolean | false | Write global `~/.hack/hack.config.json` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--global`           | boolean | false   | Write global `~/.hack/hack.config.json`        |
 
 ### hack env
 
@@ -478,12 +477,12 @@ Usage: `hack env <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List env contract vars and resolution state |
-| `set` | Set an env value (.hack/.env or secret backend) |
-| `unset` | Unset an env value (.hack/.env and secret backend) |
-| `backend` | Manage env/secret backend strategy |
+| Subcommand | Summary                                            |
+| ---------- | -------------------------------------------------- |
+| `list`     | List env contract vars and resolution state        |
+| `set`      | Set an env value (.hack/.env or secret backend)    |
+| `unset`    | Unset an env value (.hack/.env and secret backend) |
+| `backend`  | Manage env/secret backend strategy                 |
 
 #### hack env list
 
@@ -491,12 +490,12 @@ Usage: `hack env list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--json` | boolean | false | Output JSON (machine-readable) |
-| `--show-secrets` | boolean | false | Print secret values (secret backend) in plaintext |
+| Flag                 | Type    | Default | Description                                       |
+| -------------------- | ------- | ------- | ------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)    |
+| `--project <name>`   | string  | -       | Target a registered project by name               |
+| `--json`             | boolean | false   | Output JSON (machine-readable)                    |
+| `--show-secrets`     | boolean | false   | Print secret values (secret backend) in plaintext |
 
 #### hack env set
 
@@ -518,10 +517,10 @@ Usage: `hack env unset [key] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack env backend
 
@@ -529,10 +528,10 @@ Usage: `hack env backend <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `status` | Show configured env/secret backend strategy |
-| `use` | Select env/secret backend strategy |
+| Subcommand | Summary                                     |
+| ---------- | ------------------------------------------- |
+| `status`   | Show configured env/secret backend strategy |
+| `use`      | Select env/secret backend strategy          |
 
 #### hack env backend status
 
@@ -540,9 +539,9 @@ Usage: `hack env backend status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag     | Type    | Default | Description                    |
+| -------- | ------- | ------- | ------------------------------ |
+| `--json` | boolean | false   | Output JSON (machine-readable) |
 
 #### hack env backend use
 
@@ -551,8 +550,8 @@ Usage: `hack env backend use <keychain|encrypted_file|cloud> [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--provider <aws|gcp|azure|vault>` | string | - | Cloud provider when backend is `cloud` |
+| --- | --- | --- | --- | --- | --- | --- |
+| `--provider <aws | gcp | azure | vault>` | string | - | Cloud provider when backend is `cloud` |
 | `--store-path <path>` | string | - | Encrypted file path when backend is `encrypted_file` |
 | `--secret-project <id>` | string | - | Optional cloud account/project identifier |
 | `--secret-prefix <prefix>` | string | - | Optional cloud secret name prefix |
@@ -566,16 +565,16 @@ With no subcommand, opens an interactive picker of active sessions and available
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List active sessions |
-| `start` | Start or attach to a session for a project |
-| `stop` | Stop (kill) a session |
-| `attach` | Attach to an existing session |
-| `exec` | Execute a command in a session |
-| `panes` | List panes in a tmux session |
-| `capture` | Capture recent output from a tmux session |
-| `tail` | Tail output from a tmux session |
+| Subcommand | Summary                                    |
+| ---------- | ------------------------------------------ |
+| `list`     | List active sessions                       |
+| `start`    | Start or attach to a session for a project |
+| `stop`     | Stop (kill) a session                      |
+| `attach`   | Attach to an existing session              |
+| `exec`     | Execute a command in a session             |
+| `panes`    | List panes in a tmux session               |
+| `capture`  | Capture recent output from a tmux session  |
+| `tail`     | Tail output from a tmux session            |
 
 #### hack session start
 
@@ -583,11 +582,11 @@ Usage: `hack session start [project] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--up` | boolean | false | Run hack up -d before attaching |
-| `--new` | boolean | false | Force create new session even if one exists |
-| `--name <suffix>` | string | - | Custom suffix for new session (e.g., agent-1) |
+| Flag              | Type    | Default | Description                                   |
+| ----------------- | ------- | ------- | --------------------------------------------- |
+| `--up`            | boolean | false   | Run hack up -d before attaching               |
+| `--new`           | boolean | false   | Force create new session even if one exists   |
+| `--name <suffix>` | string  | -       | Custom suffix for new session (e.g., agent-1) |
 
 #### hack session panes
 
@@ -595,10 +594,10 @@ Usage: `hack session panes <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag       | Type    | Default | Description                          |
+| ---------- | ------- | ------- | ------------------------------------ |
+| `--json`   | boolean | false   | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false   | Output human-friendly text           |
 
 #### hack session capture
 
@@ -606,12 +605,12 @@ Usage: `hack session capture <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--target <target>` | string | - | Tmux pane target (default: active pane) |
-| `--lines <n>` | number | 200 | Number of lines to capture |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag                | Type    | Default | Description                             |
+| ------------------- | ------- | ------- | --------------------------------------- |
+| `--target <target>` | string  | -       | Tmux pane target (default: active pane) |
+| `--lines <n>`       | number  | 200     | Number of lines to capture              |
+| `--json`            | boolean | false   | Output NDJSON stream (start/log/end)    |
+| `--pretty`          | boolean | false   | Output human-friendly text              |
 
 #### hack session tail
 
@@ -619,14 +618,14 @@ Usage: `hack session tail <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--target <target>` | string | - | Tmux pane target (default: active pane) |
-| `--lines <n>` | number | 200 | Number of lines to capture |
-| `--interval-ms <ms>` | number | 500 | Polling interval in milliseconds |
-| `--max-ms <ms>` | number | 5000 | Stop tailing after N milliseconds |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag                 | Type    | Default | Description                             |
+| -------------------- | ------- | ------- | --------------------------------------- |
+| `--target <target>`  | string  | -       | Tmux pane target (default: active pane) |
+| `--lines <n>`        | number  | 200     | Number of lines to capture              |
+| `--interval-ms <ms>` | number  | 500     | Polling interval in milliseconds        |
+| `--max-ms <ms>`      | number  | 5000    | Stop tailing after N milliseconds       |
+| `--json`             | boolean | false   | Output NDJSON stream (start/log/end)    |
+| `--pretty`           | boolean | false   | Output human-friendly text              |
 
 ### hack ssh
 
@@ -634,27 +633,25 @@ Usage: `hack ssh [session] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-H`, `--host <host>` | string | - | SSH host (hostname or IP) |
-| `-u`, `--user <user>` | string | - | SSH username |
-| `-t`, `--tailscale` | boolean | false | Use Tailscale SSH |
-| `-d`, `--direct` | boolean | false | Use direct SSH (requires --host) |
-| `-p`, `--port <port>` | string | - | SSH port for direct connection (default: 22) |
+| Flag                  | Type    | Default | Description                                  |
+| --------------------- | ------- | ------- | -------------------------------------------- |
+| `-H`, `--host <host>` | string  | -       | SSH host (hostname or IP)                    |
+| `-u`, `--user <user>` | string  | -       | SSH username                                 |
+| `-t`, `--tailscale`   | boolean | false   | Use Tailscale SSH                            |
+| `-d`, `--direct`      | boolean | false   | Use direct SSH (requires --host)             |
+| `-p`, `--port <port>` | string  | -       | SSH port for direct connection (default: 22) |
 
 ### hack tickets
 
 Usage: `hack tickets <args...>`
 
-`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`).
-Run `hack tickets` with no args to see available subcommands.
+`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`). Run `hack tickets` with no args to see available subcommands.
 
 ### hack linear
 
 Usage: `hack linear <args...>`
 
-`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`).
-Run `hack linear` with no args to see available subcommands.
+`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`). Run `hack linear` with no args to see available subcommands.
 
 ## Internal commands
 
@@ -664,8 +661,8 @@ Usage: `hack internal <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
+| Subcommand    | Summary                             |
+| ------------- | ----------------------------------- |
 | `extra-hosts` | Manage internal Compose extra_hosts |
 
 #### hack internal extra-hosts
@@ -674,17 +671,17 @@ Usage: `hack internal extra-hosts <subcommand> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <path>` | string | - | Start directory (defaults to cwd) |
+| Flag                  | Type   | Default | Description                       |
+| --------------------- | ------ | ------- | --------------------------------- |
+| `-p`, `--path <path>` | string | -       | Start directory (defaults to cwd) |
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `set` | Set an internal extra_hosts entry |
-| `unset` | Remove an internal extra_hosts entry |
-| `list` | List internal extra_hosts entries |
+| Subcommand | Summary                              |
+| ---------- | ------------------------------------ |
+| `set`      | Set an internal extra_hosts entry    |
+| `unset`    | Remove an internal extra_hosts entry |
+| `list`     | List internal extra_hosts entries    |
 
 #### hack internal extra-hosts set
 
@@ -706,11 +703,11 @@ Usage: `hack gateway <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `enable` | Enable the gateway and start hackd |
-| `setup` | Guided gateway setup (enable + token) |
-| `disable` | Disable the gateway (does not stop hackd) |
+| Subcommand | Summary                                   |
+| ---------- | ----------------------------------------- |
+| `enable`   | Enable the gateway and start hackd        |
+| `setup`    | Guided gateway setup (enable + token)     |
+| `disable`  | Disable the gateway (does not stop hackd) |
 
 #### hack gateway enable
 
@@ -718,10 +715,10 @@ Usage: `hack gateway enable [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack gateway setup
 
@@ -729,13 +726,13 @@ Usage: `hack gateway setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--qr` | boolean | true | Force QR output after setup (default) |
-| `--no-qr` | boolean | false | Skip QR output after setup |
-| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
+| Flag                 | Type    | Default | Description                                         |
+| -------------------- | ------- | ------- | --------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
+| `--project <name>`   | string  | -       | Target a registered project by name                 |
+| `--qr`               | boolean | true    | Force QR output after setup (default)               |
+| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
+| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
 
 #### hack gateway disable
 
@@ -743,10 +740,10 @@ Usage: `hack gateway disable [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 ### hack node
 
@@ -754,20 +751,20 @@ Usage: `hack node <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `init` | Initialize this host as a node and emit enrollment bundle |
-| `pair` | Pair node with one-command or expiring verification-code flow |
-| `ssh` | Manage SSH bootstrap for node pairing and remote runs |
-| `add` | Add a node from an enrollment bundle |
-| `list` | List registered nodes |
-| `status` | Probe node health and report live status |
-| `use` | Set default node |
-| `remove` | Remove node registration |
-| `workspace` | Inspect and repair node workspace map entries |
-| `routes` | Inspect and repair controller-side remote route bridge |
-| `provider` | Manage provider-specific node bootstrap workflows |
-| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints |
+| Subcommand     | Summary                                                       |
+| -------------- | ------------------------------------------------------------- |
+| `init`         | Initialize this host as a node and emit enrollment bundle     |
+| `pair`         | Pair node with one-command or expiring verification-code flow |
+| `ssh`          | Manage SSH bootstrap for node pairing and remote runs         |
+| `add`          | Add a node from an enrollment bundle                          |
+| `list`         | List registered nodes                                         |
+| `status`       | Probe node health and report live status                      |
+| `use`          | Set default node                                              |
+| `remove`       | Remove node registration                                      |
+| `workspace`    | Inspect and repair node workspace map entries                 |
+| `routes`       | Inspect and repair controller-side remote route bridge        |
+| `provider`     | Manage provider-specific node bootstrap workflows             |
+| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints    |
 
 Examples:
 
@@ -872,12 +869,12 @@ Usage: `hack node workspace <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List node-local workspace map entries |
-| `resolve` | Resolve a map entry by controller project selector |
-| `attach` | Attach an existing local workspace to project selector |
-| `remove` | Remove a map entry by project selector |
+| Subcommand | Summary                                                |
+| ---------- | ------------------------------------------------------ |
+| `list`     | List node-local workspace map entries                  |
+| `resolve`  | Resolve a map entry by controller project selector     |
+| `attach`   | Attach an existing local workspace to project selector |
+| `remove`   | Remove a map entry by project selector                 |
 
 Examples:
 
@@ -894,10 +891,10 @@ Usage: `hack node routes <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `status` | Show controller-side remote route bridge state |
-| `repair` | Re-render and re-apply persisted route bridge stack |
+| Subcommand | Summary                                             |
+| ---------- | --------------------------------------------------- |
+| `status`   | Show controller-side remote route bridge state      |
+| `repair`   | Re-render and re-apply persisted route bridge stack |
 
 Examples:
 
@@ -913,11 +910,11 @@ Usage: `hack dispatch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `run` | Dispatch a command to a node workspace |
-| `status` | Show dispatched run status |
-| `logs` | Show or follow persisted/remote run logs |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `run`      | Dispatch a command to a node workspace   |
+| `status`   | Show dispatched run status               |
+| `logs`     | Show or follow persisted/remote run logs |
 
 #### hack dispatch run
 
@@ -926,15 +923,15 @@ Usage: `hack dispatch run --project <name|id> [options] -- <command...>`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name|id>` | string | - | Project name or id |
-| `--node <id|default|auto>` | string | auto | Target node id, or use default/auto |
+| --- | --- | --- | --- | --- | --- | --- |
+| `--project <name | id>` | string | - | Project name or id |
+| `--node <id | default | auto>` | string | auto | Target node id, or use default/auto |
 | `--provider <provider>` | string | - | Provider route override used when resolving profile/bootstrap intent |
 | `--profile <profile-id>` | string | - | Provider profile route override |
 | `--bootstrap-if-needed` | boolean | false | Allow guarded provider bootstrap handoff when no reachable node is found |
 | `--branch <branch>` | string | current | Target branch on selected node |
 | `--ticket <ticket-id>` | string | - | Ticket id to associate with run metadata |
-| `--runner <generic|codex|claude|cursor>` | string | `generic` | Runner identity for policy and audit |
+| `--runner <generic | codex | claude | cursor>` | string | `generic` | Runner identity for policy and audit |
 | `--approve` | boolean | false | Approve high/critical risk commands non-interactively |
 | `--pr` | boolean | false | Push branch + create/update GitHub PR on successful run |
 | `--pr-base <branch>` | string | `main` | Base branch used with `--pr` |
@@ -981,12 +978,12 @@ If you run `hack remote` with no subcommand, it prints status and offers to run
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `setup` | Run the guided gateway setup |
-| `status` | Show remote/gateway status |
-| `monitor` | Open a remote status TUI |
-| `qr` | Print a QR payload for remote access |
+| Subcommand | Summary                              |
+| ---------- | ------------------------------------ |
+| `setup`    | Run the guided gateway setup         |
+| `status`   | Show remote/gateway status           |
+| `monitor`  | Open a remote status TUI             |
+| `qr`       | Print a QR payload for remote access |
 
 #### hack remote setup
 
@@ -994,13 +991,13 @@ Usage: `hack remote setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--qr` | boolean | true | Force QR output after setup (default) |
-| `--no-qr` | boolean | false | Skip QR output after setup |
-| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
+| Flag                 | Type    | Default | Description                                         |
+| -------------------- | ------- | ------- | --------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
+| `--project <name>`   | string  | -       | Target a registered project by name                 |
+| `--qr`               | boolean | true    | Force QR output after setup (default)               |
+| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
+| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
 
 #### hack remote status
 
@@ -1008,10 +1005,10 @@ Usage: `hack remote status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack remote monitor
 
@@ -1019,10 +1016,10 @@ Usage: `hack remote monitor [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack remote qr
 
@@ -1048,9 +1045,9 @@ Usage: `hack x <namespace> <command> [args...]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `args` | string[] | no | Extension command args (passed through) |
+| Name   | Type     | Required | Description                             |
+| ------ | -------- | -------- | --------------------------------------- |
+| `args` | string[] | no       | Extension command args (passed through) |
 
 Notes:
 
@@ -1065,15 +1062,15 @@ Usage: `hack setup <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `cursor` | Install Cursor rules for hack CLI usage |
-| `claude` | Install Claude Code hooks for hack CLI usage |
-| `codex` | Install Codex skill for hack CLI usage |
-| `tickets` | Install Codex skill for hack tickets usage |
-| `agents` | Install AGENTS.md / CLAUDE.md snippets |
-| `sync` | Refresh agent docs, skills, and MCP configs |
-| `mcp` | Install MCP configs for hack CLI usage (no-shell only) |
+| Subcommand | Summary                                                |
+| ---------- | ------------------------------------------------------ |
+| `cursor`   | Install Cursor rules for hack CLI usage                |
+| `claude`   | Install Claude Code hooks for hack CLI usage           |
+| `codex`    | Install Codex skill for hack CLI usage                 |
+| `tickets`  | Install Codex skill for hack tickets usage             |
+| `agents`   | Install AGENTS.md / CLAUDE.md snippets                 |
+| `sync`     | Refresh agent docs, skills, and MCP configs            |
+| `mcp`      | Install MCP configs for hack CLI usage (no-shell only) |
 
 #### hack setup cursor
 
@@ -1081,12 +1078,12 @@ Usage: `hack setup cursor [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup claude
 
@@ -1094,12 +1091,12 @@ Usage: `hack setup claude [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup codex
 
@@ -1107,12 +1104,12 @@ Usage: `hack setup codex [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup agents
 
@@ -1120,14 +1117,14 @@ Usage: `hack setup agents [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported docs |
-| `--agents-md` | boolean | false | Target AGENTS.md |
-| `--claude-md` | boolean | false | Target CLAUDE.md |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean | false   | Target all supported docs                      |
+| `--agents-md`        | boolean | false   | Target AGENTS.md                               |
+| `--claude-md`        | boolean | false   | Target CLAUDE.md                               |
+| `--check`            | boolean | false   | Check whether integration is installed         |
+| `--remove`           | boolean | false   | Remove integration files/config                |
 
 #### hack setup sync
 
@@ -1135,13 +1132,13 @@ Usage: `hack setup sync [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Target global (user) scope only |
-| `--all-scopes` | boolean | false | Target both project and global (user) scopes |
-| `--check` | boolean | false | Check whether integrations are installed |
-| `--remove` | boolean | false | Remove generated integration files/config |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--global`           | boolean | false   | Target global (user) scope only                |
+| `--all-scopes`       | boolean | false   | Target both project and global (user) scopes   |
+| `--check`            | boolean | false   | Check whether integrations are installed       |
+| `--remove`           | boolean | false   | Remove generated integration files/config      |
 
 Automatic guardrail:
 
@@ -1154,16 +1151,16 @@ Usage: `hack setup mcp [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor integration |
-| `--claude` | boolean | false | Target Claude integration |
-| `--codex` | boolean | false | Target Codex integration |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--all`              | boolean | false   | Target all supported clients                     |
+| `--cursor`           | boolean | false   | Target Cursor integration                        |
+| `--claude`           | boolean | false   | Target Claude integration                        |
+| `--codex`            | boolean | false   | Target Codex integration                         |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 ### hack agent
 
@@ -1171,11 +1168,11 @@ Usage: `hack agent <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `prime` | Print agent primer text |
+| Subcommand | Summary                         |
+| ---------- | ------------------------------- |
+| `prime`    | Print agent primer text         |
 | `patterns` | Print agent init patterns guide |
-| `init` | Print agent init prompt |
+| `init`     | Print agent init prompt         |
 
 #### hack agent init
 
@@ -1183,10 +1180,10 @@ Usage: `hack agent init [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `-c`, `--client <cursor|claude|codex|print>` | string | - | Open init prompt in an agent client (or print) |
+| Flag                    | Type   | Default | Description                                    |
+| ----------------------- | ------ | ------- | ---------------------------------------------- | ------ | --- | ---------------------------------------------- |
+| `-p`, `--path <dir>`    | string | -       | Run against a repo path (overrides cwd search) |
+| `-c`, `--client <cursor | claude | codex   | print>`                                        | string | -   | Open init prompt in an agent client (or print) |
 
 ### hack mcp
 
@@ -1194,11 +1191,11 @@ Usage: `hack mcp <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `serve` | Run the MCP server over stdio |
-| `install` | Install MCP config for supported clients |
-| `print` | Print MCP config snippets |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `serve`    | Run the MCP server over stdio            |
+| `install`  | Install MCP config for supported clients |
+| `print`    | Print MCP config snippets                |
 
 #### hack mcp install
 
@@ -1206,17 +1203,17 @@ Usage: `hack mcp install [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <user|project>` | string | `user` | Write MCP config to user or project scope |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor MCP config |
-| `--claude` | boolean | false | Target Claude CLI MCP config |
-| `--codex` | boolean | false | Target Codex MCP config |
-| `--docs` | boolean | false | Update AGENTS.md and CLAUDE.md with hack usage |
-| `--agents-md` | boolean | false | Update AGENTS.md with hack usage |
-| `--claude-md` | boolean | false | Update CLAUDE.md with hack usage |
+| Flag                 | Type      | Default | Description                                    |
+| -------------------- | --------- | ------- | ---------------------------------------------- | ----------------------------------------- |
+| `--scope <user       | project>` | string  | `user`                                         | Write MCP config to user or project scope |
+| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean   | false   | Target all supported clients                   |
+| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
+| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
+| `--codex`            | boolean   | false   | Target Codex MCP config                        |
+| `--docs`             | boolean   | false   | Update AGENTS.md and CLAUDE.md with hack usage |
+| `--agents-md`        | boolean   | false   | Update AGENTS.md with hack usage               |
+| `--claude-md`        | boolean   | false   | Update CLAUDE.md with hack usage               |
 
 Notes:
 
@@ -1229,14 +1226,14 @@ Usage: `hack mcp print [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <user|project>` | string | `user` | Print MCP config for user or project scope |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor MCP config |
-| `--claude` | boolean | false | Target Claude CLI MCP config |
-| `--codex` | boolean | false | Target Codex MCP config |
+| Flag                 | Type      | Default | Description                                    |
+| -------------------- | --------- | ------- | ---------------------------------------------- | ------------------------------------------ |
+| `--scope <user       | project>` | string  | `user`                                         | Print MCP config for user or project scope |
+| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean   | false   | Target all supported clients                   |
+| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
+| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
+| `--codex`            | boolean   | false   | Target Codex MCP config                        |
 
 ## Diagnostics commands
 
@@ -1275,17 +1272,17 @@ Usage: `hack daemon <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `start` | Start hackd (local daemon) |
-| `stop` | Stop hackd |
-| `restart` | Restart hackd |
-| `status` | Show hackd status |
-| `metrics` | Show hackd metrics |
-| `logs` | Show hackd logs |
-| `clear` | Clear stale hackd pid/socket files |
-| `install` | Install hackd as a launchd service (macOS) |
-| `uninstall` | Uninstall hackd launchd service (macOS) |
+| Subcommand  | Summary                                    |
+| ----------- | ------------------------------------------ |
+| `start`     | Start hackd (local daemon)                 |
+| `stop`      | Stop hackd                                 |
+| `restart`   | Restart hackd                              |
+| `status`    | Show hackd status                          |
+| `metrics`   | Show hackd metrics                         |
+| `logs`      | Show hackd logs                            |
+| `clear`     | Clear stale hackd pid/socket files         |
+| `install`   | Install hackd as a launchd service (macOS) |
+| `uninstall` | Uninstall hackd launchd service (macOS)    |
 
 Autostart + self-heal behavior:
 
@@ -1302,9 +1299,9 @@ Usage: `hack daemon start [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--foreground` | boolean | false | Run hackd in the foreground (debug) |
+| Flag           | Type    | Default | Description                         |
+| -------------- | ------- | ------- | ----------------------------------- |
+| `--foreground` | boolean | false   | Run hackd in the foreground (debug) |
 
 #### hack daemon status
 
@@ -1312,9 +1309,9 @@ Usage: `hack daemon status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output JSON (machine-readable, includes launchd info on macOS) |
+| Flag     | Type    | Default | Description                                                    |
+| -------- | ------- | ------- | -------------------------------------------------------------- |
+| `--json` | boolean | false   | Output JSON (machine-readable, includes launchd info on macOS) |
 
 #### hack daemon logs
 
@@ -1322,35 +1319,32 @@ Usage: `hack daemon logs [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--tail <n>` | number | 200 | Tail last N log lines |
+| Flag         | Type   | Default | Description           |
+| ------------ | ------ | ------- | --------------------- |
+| `--tail <n>` | number | 200     | Tail last N log lines |
 
 #### hack daemon install
 
 Usage: `hack daemon install [options]`
 
-Installs hackd as a launchd service on macOS. The daemon will be managed by launchd
-and can optionally start automatically on login.
+Installs hackd as a launchd service on macOS. The daemon will be managed by launchd and can optionally start automatically on login.
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--run-at-load` | boolean | true | Start hackd automatically on login |
-| `--no-run-at-load` | boolean | - | Do not start hackd automatically on login |
-| `--gui-only` | boolean | true | Only run in GUI sessions (Aqua) |
-| `--no-gui-only` | boolean | - | Run in all session types (including SSH) |
+| Flag               | Type    | Default | Description                               |
+| ------------------ | ------- | ------- | ----------------------------------------- |
+| `--run-at-load`    | boolean | true    | Start hackd automatically on login        |
+| `--no-run-at-load` | boolean | -       | Do not start hackd automatically on login |
+| `--gui-only`       | boolean | true    | Only run in GUI sessions (Aqua)           |
+| `--no-gui-only`    | boolean | -       | Run in all session types (including SSH)  |
 
-The service uses the label `dance.hack.hackd` and writes its plist to
-`~/Library/LaunchAgents/dance.hack.hackd.plist`.
+The service uses the label `dance.hack.hackd` and writes its plist to `~/Library/LaunchAgents/dance.hack.hackd.plist`.
 
 #### hack daemon uninstall
 
 Usage: `hack daemon uninstall`
 
-Uninstalls the hackd launchd service on macOS. Removes the plist and unloads
-the service from launchd.
+Uninstalls the hackd launchd service on macOS. Removes the plist and unloads the service from launchd.
 
 ### hack log-pipe
 
@@ -1358,10 +1352,10 @@ Usage: `hack log-pipe [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--format <auto|docker-compose|plain>` | string | `auto` | How to parse incoming lines from stdin |
-| `--stream <stdout|stderr>` | string | `stdout` | Treat stdin as stdout or stderr |
+| Flag              | Type           | Default | Description |
+| ----------------- | -------------- | ------- | ----------- | ------------------------------- | -------------------------------------- |
+| `--format <auto   | docker-compose | plain>` | string      | `auto`                          | How to parse incoming lines from stdin |
+| `--stream <stdout | stderr>`       | string  | `stdout`    | Treat stdin as stdout or stderr |
 
 ### hack help
 
@@ -1369,9 +1363,9 @@ Usage: `hack help [path...]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `path` | string[] | no | Command path to show help for (e.g. `global logs`) |
+| Name   | Type     | Required | Description                                        |
+| ------ | -------- | -------- | -------------------------------------------------- |
+| `path` | string[] | no       | Command path to show help for (e.g. `global logs`) |
 
 ### hack update
 
@@ -1379,12 +1373,12 @@ Usage: `hack update [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--check` | boolean | false | Check for updates (do not install) |
-| `--yes` | boolean | false | Apply update without prompting |
-| `--tag <tag>` | string | - | Update to a specific release tag (e.g. v1.4.0) |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag          | Type    | Default | Description                                    |
+| ------------- | ------- | ------- | ---------------------------------------------- |
+| `--check`     | boolean | false   | Check for updates (do not install)             |
+| `--yes`       | boolean | false   | Apply update without prompting                 |
+| `--tag <tag>` | string  | -       | Update to a specific release tag (e.g. v1.4.0) |
+| `--json`      | boolean | false   | Output JSON (machine-readable)                 |
 
 ### hack version
 
@@ -1398,23 +1392,23 @@ Usage: `hack secrets <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `set` | Store a secret |
-| `get` | Print a secret (exit 1 if missing) |
-| `delete` | Delete a stored secret |
+| Subcommand | Summary                            |
+| ---------- | ---------------------------------- |
+| `set`      | Store a secret                     |
+| `get`      | Print a secret (exit 1 if missing) |
+| `delete`   | Delete a stored secret             |
 
 Options (all subcommands):
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| Flag                  | Type   | Default    | Description                       |
+| --------------------- | ------ | ---------- | --------------------------------- |
 | `--service <service>` | string | `hack-cli` | Override Bun.secrets service name |
 
 Arguments (set/get/delete):
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | no | Secret name (prompted if omitted) |
+| Name   | Type   | Required | Description                       |
+| ------ | ------ | -------- | --------------------------------- |
+| `name` | string | no       | Secret name (prompted if omitted) |
 
 ## Fun
 
@@ -1424,7 +1418,7 @@ Usage: `hack the planet [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--variant <cut|mash|cycle|random>` | string | `cycle` | Animation variant |
-| `--loop` | boolean | true | Loop until Ctrl+C |
+| Flag            | Type    | Default | Description       |
+| --------------- | ------- | ------- | ----------------- | ------ | ------- | ----------------- |
+| `--variant <cut | mash    | cycle   | random>`          | string | `cycle` | Animation variant |
+| `--loop`        | boolean | true    | Loop until Ctrl+C |
diff --git a/docs/extensions.md b/docs/extensions.md
index 05103107b..2a6155c37 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -1,7 +1,6 @@
 # Extensions & SDK (v0.1)
 
-This doc defines the extension surface area for `hack` and how extension commands are authored,
-configured, and dispatched.
+This doc defines the extension surface area for `hack` and how extension commands are authored, configured, and dispatched.
 
 ## Quick start (one command)
 
@@ -11,8 +10,7 @@ If you just want remote access working, start here:
 hack remote setup
 ```
 
-The wizard enables the gateway for the current project, creates a token + QR, and can configure
-Cloudflare/Tailscale/SSH exposure in one flow.
+The wizard enables the gateway for the current project, creates a token + QR, and can configure Cloudflare/Tailscale/SSH exposure in one flow.
 
 ## Behavior
 
@@ -20,8 +18,7 @@ Cloudflare/Tailscale/SSH exposure in one flow.
 - Each extension provides a manifest + commands (`ExtensionDefinition`).
 - The CLI dispatches extension commands via `hack x <namespace> <command>`.
 - Global enablement lives in `~/.hack/hack.config.json` (`hack config set --global ...`).
-- Per-project overrides live in `.hack/hack.config.json` and typically win over global values
-  (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
+- Per-project overrides live in `.hack/hack.config.json` and typically win over global values (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
 - Built-in Gateway enablement is project-scoped: `controlPlane.gateway.enabled` opts a project into routing.
 
 ## Extension definition (API surface)
@@ -47,14 +44,14 @@ export type ExtensionCommand = {
 ```
 
 The `ExtensionCommandContext` includes:
+
 - `controlPlaneConfig` (parsed config)
 - `projectId` and `projectName` (when available)
 - `logger` and `cwd`
 
 ## Config + enablement
 
-Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by
-`src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
+Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by `src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
 
 Enable a global extension by id:
 
@@ -78,10 +75,10 @@ Shortcut for gateway (project-scoped):
 }
 ```
 
-Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config.
-Project overrides for these are ignored.
+Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config. Project overrides for these are ignored.
 
 CLI helpers:
+
 - `hack gateway enable` (sets both gateway + extension flags)
 - `hack gateway setup` (guided enable + optional writes + token creation + QR by default)
 - `hack config set --global 'controlPlane.extensions[\"dance.hack.gateway\"].enabled' true`
@@ -106,10 +103,10 @@ Use `hack x <namespace> help` to list commands.
 - GitHub: `hack x github connect|oauth-connect|disconnect|profiles|use|status|pr-upsert`
 - Linear: `hack x linear setup|connect|oauth-connect|disconnect|status|profiles|use|projects|project-bind|sync-issue|sync-project`
 
-Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also
-requires global `controlPlane.gateway.allowWrites = true`).
+Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also requires global `controlPlane.gateway.allowWrites = true`).
 
 Current gateway API surface (HTTP/WS):
+
 - `GET /v1/status`, `GET /v1/metrics`, `GET /v1/projects`, `GET /v1/ps`
 - `GET/POST /control-plane/projects/:id/jobs`
 - `GET /control-plane/projects/:id/jobs/:jobId`
@@ -120,6 +117,7 @@ Current gateway API surface (HTTP/WS):
 - `WS /control-plane/projects/:id/shells/:shellId/stream` (requires write token + allowWrites)
 
 Local auth service surface (daemon + global Caddy route):
+
 - `GET /health`
 - `GET /v1/auth/providers`
 - `GET /gh/start` (GitHub browser OAuth entrypoint)
@@ -128,15 +126,14 @@ Local auth service surface (daemon + global Caddy route):
 - `GET /v1/auth/github/start`
 - `GET /v1/auth/github/flows/:id`
 
-Interactive shell/TTY is available via the shell stream endpoints; use
-`hack x supervisor shell` or see protocol below.
+Interactive shell/TTY is available via the shell stream endpoints; use `hack x supervisor shell` or see protocol below.
 
 For full usage guidance and structured workflow patterns, see `gateway-api.md`.
 
 For exposure helpers, see the guides:
+
 - `guides/remote-cloudflare.md`
-- `guides/remote-tailscale.md`
-DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
+- `guides/remote-tailscale.md` DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
 
 ## Command reference
 
@@ -148,13 +145,14 @@ Usage: `hack x gateway token-create [options] [label]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <read|write>` | string | `read` | Token scope |
-| `--write` | boolean | false | Shortcut for `--scope write` |
-| `--label <label>` | string | - | Optional label |
+| Flag              | Type    | Default | Description                  |
+| ----------------- | ------- | ------- | ---------------------------- | ----------- |
+| `--scope <read    | write>` | string  | `read`                       | Token scope |
+| `--write`         | boolean | false   | Shortcut for `--scope write` |
+| `--label <label>` | string  | -       | Optional label               |
 
 Notes:
+
 - The first non-flag argument is treated as the label if `--label` is not used.
 
 #### token-list
@@ -175,11 +173,11 @@ Usage: `hack x supervisor job-list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-create
 
@@ -187,14 +185,14 @@ Usage: `hack x supervisor job-create [options] -- <command...>`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--runner <name>` | string | `generic` | Runner name |
-| `--cwd <path>` | string | - | Working directory (relative to project root) |
-| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
-| `--json` | boolean | false | Output JSON |
+| Flag                | Type    | Default   | Description                                  |
+| ------------------- | ------- | --------- | -------------------------------------------- |
+| `--project <name>`  | string  | -         | Target a registered project                  |
+| `--path <dir>`      | string  | -         | Target a repo path                           |
+| `--runner <name>`   | string  | `generic` | Runner name                                  |
+| `--cwd <path>`      | string  | -         | Working directory (relative to project root) |
+| `--env <KEY=VALUE>` | string  | -         | Environment override (repeatable)            |
+| `--json`            | boolean | false     | Output JSON                                  |
 
 ### GitHub extension (`hack x github`)
 
@@ -257,10 +255,9 @@ hack x github pr-upsert \
 ```
 
 Notes:
-- Profile config lives at:
-  `controlPlane.extensions["dance.hack.github"].config.profiles`.
-- Profile selection precedence is:
-  `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
+
+- Profile config lives at: `controlPlane.extensions["dance.hack.github"].config.profiles`.
+- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
 - Keychain storage uses profile-specific `authRef` + `service`.
 - Token resolution order is keychain first, then environment fallback (`tokenEnv`).
 - If token metadata includes `expiresAt`, auth resolution attempts automatic GitHub App refresh using profile `appId`, `installationId`, and private key source.
@@ -339,8 +336,7 @@ Detailed design and sequencing live in:
 
 ### Linear extension (`hack x linear`)
 
-Linear integration supports multiple auth profiles, project-level binding, and manual sync in both
-directions between Linear issues and hack tickets.
+Linear integration supports multiple auth profiles, project-level binding, and manual sync in both directions between Linear issues and hack tickets.
 
 Quick start:
 
@@ -363,11 +359,9 @@ hack x linear sync-project --from hack --owner both
 ```
 
 Notes:
-- Profile selection precedence is:
-  `--profile` -> `controlPlane.routing.overrides.linear.profile` ->
-  `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
-- Project mapping is stored in project config:
-  `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
+
+- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.linear.profile` -> `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
+- Project mapping is stored in project config: `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
 - Sync is manual by default (`sync-issue` / `sync-project`); there is no background autosync yet.
 - Ticket provenance is preserved during sync via `owner`, `source`, `tags`, and `external*` linkage fields.
 - `hack x linear connect` uses token mode when `--token`/`--stdin`/`$HACK_LINEAR_API_TOKEN` is present, and otherwise falls back to browser OAuth.
@@ -380,8 +374,7 @@ Notes:
 - Auth-broker Linear endpoints:
   - OAuth callback page: `/linear/callback`
   - Webhook ingest: `/linear/webhooks` (legacy alias: `/v1/integrations/linear/webhook`)
-- Sync toggles are configurable at
-  `controlPlane.extensions["dance.hack.linear"].config.sync`:
+- Sync toggles are configurable at `controlPlane.extensions["dance.hack.linear"].config.sync`:
   - `labels` (default `false`)
   - `statuses` (default `true`)
   - `dependencies` (default `true`)
@@ -394,11 +387,11 @@ Usage: `hack x supervisor job-show <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-cancel
 
@@ -406,10 +399,10 @@ Usage: `hack x supervisor job-cancel <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
+| Flag               | Type   | Default | Description                 |
+| ------------------ | ------ | ------- | --------------------------- |
+| `--project <name>` | string | -       | Target a registered project |
+| `--path <dir>`     | string | -       | Target a repo path          |
 
 #### job-tail
 
@@ -417,15 +410,15 @@ Usage: `hack x supervisor job-tail <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--logs-from <n>` | number | 0 | Resume from log offset |
-| `--from <n>` | number | 0 | Alias for `--logs-from` |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--follow`         | boolean | true    | Follow logs (default)       |
+| `--no-follow`      | boolean | false   | Print logs and exit         |
+| `--logs-from <n>`  | number  | 0       | Resume from log offset      |
+| `--from <n>`       | number  | 0       | Alias for `--logs-from`     |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-attach
 
@@ -433,16 +426,16 @@ Usage: `hack x supervisor job-attach <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--logs-from <n>` | number | 0 | Resume from log offset |
-| `--from <n>` | number | 0 | Alias for `--logs-from` |
-| `--events-from <n>` | number | 0 | Resume from event sequence |
-| `--json` | boolean | false | Output JSON |
+| Flag                | Type    | Default | Description                 |
+| ------------------- | ------- | ------- | --------------------------- |
+| `--project <name>`  | string  | -       | Target a registered project |
+| `--path <dir>`      | string  | -       | Target a repo path          |
+| `--follow`          | boolean | true    | Follow logs (default)       |
+| `--no-follow`       | boolean | false   | Print logs and exit         |
+| `--logs-from <n>`   | number  | 0       | Resume from log offset      |
+| `--from <n>`        | number  | 0       | Alias for `--logs-from`     |
+| `--events-from <n>` | number  | 0       | Resume from event sequence  |
+| `--json`            | boolean | false   | Output JSON                 |
 
 #### shell
 
@@ -450,20 +443,21 @@ Usage: `hack x supervisor shell [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--project-id <id>` | string | - | Target by project id (gateway) |
-| `--path <dir>` | string | - | Target a repo path |
-| `--gateway <url>` | string | `http://127.0.0.1:7788` | Gateway URL |
-| `--token <token>` | string | - | Gateway write token |
-| `--shell <path>` | string | - | Shell path |
-| `--cwd <path>` | string | - | Working directory |
-| `--cols <n>` | number | - | Terminal columns |
-| `--rows <n>` | number | - | Terminal rows |
-| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
+| Flag                | Type   | Default                 | Description                       |
+| ------------------- | ------ | ----------------------- | --------------------------------- |
+| `--project <name>`  | string | -                       | Target a registered project       |
+| `--project-id <id>` | string | -                       | Target by project id (gateway)    |
+| `--path <dir>`      | string | -                       | Target a repo path                |
+| `--gateway <url>`   | string | `http://127.0.0.1:7788` | Gateway URL                       |
+| `--token <token>`   | string | -                       | Gateway write token               |
+| `--shell <path>`    | string | -                       | Shell path                        |
+| `--cwd <path>`      | string | -                       | Working directory                 |
+| `--cols <n>`        | number | -                       | Terminal columns                  |
+| `--rows <n>`        | number | -                       | Terminal rows                     |
+| `--env <KEY=VALUE>` | string | -                       | Environment override (repeatable) |
 
 Notes:
+
 - `--project` and `--project-id` are mutually exclusive.
 
 ### Cloudflare extension (`hack x cloudflare`)
@@ -474,15 +468,15 @@ Usage: `hack x cloudflare tunnel-print [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--hostname <host>` | string | - | Gateway hostname |
-| `--tunnel <name>` | string | `hack-gateway` | Tunnel name |
-| `--origin <url>` | string | `http://127.0.0.1:7788` | Gateway origin |
-| `--ssh-hostname <host>` | string | - | SSH hostname (optional) |
-| `--ssh-origin <url>` | string | `ssh://127.0.0.1:22` | SSH origin |
-| `--credentials-file <path>` | string | - | Cloudflared credentials file |
-| `--out <path>` | string | - | Write config to a file |
+| Flag                        | Type   | Default                 | Description                  |
+| --------------------------- | ------ | ----------------------- | ---------------------------- |
+| `--hostname <host>`         | string | -                       | Gateway hostname             |
+| `--tunnel <name>`           | string | `hack-gateway`          | Tunnel name                  |
+| `--origin <url>`            | string | `http://127.0.0.1:7788` | Gateway origin               |
+| `--ssh-hostname <host>`     | string | -                       | SSH hostname (optional)      |
+| `--ssh-origin <url>`        | string | `ssh://127.0.0.1:22`    | SSH origin                   |
+| `--credentials-file <path>` | string | -                       | Cloudflared credentials file |
+| `--out <path>`              | string | -                       | Write config to a file       |
 
 #### tunnel-setup
 
@@ -509,11 +503,11 @@ Usage: `hack x cloudflare tunnel-start [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path |
-| `--out <path>` | string | - | Alias for `--config` |
-| `--tunnel <name>` | string | - | Override tunnel name |
+| Flag              | Type   | Default                     | Description          |
+| ----------------- | ------ | --------------------------- | -------------------- |
+| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path          |
+| `--out <path>`    | string | -                           | Alias for `--config` |
+| `--tunnel <name>` | string | -                           | Override tunnel name |
 
 #### tunnel-stop
 
@@ -525,10 +519,10 @@ Usage: `hack x cloudflare access-setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--ssh-hostname <host>` | string | - | SSH hostname |
-| `--user <user>` | string | - | SSH username |
+| Flag                    | Type   | Default | Description  |
+| ----------------------- | ------ | ------- | ------------ |
+| `--ssh-hostname <host>` | string | -       | SSH hostname |
+| `--user <user>`         | string | -       | SSH username |
 
 ### Tailscale extension (`hack x tailscale`)
 
@@ -561,6 +555,7 @@ Usage: `hack x tailscale oauth-disconnect [--auth-ref <ref>] [--json]`
 Usage: `hack x tailscale ip [args...]`
 
 Notes:
+
 - `status` and `ip` forward extra args directly to `tailscale`.
 - `ip` defaults to `-4` when no args are provided.
 
@@ -609,17 +604,18 @@ The gateway binds to `127.0.0.1` by default. Expose it through one of:
 - SSH tunnel (ad‑hoc): `ssh -L 7788:127.0.0.1:7788 <host>`
 - Zero Trust/VPN (persistent): Tailscale, Cloudflare, etc. targeting the gateway port
 - Optional Caddy route for local convenience (`https://gateway.hack`):
-  - Add a small labeled container in the global Caddy compose that proxies to
-    `host.docker.internal:7788` (or `host-gateway` on Linux).
+  - Add a small labeled container in the global Caddy compose that proxies to `host.docker.internal:7788` (or `host-gateway` on Linux).
 
 Keep tokens read-only unless you explicitly need writes.
 
 Recommended order:
-1) Start with SSH tunneling for quick remote access.
-2) Move to a private Zero Trust/VPN network once you want persistent access.
-3) Add the Caddy route only for nicer local URLs (not required for remote access).
+
+1. Start with SSH tunneling for quick remote access.
+2. Move to a private Zero Trust/VPN network once you want persistent access.
+3. Add the Caddy route only for nicer local URLs (not required for remote access).
 
 Remote helper commands:
+
 - `hack remote status` shows gateway + exposure status.
 - `hack remote qr` emits QR payloads for SSH or gateway clients.
 
@@ -653,7 +649,7 @@ Server → client:
 
 ```
 {"type":"ready","shellId":"...","cols":120,"rows":30,"cwd":"/repo","shell":"/bin/zsh","status":"running"}
-{"type":"output","data":"..."} 
+{"type":"output","data":"..."}
 {"type":"exit","exitCode":0,"signal":null}
 ```
 

From 7f8cb4dd3dbde2cd3bfe090221e64cf92b3e6fee Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 18:50:40 +0000
Subject: [PATCH 074/134] docs: restore markdown table formatting

---
 docs/cli.md        | 832 +++++++++++++++++++++++----------------------
 docs/extensions.md | 216 ++++++------
 2 files changed, 529 insertions(+), 519 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 61e0c0e35..247f0f85c 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,6 +1,7 @@
 # CLI Reference
 
-This reference mirrors the CLI spec in `src/cli/spec.ts`. Run `hack help` or `hack help <command>` for interactive help.
+This reference mirrors the CLI spec in `src/cli/spec.ts`.
+Run `hack help` or `hack help <command>` for interactive help.
 
 ## Conventions
 
@@ -60,17 +61,17 @@ Usage: `hack global <subcommand>`
 
 Subcommands:
 
-| Subcommand   | Summary                                                      |
-| ------------ | ------------------------------------------------------------ | ------- | ---- | ------ |
-| `install`    | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy     |
-| `up`         | Start global infra containers                                |
-| `down`       | Stop global infra containers                                 |
-| `status`     | Show status for global infra (containers + networks)         |
-| `logs`       | Tail global infra logs (caddy                                | grafana | loki | alloy) |
-| `ca`         | Export Caddy Local CA cert (print path or PEM)               |
-| `cert`       | Generate local TLS certs via mkcert (for non-Caddy services) |
-| `trust`      | Trust Caddy Local CA (macOS) so https://\*.hack is trusted   |
-| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards)          |
+| Subcommand | Summary |
+| --- | --- |
+| `install` | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy |
+| `up` | Start global infra containers |
+| `down` | Stop global infra containers |
+| `status` | Show status for global infra (containers + networks) |
+| `logs` | Tail global infra logs (caddy|grafana|loki|alloy) |
+| `ca` | Export Caddy Local CA cert (print path or PEM) |
+| `cert` | Generate local TLS certs via mkcert (for non-Caddy services) |
+| `trust` | Trust Caddy Local CA (macOS) so https://*.hack is trusted |
+| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards) |
 
 #### hack global logs
 
@@ -78,18 +79,18 @@ Usage: `hack global logs [service] [options]`
 
 Arguments:
 
-| Name      | Type   | Required | Description                                                |
-| --------- | ------ | -------- | ---------------------------------------------------------- |
-| `service` | string | no       | Filter to one global service (caddy, grafana, loki, alloy) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `service` | string | no | Filter to one global service (caddy, grafana, loki, alloy) |
 
 Options:
 
-| Flag             | Type    | Default | Description                                               |
-| ---------------- | ------- | ------- | --------------------------------------------------------- |
-| `-f`, `--follow` | boolean | true    | Follow logs (default)                                     |
-| `--no-follow`    | boolean | false   | Print logs and exit                                       |
-| `--tail <n>`     | number  | 200     | Tail last N log lines                                     |
-| `--pretty`       | boolean | false   | Pretty-print logs (best-effort JSON parsing + formatting) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-f`, `--follow` | boolean | true | Follow logs (default) |
+| `--no-follow` | boolean | false | Print logs and exit |
+| `--tail <n>` | number | 200 | Tail last N log lines |
+| `--pretty` | boolean | false | Pretty-print logs (best-effort JSON parsing + formatting) |
 
 #### hack global ca
 
@@ -97,9 +98,9 @@ Usage: `hack global ca [options]`
 
 Options:
 
-| Flag      | Type    | Default | Description                                                    |
-| --------- | ------- | ------- | -------------------------------------------------------------- |
-| `--print` | boolean | false   | Print the CA cert PEM to stdout (instead of printing its path) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--print` | boolean | false | Print the CA cert PEM to stdout (instead of printing its path) |
 
 #### hack global cert
 
@@ -107,16 +108,16 @@ Usage: `hack global cert <hosts...> [options]`
 
 Arguments:
 
-| Name    | Type     | Required | Description                                 |
-| ------- | -------- | -------- | ------------------------------------------- |
-| `hosts` | string[] | yes      | One or more hostnames to generate certs for |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `hosts` | string[] | yes | One or more hostnames to generate certs for |
 
 Options:
 
-| Flag          | Type    | Default         | Description                                 |
-| ------------- | ------- | --------------- | ------------------------------------------- |
-| `--install`   | boolean | false           | Run mkcert -install before generating certs |
-| `--out <dir>` | string  | `~/.hack/certs` | Directory for generated cert/key            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--install` | boolean | false | Run mkcert -install before generating certs |
+| `--out <dir>` | string | `~/.hack/certs` | Directory for generated cert/key |
 
 ### hack projects
 
@@ -141,9 +142,9 @@ Usage: `hack projects prune [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                                   |
-| ------------------ | ------- | ------- | --------------------------------------------- |
-| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
 
 ### hack status
 
@@ -151,12 +152,12 @@ Usage: `hack status [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                                   |
-| ------------------ | ------- | ------- | --------------------------------------------- |
-| `--project <name>` | string  | -       | Filter to a registered project name           |
-| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
-| `--all`            | boolean | false   | Include unregistered docker compose projects  |
-| `--json`           | boolean | false   | Output JSON (machine-readable)                |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Filter to a registered project name |
+| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
+| `--all` | boolean | false | Include unregistered docker compose projects |
+| `--json` | boolean | false | Output JSON (machine-readable) |
 
 ### hack usage
 
@@ -199,13 +200,13 @@ Usage: `hack up [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `-d`, `--detach` | boolean | false | Run in background (docker compose up -d) |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack down
 
@@ -214,12 +215,12 @@ Usage: `hack down [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack restart
 
@@ -228,12 +229,12 @@ Usage: `hack restart [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack ps
 
@@ -255,9 +256,9 @@ Usage: `hack logs [service] [options]`
 
 Arguments:
 
-| Name      | Type   | Required | Description                                        |
-| --------- | ------ | -------- | -------------------------------------------------- |
-| `service` | string | no       | Filter logs by service (shortcut for `--services`) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `service` | string | no | Filter logs by service (shortcut for `--services`) |
 
 Options:
 
@@ -291,10 +292,10 @@ Usage: `hack run <service> [-- <cmd...>] [options]`
 
 Arguments:
 
-| Name      | Type     | Required | Description                                     |
-| --------- | -------- | -------- | ----------------------------------------------- |
-| `service` | string   | yes      | Compose service name                            |
-| `cmd`     | string[] | no       | Command to run (defaults to service entrypoint) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `service` | string | yes | Compose service name |
+| `cmd` | string[] | no | Command to run (defaults to service entrypoint) |
 
 Options:
 
@@ -312,18 +313,18 @@ Usage: `hack open [target] [options]`
 
 Arguments:
 
-| Name     | Type   | Required | Description                                         |
-| -------- | ------ | -------- | --------------------------------------------------- |
-| `target` | string | no       | `www` (default), `logs`, a subdomain, or a full URL |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `target` | string | no | `www` (default), `logs`, a subdomain, or a full URL |
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string  | -       | Target a registered project by name            |
-| `--branch <name>`    | string  | -       | Run against a branch-specific instance         |
-| `--json`             | boolean | false   | Output JSON with `{ "url": "..." }`            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--branch <name>` | string | - | Run against a branch-specific instance |
+| `--json` | boolean | false | Output JSON with `{ "url": "..." }` |
 
 Notes:
 
@@ -338,10 +339,10 @@ Usage: `hack tui [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 Notes:
 
@@ -353,12 +354,12 @@ Usage: `hack branch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                  |
-| ---------- | ---------------------------------------- |
-| `add`      | Register a branch alias for this project |
-| `list`     | List registered branch aliases           |
-| `remove`   | Remove a branch alias                    |
-| `open`     | Open the branch host in a browser        |
+| Subcommand | Summary |
+| --- | --- |
+| `add` | Register a branch alias for this project |
+| `list` | List registered branch aliases |
+| `remove` | Remove a branch alias |
+| `open` | Open the branch host in a browser |
 
 #### hack branch add
 
@@ -366,17 +367,17 @@ Usage: `hack branch add <name> [options]`
 
 Arguments:
 
-| Name   | Type   | Required | Description          |
-| ------ | ------ | -------- | -------------------- |
-| `name` | string | yes      | Branch name or alias |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | yes | Branch name or alias |
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
-| `--note <text>`      | string | -       | Optional note for the branch entry             |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--note <text>` | string | - | Optional note for the branch entry |
 
 #### hack branch list
 
@@ -384,10 +385,10 @@ Usage: `hack branch list [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack branch remove
 
@@ -395,16 +396,16 @@ Usage: `hack branch remove <name> [options]`
 
 Arguments:
 
-| Name   | Type   | Required | Description          |
-| ------ | ------ | -------- | -------------------- |
-| `name` | string | yes      | Branch name or alias |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | yes | Branch name or alias |
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack branch open
 
@@ -412,16 +413,16 @@ Usage: `hack branch open <name> [options]`
 
 Arguments:
 
-| Name   | Type   | Required | Description          |
-| ------ | ------ | -------- | -------------------- |
-| `name` | string | yes      | Branch name or alias |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | yes | Branch name or alias |
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 ### hack config
 
@@ -429,10 +430,10 @@ Usage: `hack config <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                            |
-| ---------- | ---------------------------------- |
-| `get`      | Read a value from hack.config.json |
-| `set`      | Update a value in hack.config.json |
+| Subcommand | Summary |
+| --- | --- |
+| `get` | Read a value from hack.config.json |
+| `set` | Update a value in hack.config.json |
 
 #### hack config get
 
@@ -440,17 +441,17 @@ Usage: `hack config get <key> [options]`
 
 Arguments:
 
-| Name  | Type   | Required | Description                             |
-| ----- | ------ | -------- | --------------------------------------- |
-| `key` | string | yes      | Dot path (e.g. `logs.snapshot_backend`) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string  | -       | Target a registered project by name            |
-| `--global`           | boolean | false   | Read global `~/.hack/hack.config.json`         |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--global` | boolean | false | Read global `~/.hack/hack.config.json` |
 
 #### hack config set
 
@@ -458,18 +459,18 @@ Usage: `hack config set <key> <value> [options]`
 
 Arguments:
 
-| Name    | Type   | Required | Description                                          |
-| ------- | ------ | -------- | ---------------------------------------------------- |
-| `key`   | string | yes      | Dot path (e.g. `logs.snapshot_backend`)              |
-| `value` | string | yes      | JSON value or raw string (parsed as JSON when valid) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
+| `value` | string | yes | JSON value or raw string (parsed as JSON when valid) |
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string  | -       | Target a registered project by name            |
-| `--global`           | boolean | false   | Write global `~/.hack/hack.config.json`        |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--global` | boolean | false | Write global `~/.hack/hack.config.json` |
 
 ### hack env
 
@@ -477,12 +478,12 @@ Usage: `hack env <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                            |
-| ---------- | -------------------------------------------------- |
-| `list`     | List env contract vars and resolution state        |
-| `set`      | Set an env value (.hack/.env or secret backend)    |
-| `unset`    | Unset an env value (.hack/.env and secret backend) |
-| `backend`  | Manage env/secret backend strategy                 |
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List env contract vars and resolution state |
+| `set` | Set an env value (.hack/.env or secret backend) |
+| `unset` | Unset an env value (.hack/.env and secret backend) |
+| `backend` | Manage env/secret backend strategy |
 
 #### hack env list
 
@@ -490,12 +491,12 @@ Usage: `hack env list [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                       |
-| -------------------- | ------- | ------- | ------------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)    |
-| `--project <name>`   | string  | -       | Target a registered project by name               |
-| `--json`             | boolean | false   | Output JSON (machine-readable)                    |
-| `--show-secrets`     | boolean | false   | Print secret values (secret backend) in plaintext |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--show-secrets` | boolean | false | Print secret values (secret backend) in plaintext |
 
 #### hack env set
 
@@ -517,10 +518,10 @@ Usage: `hack env unset [key] [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack env backend
 
@@ -528,10 +529,10 @@ Usage: `hack env backend <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                     |
-| ---------- | ------------------------------------------- |
-| `status`   | Show configured env/secret backend strategy |
-| `use`      | Select env/secret backend strategy          |
+| Subcommand | Summary |
+| --- | --- |
+| `status` | Show configured env/secret backend strategy |
+| `use` | Select env/secret backend strategy |
 
 #### hack env backend status
 
@@ -539,9 +540,9 @@ Usage: `hack env backend status [options]`
 
 Options:
 
-| Flag     | Type    | Default | Description                    |
-| -------- | ------- | ------- | ------------------------------ |
-| `--json` | boolean | false   | Output JSON (machine-readable) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
 
 #### hack env backend use
 
@@ -550,8 +551,8 @@ Usage: `hack env backend use <keychain|encrypted_file|cloud> [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- | --- |
-| `--provider <aws | gcp | azure | vault>` | string | - | Cloud provider when backend is `cloud` |
+| --- | --- | --- | --- |
+| `--provider <aws|gcp|azure|vault>` | string | - | Cloud provider when backend is `cloud` |
 | `--store-path <path>` | string | - | Encrypted file path when backend is `encrypted_file` |
 | `--secret-project <id>` | string | - | Optional cloud account/project identifier |
 | `--secret-prefix <prefix>` | string | - | Optional cloud secret name prefix |
@@ -565,16 +566,16 @@ With no subcommand, opens an interactive picker of active sessions and available
 
 Subcommands:
 
-| Subcommand | Summary                                    |
-| ---------- | ------------------------------------------ |
-| `list`     | List active sessions                       |
-| `start`    | Start or attach to a session for a project |
-| `stop`     | Stop (kill) a session                      |
-| `attach`   | Attach to an existing session              |
-| `exec`     | Execute a command in a session             |
-| `panes`    | List panes in a tmux session               |
-| `capture`  | Capture recent output from a tmux session  |
-| `tail`     | Tail output from a tmux session            |
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List active sessions |
+| `start` | Start or attach to a session for a project |
+| `stop` | Stop (kill) a session |
+| `attach` | Attach to an existing session |
+| `exec` | Execute a command in a session |
+| `panes` | List panes in a tmux session |
+| `capture` | Capture recent output from a tmux session |
+| `tail` | Tail output from a tmux session |
 
 #### hack session start
 
@@ -582,11 +583,11 @@ Usage: `hack session start [project] [options]`
 
 Options:
 
-| Flag              | Type    | Default | Description                                   |
-| ----------------- | ------- | ------- | --------------------------------------------- |
-| `--up`            | boolean | false   | Run hack up -d before attaching               |
-| `--new`           | boolean | false   | Force create new session even if one exists   |
-| `--name <suffix>` | string  | -       | Custom suffix for new session (e.g., agent-1) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--up` | boolean | false | Run hack up -d before attaching |
+| `--new` | boolean | false | Force create new session even if one exists |
+| `--name <suffix>` | string | - | Custom suffix for new session (e.g., agent-1) |
 
 #### hack session panes
 
@@ -594,10 +595,10 @@ Usage: `hack session panes <session> [options]`
 
 Options:
 
-| Flag       | Type    | Default | Description                          |
-| ---------- | ------- | ------- | ------------------------------------ |
-| `--json`   | boolean | false   | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false   | Output human-friendly text           |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false | Output human-friendly text |
 
 #### hack session capture
 
@@ -605,12 +606,12 @@ Usage: `hack session capture <session> [options]`
 
 Options:
 
-| Flag                | Type    | Default | Description                             |
-| ------------------- | ------- | ------- | --------------------------------------- |
-| `--target <target>` | string  | -       | Tmux pane target (default: active pane) |
-| `--lines <n>`       | number  | 200     | Number of lines to capture              |
-| `--json`            | boolean | false   | Output NDJSON stream (start/log/end)    |
-| `--pretty`          | boolean | false   | Output human-friendly text              |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--target <target>` | string | - | Tmux pane target (default: active pane) |
+| `--lines <n>` | number | 200 | Number of lines to capture |
+| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false | Output human-friendly text |
 
 #### hack session tail
 
@@ -618,14 +619,14 @@ Usage: `hack session tail <session> [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                             |
-| -------------------- | ------- | ------- | --------------------------------------- |
-| `--target <target>`  | string  | -       | Tmux pane target (default: active pane) |
-| `--lines <n>`        | number  | 200     | Number of lines to capture              |
-| `--interval-ms <ms>` | number  | 500     | Polling interval in milliseconds        |
-| `--max-ms <ms>`      | number  | 5000    | Stop tailing after N milliseconds       |
-| `--json`             | boolean | false   | Output NDJSON stream (start/log/end)    |
-| `--pretty`           | boolean | false   | Output human-friendly text              |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--target <target>` | string | - | Tmux pane target (default: active pane) |
+| `--lines <n>` | number | 200 | Number of lines to capture |
+| `--interval-ms <ms>` | number | 500 | Polling interval in milliseconds |
+| `--max-ms <ms>` | number | 5000 | Stop tailing after N milliseconds |
+| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false | Output human-friendly text |
 
 ### hack ssh
 
@@ -633,25 +634,27 @@ Usage: `hack ssh [session] [options]`
 
 Options:
 
-| Flag                  | Type    | Default | Description                                  |
-| --------------------- | ------- | ------- | -------------------------------------------- |
-| `-H`, `--host <host>` | string  | -       | SSH host (hostname or IP)                    |
-| `-u`, `--user <user>` | string  | -       | SSH username                                 |
-| `-t`, `--tailscale`   | boolean | false   | Use Tailscale SSH                            |
-| `-d`, `--direct`      | boolean | false   | Use direct SSH (requires --host)             |
-| `-p`, `--port <port>` | string  | -       | SSH port for direct connection (default: 22) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-H`, `--host <host>` | string | - | SSH host (hostname or IP) |
+| `-u`, `--user <user>` | string | - | SSH username |
+| `-t`, `--tailscale` | boolean | false | Use Tailscale SSH |
+| `-d`, `--direct` | boolean | false | Use direct SSH (requires --host) |
+| `-p`, `--port <port>` | string | - | SSH port for direct connection (default: 22) |
 
 ### hack tickets
 
 Usage: `hack tickets <args...>`
 
-`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`). Run `hack tickets` with no args to see available subcommands.
+`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`).
+Run `hack tickets` with no args to see available subcommands.
 
 ### hack linear
 
 Usage: `hack linear <args...>`
 
-`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`). Run `hack linear` with no args to see available subcommands.
+`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`).
+Run `hack linear` with no args to see available subcommands.
 
 ## Internal commands
 
@@ -661,8 +664,8 @@ Usage: `hack internal <subcommand>`
 
 Subcommands:
 
-| Subcommand    | Summary                             |
-| ------------- | ----------------------------------- |
+| Subcommand | Summary |
+| --- | --- |
 | `extra-hosts` | Manage internal Compose extra_hosts |
 
 #### hack internal extra-hosts
@@ -671,17 +674,17 @@ Usage: `hack internal extra-hosts <subcommand> [options]`
 
 Options:
 
-| Flag                  | Type   | Default | Description                       |
-| --------------------- | ------ | ------- | --------------------------------- |
-| `-p`, `--path <path>` | string | -       | Start directory (defaults to cwd) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <path>` | string | - | Start directory (defaults to cwd) |
 
 Subcommands:
 
-| Subcommand | Summary                              |
-| ---------- | ------------------------------------ |
-| `set`      | Set an internal extra_hosts entry    |
-| `unset`    | Remove an internal extra_hosts entry |
-| `list`     | List internal extra_hosts entries    |
+| Subcommand | Summary |
+| --- | --- |
+| `set` | Set an internal extra_hosts entry |
+| `unset` | Remove an internal extra_hosts entry |
+| `list` | List internal extra_hosts entries |
 
 #### hack internal extra-hosts set
 
@@ -703,11 +706,11 @@ Usage: `hack gateway <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                   |
-| ---------- | ----------------------------------------- |
-| `enable`   | Enable the gateway and start hackd        |
-| `setup`    | Guided gateway setup (enable + token)     |
-| `disable`  | Disable the gateway (does not stop hackd) |
+| Subcommand | Summary |
+| --- | --- |
+| `enable` | Enable the gateway and start hackd |
+| `setup` | Guided gateway setup (enable + token) |
+| `disable` | Disable the gateway (does not stop hackd) |
 
 #### hack gateway enable
 
@@ -715,10 +718,10 @@ Usage: `hack gateway enable [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack gateway setup
 
@@ -726,13 +729,13 @@ Usage: `hack gateway setup [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                         |
-| -------------------- | ------- | ------- | --------------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
-| `--project <name>`   | string  | -       | Target a registered project by name                 |
-| `--qr`               | boolean | true    | Force QR output after setup (default)               |
-| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
-| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--qr` | boolean | true | Force QR output after setup (default) |
+| `--no-qr` | boolean | false | Skip QR output after setup |
+| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
 
 #### hack gateway disable
 
@@ -740,10 +743,10 @@ Usage: `hack gateway disable [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 ### hack node
 
@@ -751,20 +754,20 @@ Usage: `hack node <subcommand>`
 
 Subcommands:
 
-| Subcommand     | Summary                                                       |
-| -------------- | ------------------------------------------------------------- |
-| `init`         | Initialize this host as a node and emit enrollment bundle     |
-| `pair`         | Pair node with one-command or expiring verification-code flow |
-| `ssh`          | Manage SSH bootstrap for node pairing and remote runs         |
-| `add`          | Add a node from an enrollment bundle                          |
-| `list`         | List registered nodes                                         |
-| `status`       | Probe node health and report live status                      |
-| `use`          | Set default node                                              |
-| `remove`       | Remove node registration                                      |
-| `workspace`    | Inspect and repair node workspace map entries                 |
-| `routes`       | Inspect and repair controller-side remote route bridge        |
-| `provider`     | Manage provider-specific node bootstrap workflows             |
-| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints    |
+| Subcommand | Summary |
+| --- | --- |
+| `init` | Initialize this host as a node and emit enrollment bundle |
+| `pair` | Pair node with one-command or expiring verification-code flow |
+| `ssh` | Manage SSH bootstrap for node pairing and remote runs |
+| `add` | Add a node from an enrollment bundle |
+| `list` | List registered nodes |
+| `status` | Probe node health and report live status |
+| `use` | Set default node |
+| `remove` | Remove node registration |
+| `workspace` | Inspect and repair node workspace map entries |
+| `routes` | Inspect and repair controller-side remote route bridge |
+| `provider` | Manage provider-specific node bootstrap workflows |
+| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints |
 
 Examples:
 
@@ -869,12 +872,12 @@ Usage: `hack node workspace <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                                |
-| ---------- | ------------------------------------------------------ |
-| `list`     | List node-local workspace map entries                  |
-| `resolve`  | Resolve a map entry by controller project selector     |
-| `attach`   | Attach an existing local workspace to project selector |
-| `remove`   | Remove a map entry by project selector                 |
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List node-local workspace map entries |
+| `resolve` | Resolve a map entry by controller project selector |
+| `attach` | Attach an existing local workspace to project selector |
+| `remove` | Remove a map entry by project selector |
 
 Examples:
 
@@ -891,10 +894,10 @@ Usage: `hack node routes <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                             |
-| ---------- | --------------------------------------------------- |
-| `status`   | Show controller-side remote route bridge state      |
-| `repair`   | Re-render and re-apply persisted route bridge stack |
+| Subcommand | Summary |
+| --- | --- |
+| `status` | Show controller-side remote route bridge state |
+| `repair` | Re-render and re-apply persisted route bridge stack |
 
 Examples:
 
@@ -910,11 +913,11 @@ Usage: `hack dispatch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                  |
-| ---------- | ---------------------------------------- |
-| `run`      | Dispatch a command to a node workspace   |
-| `status`   | Show dispatched run status               |
-| `logs`     | Show or follow persisted/remote run logs |
+| Subcommand | Summary |
+| --- | --- |
+| `run` | Dispatch a command to a node workspace |
+| `status` | Show dispatched run status |
+| `logs` | Show or follow persisted/remote run logs |
 
 #### hack dispatch run
 
@@ -923,15 +926,15 @@ Usage: `hack dispatch run --project <name|id> [options] -- <command...>`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- | --- |
-| `--project <name | id>` | string | - | Project name or id |
-| `--node <id | default | auto>` | string | auto | Target node id, or use default/auto |
+| --- | --- | --- | --- |
+| `--project <name|id>` | string | - | Project name or id |
+| `--node <id|default|auto>` | string | auto | Target node id, or use default/auto |
 | `--provider <provider>` | string | - | Provider route override used when resolving profile/bootstrap intent |
 | `--profile <profile-id>` | string | - | Provider profile route override |
 | `--bootstrap-if-needed` | boolean | false | Allow guarded provider bootstrap handoff when no reachable node is found |
 | `--branch <branch>` | string | current | Target branch on selected node |
 | `--ticket <ticket-id>` | string | - | Ticket id to associate with run metadata |
-| `--runner <generic | codex | claude | cursor>` | string | `generic` | Runner identity for policy and audit |
+| `--runner <generic|codex|claude|cursor>` | string | `generic` | Runner identity for policy and audit |
 | `--approve` | boolean | false | Approve high/critical risk commands non-interactively |
 | `--pr` | boolean | false | Push branch + create/update GitHub PR on successful run |
 | `--pr-base <branch>` | string | `main` | Base branch used with `--pr` |
@@ -978,12 +981,12 @@ If you run `hack remote` with no subcommand, it prints status and offers to run
 
 Subcommands:
 
-| Subcommand | Summary                              |
-| ---------- | ------------------------------------ |
-| `setup`    | Run the guided gateway setup         |
-| `status`   | Show remote/gateway status           |
-| `monitor`  | Open a remote status TUI             |
-| `qr`       | Print a QR payload for remote access |
+| Subcommand | Summary |
+| --- | --- |
+| `setup` | Run the guided gateway setup |
+| `status` | Show remote/gateway status |
+| `monitor` | Open a remote status TUI |
+| `qr` | Print a QR payload for remote access |
 
 #### hack remote setup
 
@@ -991,13 +994,13 @@ Usage: `hack remote setup [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                         |
-| -------------------- | ------- | ------- | --------------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
-| `--project <name>`   | string  | -       | Target a registered project by name                 |
-| `--qr`               | boolean | true    | Force QR output after setup (default)               |
-| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
-| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--qr` | boolean | true | Force QR output after setup (default) |
+| `--no-qr` | boolean | false | Skip QR output after setup |
+| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
 
 #### hack remote status
 
@@ -1005,10 +1008,10 @@ Usage: `hack remote status [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack remote monitor
 
@@ -1016,10 +1019,10 @@ Usage: `hack remote monitor [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack remote qr
 
@@ -1045,9 +1048,9 @@ Usage: `hack x <namespace> <command> [args...]`
 
 Arguments:
 
-| Name   | Type     | Required | Description                             |
-| ------ | -------- | -------- | --------------------------------------- |
-| `args` | string[] | no       | Extension command args (passed through) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `args` | string[] | no | Extension command args (passed through) |
 
 Notes:
 
@@ -1062,15 +1065,15 @@ Usage: `hack setup <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                                |
-| ---------- | ------------------------------------------------------ |
-| `cursor`   | Install Cursor rules for hack CLI usage                |
-| `claude`   | Install Claude Code hooks for hack CLI usage           |
-| `codex`    | Install Codex skill for hack CLI usage                 |
-| `tickets`  | Install Codex skill for hack tickets usage             |
-| `agents`   | Install AGENTS.md / CLAUDE.md snippets                 |
-| `sync`     | Refresh agent docs, skills, and MCP configs            |
-| `mcp`      | Install MCP configs for hack CLI usage (no-shell only) |
+| Subcommand | Summary |
+| --- | --- |
+| `cursor` | Install Cursor rules for hack CLI usage |
+| `claude` | Install Claude Code hooks for hack CLI usage |
+| `codex` | Install Codex skill for hack CLI usage |
+| `tickets` | Install Codex skill for hack tickets usage |
+| `agents` | Install AGENTS.md / CLAUDE.md snippets |
+| `sync` | Refresh agent docs, skills, and MCP configs |
+| `mcp` | Install MCP configs for hack CLI usage (no-shell only) |
 
 #### hack setup cursor
 
@@ -1078,12 +1081,12 @@ Usage: `hack setup cursor [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup claude
 
@@ -1091,12 +1094,12 @@ Usage: `hack setup claude [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup codex
 
@@ -1104,12 +1107,12 @@ Usage: `hack setup codex [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup agents
 
@@ -1117,14 +1120,14 @@ Usage: `hack setup agents [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--all`              | boolean | false   | Target all supported docs                      |
-| `--agents-md`        | boolean | false   | Target AGENTS.md                               |
-| `--claude-md`        | boolean | false   | Target CLAUDE.md                               |
-| `--check`            | boolean | false   | Check whether integration is installed         |
-| `--remove`           | boolean | false   | Remove integration files/config                |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--all` | boolean | false | Target all supported docs |
+| `--agents-md` | boolean | false | Target AGENTS.md |
+| `--claude-md` | boolean | false | Target CLAUDE.md |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup sync
 
@@ -1132,13 +1135,13 @@ Usage: `hack setup sync [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--global`           | boolean | false   | Target global (user) scope only                |
-| `--all-scopes`       | boolean | false   | Target both project and global (user) scopes   |
-| `--check`            | boolean | false   | Check whether integrations are installed       |
-| `--remove`           | boolean | false   | Remove generated integration files/config      |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Target global (user) scope only |
+| `--all-scopes` | boolean | false | Target both project and global (user) scopes |
+| `--check` | boolean | false | Check whether integrations are installed |
+| `--remove` | boolean | false | Remove generated integration files/config |
 
 Automatic guardrail:
 
@@ -1151,16 +1154,16 @@ Usage: `hack setup mcp [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--all`              | boolean | false   | Target all supported clients                     |
-| `--cursor`           | boolean | false   | Target Cursor integration                        |
-| `--claude`           | boolean | false   | Target Claude integration                        |
-| `--codex`            | boolean | false   | Target Codex integration                         |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--all` | boolean | false | Target all supported clients |
+| `--cursor` | boolean | false | Target Cursor integration |
+| `--claude` | boolean | false | Target Claude integration |
+| `--codex` | boolean | false | Target Codex integration |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 ### hack agent
 
@@ -1168,11 +1171,11 @@ Usage: `hack agent <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                         |
-| ---------- | ------------------------------- |
-| `prime`    | Print agent primer text         |
+| Subcommand | Summary |
+| --- | --- |
+| `prime` | Print agent primer text |
 | `patterns` | Print agent init patterns guide |
-| `init`     | Print agent init prompt         |
+| `init` | Print agent init prompt |
 
 #### hack agent init
 
@@ -1180,10 +1183,10 @@ Usage: `hack agent init [options]`
 
 Options:
 
-| Flag                    | Type   | Default | Description                                    |
-| ----------------------- | ------ | ------- | ---------------------------------------------- | ------ | --- | ---------------------------------------------- |
-| `-p`, `--path <dir>`    | string | -       | Run against a repo path (overrides cwd search) |
-| `-c`, `--client <cursor | claude | codex   | print>`                                        | string | -   | Open init prompt in an agent client (or print) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `-c`, `--client <cursor|claude|codex|print>` | string | - | Open init prompt in an agent client (or print) |
 
 ### hack mcp
 
@@ -1191,11 +1194,11 @@ Usage: `hack mcp <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                  |
-| ---------- | ---------------------------------------- |
-| `serve`    | Run the MCP server over stdio            |
-| `install`  | Install MCP config for supported clients |
-| `print`    | Print MCP config snippets                |
+| Subcommand | Summary |
+| --- | --- |
+| `serve` | Run the MCP server over stdio |
+| `install` | Install MCP config for supported clients |
+| `print` | Print MCP config snippets |
 
 #### hack mcp install
 
@@ -1203,17 +1206,17 @@ Usage: `hack mcp install [options]`
 
 Options:
 
-| Flag                 | Type      | Default | Description                                    |
-| -------------------- | --------- | ------- | ---------------------------------------------- | ----------------------------------------- |
-| `--scope <user       | project>` | string  | `user`                                         | Write MCP config to user or project scope |
-| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
-| `--all`              | boolean   | false   | Target all supported clients                   |
-| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
-| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
-| `--codex`            | boolean   | false   | Target Codex MCP config                        |
-| `--docs`             | boolean   | false   | Update AGENTS.md and CLAUDE.md with hack usage |
-| `--agents-md`        | boolean   | false   | Update AGENTS.md with hack usage               |
-| `--claude-md`        | boolean   | false   | Update CLAUDE.md with hack usage               |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--scope <user|project>` | string | `user` | Write MCP config to user or project scope |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--all` | boolean | false | Target all supported clients |
+| `--cursor` | boolean | false | Target Cursor MCP config |
+| `--claude` | boolean | false | Target Claude CLI MCP config |
+| `--codex` | boolean | false | Target Codex MCP config |
+| `--docs` | boolean | false | Update AGENTS.md and CLAUDE.md with hack usage |
+| `--agents-md` | boolean | false | Update AGENTS.md with hack usage |
+| `--claude-md` | boolean | false | Update CLAUDE.md with hack usage |
 
 Notes:
 
@@ -1226,14 +1229,14 @@ Usage: `hack mcp print [options]`
 
 Options:
 
-| Flag                 | Type      | Default | Description                                    |
-| -------------------- | --------- | ------- | ---------------------------------------------- | ------------------------------------------ |
-| `--scope <user       | project>` | string  | `user`                                         | Print MCP config for user or project scope |
-| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
-| `--all`              | boolean   | false   | Target all supported clients                   |
-| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
-| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
-| `--codex`            | boolean   | false   | Target Codex MCP config                        |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--scope <user|project>` | string | `user` | Print MCP config for user or project scope |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--all` | boolean | false | Target all supported clients |
+| `--cursor` | boolean | false | Target Cursor MCP config |
+| `--claude` | boolean | false | Target Claude CLI MCP config |
+| `--codex` | boolean | false | Target Codex MCP config |
 
 ## Diagnostics commands
 
@@ -1272,17 +1275,17 @@ Usage: `hack daemon <subcommand>`
 
 Subcommands:
 
-| Subcommand  | Summary                                    |
-| ----------- | ------------------------------------------ |
-| `start`     | Start hackd (local daemon)                 |
-| `stop`      | Stop hackd                                 |
-| `restart`   | Restart hackd                              |
-| `status`    | Show hackd status                          |
-| `metrics`   | Show hackd metrics                         |
-| `logs`      | Show hackd logs                            |
-| `clear`     | Clear stale hackd pid/socket files         |
-| `install`   | Install hackd as a launchd service (macOS) |
-| `uninstall` | Uninstall hackd launchd service (macOS)    |
+| Subcommand | Summary |
+| --- | --- |
+| `start` | Start hackd (local daemon) |
+| `stop` | Stop hackd |
+| `restart` | Restart hackd |
+| `status` | Show hackd status |
+| `metrics` | Show hackd metrics |
+| `logs` | Show hackd logs |
+| `clear` | Clear stale hackd pid/socket files |
+| `install` | Install hackd as a launchd service (macOS) |
+| `uninstall` | Uninstall hackd launchd service (macOS) |
 
 Autostart + self-heal behavior:
 
@@ -1299,9 +1302,9 @@ Usage: `hack daemon start [options]`
 
 Options:
 
-| Flag           | Type    | Default | Description                         |
-| -------------- | ------- | ------- | ----------------------------------- |
-| `--foreground` | boolean | false   | Run hackd in the foreground (debug) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--foreground` | boolean | false | Run hackd in the foreground (debug) |
 
 #### hack daemon status
 
@@ -1309,9 +1312,9 @@ Usage: `hack daemon status [options]`
 
 Options:
 
-| Flag     | Type    | Default | Description                                                    |
-| -------- | ------- | ------- | -------------------------------------------------------------- |
-| `--json` | boolean | false   | Output JSON (machine-readable, includes launchd info on macOS) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable, includes launchd info on macOS) |
 
 #### hack daemon logs
 
@@ -1319,32 +1322,35 @@ Usage: `hack daemon logs [options]`
 
 Options:
 
-| Flag         | Type   | Default | Description           |
-| ------------ | ------ | ------- | --------------------- |
-| `--tail <n>` | number | 200     | Tail last N log lines |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--tail <n>` | number | 200 | Tail last N log lines |
 
 #### hack daemon install
 
 Usage: `hack daemon install [options]`
 
-Installs hackd as a launchd service on macOS. The daemon will be managed by launchd and can optionally start automatically on login.
+Installs hackd as a launchd service on macOS. The daemon will be managed by launchd
+and can optionally start automatically on login.
 
 Options:
 
-| Flag               | Type    | Default | Description                               |
-| ------------------ | ------- | ------- | ----------------------------------------- |
-| `--run-at-load`    | boolean | true    | Start hackd automatically on login        |
-| `--no-run-at-load` | boolean | -       | Do not start hackd automatically on login |
-| `--gui-only`       | boolean | true    | Only run in GUI sessions (Aqua)           |
-| `--no-gui-only`    | boolean | -       | Run in all session types (including SSH)  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--run-at-load` | boolean | true | Start hackd automatically on login |
+| `--no-run-at-load` | boolean | - | Do not start hackd automatically on login |
+| `--gui-only` | boolean | true | Only run in GUI sessions (Aqua) |
+| `--no-gui-only` | boolean | - | Run in all session types (including SSH) |
 
-The service uses the label `dance.hack.hackd` and writes its plist to `~/Library/LaunchAgents/dance.hack.hackd.plist`.
+The service uses the label `dance.hack.hackd` and writes its plist to
+`~/Library/LaunchAgents/dance.hack.hackd.plist`.
 
 #### hack daemon uninstall
 
 Usage: `hack daemon uninstall`
 
-Uninstalls the hackd launchd service on macOS. Removes the plist and unloads the service from launchd.
+Uninstalls the hackd launchd service on macOS. Removes the plist and unloads
+the service from launchd.
 
 ### hack log-pipe
 
@@ -1352,10 +1358,10 @@ Usage: `hack log-pipe [options]`
 
 Options:
 
-| Flag              | Type           | Default | Description |
-| ----------------- | -------------- | ------- | ----------- | ------------------------------- | -------------------------------------- |
-| `--format <auto   | docker-compose | plain>` | string      | `auto`                          | How to parse incoming lines from stdin |
-| `--stream <stdout | stderr>`       | string  | `stdout`    | Treat stdin as stdout or stderr |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--format <auto|docker-compose|plain>` | string | `auto` | How to parse incoming lines from stdin |
+| `--stream <stdout|stderr>` | string | `stdout` | Treat stdin as stdout or stderr |
 
 ### hack help
 
@@ -1363,9 +1369,9 @@ Usage: `hack help [path...]`
 
 Arguments:
 
-| Name   | Type     | Required | Description                                        |
-| ------ | -------- | -------- | -------------------------------------------------- |
-| `path` | string[] | no       | Command path to show help for (e.g. `global logs`) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `path` | string[] | no | Command path to show help for (e.g. `global logs`) |
 
 ### hack update
 
@@ -1373,12 +1379,12 @@ Usage: `hack update [options]`
 
 Options:
 
-| Flag          | Type    | Default | Description                                    |
-| ------------- | ------- | ------- | ---------------------------------------------- |
-| `--check`     | boolean | false   | Check for updates (do not install)             |
-| `--yes`       | boolean | false   | Apply update without prompting                 |
-| `--tag <tag>` | string  | -       | Update to a specific release tag (e.g. v1.4.0) |
-| `--json`      | boolean | false   | Output JSON (machine-readable)                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--check` | boolean | false | Check for updates (do not install) |
+| `--yes` | boolean | false | Apply update without prompting |
+| `--tag <tag>` | string | - | Update to a specific release tag (e.g. v1.4.0) |
+| `--json` | boolean | false | Output JSON (machine-readable) |
 
 ### hack version
 
@@ -1392,23 +1398,23 @@ Usage: `hack secrets <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                            |
-| ---------- | ---------------------------------- |
-| `set`      | Store a secret                     |
-| `get`      | Print a secret (exit 1 if missing) |
-| `delete`   | Delete a stored secret             |
+| Subcommand | Summary |
+| --- | --- |
+| `set` | Store a secret |
+| `get` | Print a secret (exit 1 if missing) |
+| `delete` | Delete a stored secret |
 
 Options (all subcommands):
 
-| Flag                  | Type   | Default    | Description                       |
-| --------------------- | ------ | ---------- | --------------------------------- |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
 | `--service <service>` | string | `hack-cli` | Override Bun.secrets service name |
 
 Arguments (set/get/delete):
 
-| Name   | Type   | Required | Description                       |
-| ------ | ------ | -------- | --------------------------------- |
-| `name` | string | no       | Secret name (prompted if omitted) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | no | Secret name (prompted if omitted) |
 
 ## Fun
 
@@ -1418,7 +1424,7 @@ Usage: `hack the planet [options]`
 
 Options:
 
-| Flag            | Type    | Default | Description       |
-| --------------- | ------- | ------- | ----------------- | ------ | ------- | ----------------- |
-| `--variant <cut | mash    | cycle   | random>`          | string | `cycle` | Animation variant |
-| `--loop`        | boolean | true    | Loop until Ctrl+C |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--variant <cut|mash|cycle|random>` | string | `cycle` | Animation variant |
+| `--loop` | boolean | true | Loop until Ctrl+C |
diff --git a/docs/extensions.md b/docs/extensions.md
index 2a6155c37..689dc93c5 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -1,6 +1,7 @@
 # Extensions & SDK (v0.1)
 
-This doc defines the extension surface area for `hack` and how extension commands are authored, configured, and dispatched.
+This doc defines the extension surface area for `hack` and how extension commands are authored,
+configured, and dispatched.
 
 ## Quick start (one command)
 
@@ -10,7 +11,8 @@ If you just want remote access working, start here:
 hack remote setup
 ```
 
-The wizard enables the gateway for the current project, creates a token + QR, and can configure Cloudflare/Tailscale/SSH exposure in one flow.
+The wizard enables the gateway for the current project, creates a token + QR, and can configure
+Cloudflare/Tailscale/SSH exposure in one flow.
 
 ## Behavior
 
@@ -18,7 +20,8 @@ The wizard enables the gateway for the current project, creates a token + QR, an
 - Each extension provides a manifest + commands (`ExtensionDefinition`).
 - The CLI dispatches extension commands via `hack x <namespace> <command>`.
 - Global enablement lives in `~/.hack/hack.config.json` (`hack config set --global ...`).
-- Per-project overrides live in `.hack/hack.config.json` and typically win over global values (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
+- Per-project overrides live in `.hack/hack.config.json` and typically win over global values
+  (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
 - Built-in Gateway enablement is project-scoped: `controlPlane.gateway.enabled` opts a project into routing.
 
 ## Extension definition (API surface)
@@ -44,14 +47,14 @@ export type ExtensionCommand = {
 ```
 
 The `ExtensionCommandContext` includes:
-
 - `controlPlaneConfig` (parsed config)
 - `projectId` and `projectName` (when available)
 - `logger` and `cwd`
 
 ## Config + enablement
 
-Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by `src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
+Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by
+`src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
 
 Enable a global extension by id:
 
@@ -75,10 +78,10 @@ Shortcut for gateway (project-scoped):
 }
 ```
 
-Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config. Project overrides for these are ignored.
+Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config.
+Project overrides for these are ignored.
 
 CLI helpers:
-
 - `hack gateway enable` (sets both gateway + extension flags)
 - `hack gateway setup` (guided enable + optional writes + token creation + QR by default)
 - `hack config set --global 'controlPlane.extensions[\"dance.hack.gateway\"].enabled' true`
@@ -103,10 +106,10 @@ Use `hack x <namespace> help` to list commands.
 - GitHub: `hack x github connect|oauth-connect|disconnect|profiles|use|status|pr-upsert`
 - Linear: `hack x linear setup|connect|oauth-connect|disconnect|status|profiles|use|projects|project-bind|sync-issue|sync-project`
 
-Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also requires global `controlPlane.gateway.allowWrites = true`).
+Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also
+requires global `controlPlane.gateway.allowWrites = true`).
 
 Current gateway API surface (HTTP/WS):
-
 - `GET /v1/status`, `GET /v1/metrics`, `GET /v1/projects`, `GET /v1/ps`
 - `GET/POST /control-plane/projects/:id/jobs`
 - `GET /control-plane/projects/:id/jobs/:jobId`
@@ -117,7 +120,6 @@ Current gateway API surface (HTTP/WS):
 - `WS /control-plane/projects/:id/shells/:shellId/stream` (requires write token + allowWrites)
 
 Local auth service surface (daemon + global Caddy route):
-
 - `GET /health`
 - `GET /v1/auth/providers`
 - `GET /gh/start` (GitHub browser OAuth entrypoint)
@@ -126,14 +128,15 @@ Local auth service surface (daemon + global Caddy route):
 - `GET /v1/auth/github/start`
 - `GET /v1/auth/github/flows/:id`
 
-Interactive shell/TTY is available via the shell stream endpoints; use `hack x supervisor shell` or see protocol below.
+Interactive shell/TTY is available via the shell stream endpoints; use
+`hack x supervisor shell` or see protocol below.
 
 For full usage guidance and structured workflow patterns, see `gateway-api.md`.
 
 For exposure helpers, see the guides:
-
 - `guides/remote-cloudflare.md`
-- `guides/remote-tailscale.md` DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
+- `guides/remote-tailscale.md`
+DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
 
 ## Command reference
 
@@ -145,14 +148,13 @@ Usage: `hack x gateway token-create [options] [label]`
 
 Options:
 
-| Flag              | Type    | Default | Description                  |
-| ----------------- | ------- | ------- | ---------------------------- | ----------- |
-| `--scope <read    | write>` | string  | `read`                       | Token scope |
-| `--write`         | boolean | false   | Shortcut for `--scope write` |
-| `--label <label>` | string  | -       | Optional label               |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--scope <read|write>` | string | `read` | Token scope |
+| `--write` | boolean | false | Shortcut for `--scope write` |
+| `--label <label>` | string | - | Optional label |
 
 Notes:
-
 - The first non-flag argument is treated as the label if `--label` is not used.
 
 #### token-list
@@ -173,11 +175,11 @@ Usage: `hack x supervisor job-list [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                 |
-| ------------------ | ------- | ------- | --------------------------- |
-| `--project <name>` | string  | -       | Target a registered project |
-| `--path <dir>`     | string  | -       | Target a repo path          |
-| `--json`           | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--json` | boolean | false | Output JSON |
 
 #### job-create
 
@@ -185,14 +187,14 @@ Usage: `hack x supervisor job-create [options] -- <command...>`
 
 Options:
 
-| Flag                | Type    | Default   | Description                                  |
-| ------------------- | ------- | --------- | -------------------------------------------- |
-| `--project <name>`  | string  | -         | Target a registered project                  |
-| `--path <dir>`      | string  | -         | Target a repo path                           |
-| `--runner <name>`   | string  | `generic` | Runner name                                  |
-| `--cwd <path>`      | string  | -         | Working directory (relative to project root) |
-| `--env <KEY=VALUE>` | string  | -         | Environment override (repeatable)            |
-| `--json`            | boolean | false     | Output JSON                                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--runner <name>` | string | `generic` | Runner name |
+| `--cwd <path>` | string | - | Working directory (relative to project root) |
+| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
+| `--json` | boolean | false | Output JSON |
 
 ### GitHub extension (`hack x github`)
 
@@ -255,9 +257,10 @@ hack x github pr-upsert \
 ```
 
 Notes:
-
-- Profile config lives at: `controlPlane.extensions["dance.hack.github"].config.profiles`.
-- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
+- Profile config lives at:
+  `controlPlane.extensions["dance.hack.github"].config.profiles`.
+- Profile selection precedence is:
+  `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
 - Keychain storage uses profile-specific `authRef` + `service`.
 - Token resolution order is keychain first, then environment fallback (`tokenEnv`).
 - If token metadata includes `expiresAt`, auth resolution attempts automatic GitHub App refresh using profile `appId`, `installationId`, and private key source.
@@ -336,7 +339,8 @@ Detailed design and sequencing live in:
 
 ### Linear extension (`hack x linear`)
 
-Linear integration supports multiple auth profiles, project-level binding, and manual sync in both directions between Linear issues and hack tickets.
+Linear integration supports multiple auth profiles, project-level binding, and manual sync in both
+directions between Linear issues and hack tickets.
 
 Quick start:
 
@@ -359,9 +363,11 @@ hack x linear sync-project --from hack --owner both
 ```
 
 Notes:
-
-- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.linear.profile` -> `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
-- Project mapping is stored in project config: `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
+- Profile selection precedence is:
+  `--profile` -> `controlPlane.routing.overrides.linear.profile` ->
+  `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
+- Project mapping is stored in project config:
+  `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
 - Sync is manual by default (`sync-issue` / `sync-project`); there is no background autosync yet.
 - Ticket provenance is preserved during sync via `owner`, `source`, `tags`, and `external*` linkage fields.
 - `hack x linear connect` uses token mode when `--token`/`--stdin`/`$HACK_LINEAR_API_TOKEN` is present, and otherwise falls back to browser OAuth.
@@ -374,7 +380,8 @@ Notes:
 - Auth-broker Linear endpoints:
   - OAuth callback page: `/linear/callback`
   - Webhook ingest: `/linear/webhooks` (legacy alias: `/v1/integrations/linear/webhook`)
-- Sync toggles are configurable at `controlPlane.extensions["dance.hack.linear"].config.sync`:
+- Sync toggles are configurable at
+  `controlPlane.extensions["dance.hack.linear"].config.sync`:
   - `labels` (default `false`)
   - `statuses` (default `true`)
   - `dependencies` (default `true`)
@@ -387,11 +394,11 @@ Usage: `hack x supervisor job-show <job-id> [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                 |
-| ------------------ | ------- | ------- | --------------------------- |
-| `--project <name>` | string  | -       | Target a registered project |
-| `--path <dir>`     | string  | -       | Target a repo path          |
-| `--json`           | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--json` | boolean | false | Output JSON |
 
 #### job-cancel
 
@@ -399,10 +406,10 @@ Usage: `hack x supervisor job-cancel <job-id> [options]`
 
 Options:
 
-| Flag               | Type   | Default | Description                 |
-| ------------------ | ------ | ------- | --------------------------- |
-| `--project <name>` | string | -       | Target a registered project |
-| `--path <dir>`     | string | -       | Target a repo path          |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
 
 #### job-tail
 
@@ -410,15 +417,15 @@ Usage: `hack x supervisor job-tail <job-id> [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                 |
-| ------------------ | ------- | ------- | --------------------------- |
-| `--project <name>` | string  | -       | Target a registered project |
-| `--path <dir>`     | string  | -       | Target a repo path          |
-| `--follow`         | boolean | true    | Follow logs (default)       |
-| `--no-follow`      | boolean | false   | Print logs and exit         |
-| `--logs-from <n>`  | number  | 0       | Resume from log offset      |
-| `--from <n>`       | number  | 0       | Alias for `--logs-from`     |
-| `--json`           | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--follow` | boolean | true | Follow logs (default) |
+| `--no-follow` | boolean | false | Print logs and exit |
+| `--logs-from <n>` | number | 0 | Resume from log offset |
+| `--from <n>` | number | 0 | Alias for `--logs-from` |
+| `--json` | boolean | false | Output JSON |
 
 #### job-attach
 
@@ -426,16 +433,16 @@ Usage: `hack x supervisor job-attach <job-id> [options]`
 
 Options:
 
-| Flag                | Type    | Default | Description                 |
-| ------------------- | ------- | ------- | --------------------------- |
-| `--project <name>`  | string  | -       | Target a registered project |
-| `--path <dir>`      | string  | -       | Target a repo path          |
-| `--follow`          | boolean | true    | Follow logs (default)       |
-| `--no-follow`       | boolean | false   | Print logs and exit         |
-| `--logs-from <n>`   | number  | 0       | Resume from log offset      |
-| `--from <n>`        | number  | 0       | Alias for `--logs-from`     |
-| `--events-from <n>` | number  | 0       | Resume from event sequence  |
-| `--json`            | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--follow` | boolean | true | Follow logs (default) |
+| `--no-follow` | boolean | false | Print logs and exit |
+| `--logs-from <n>` | number | 0 | Resume from log offset |
+| `--from <n>` | number | 0 | Alias for `--logs-from` |
+| `--events-from <n>` | number | 0 | Resume from event sequence |
+| `--json` | boolean | false | Output JSON |
 
 #### shell
 
@@ -443,21 +450,20 @@ Usage: `hack x supervisor shell [options]`
 
 Options:
 
-| Flag                | Type   | Default                 | Description                       |
-| ------------------- | ------ | ----------------------- | --------------------------------- |
-| `--project <name>`  | string | -                       | Target a registered project       |
-| `--project-id <id>` | string | -                       | Target by project id (gateway)    |
-| `--path <dir>`      | string | -                       | Target a repo path                |
-| `--gateway <url>`   | string | `http://127.0.0.1:7788` | Gateway URL                       |
-| `--token <token>`   | string | -                       | Gateway write token               |
-| `--shell <path>`    | string | -                       | Shell path                        |
-| `--cwd <path>`      | string | -                       | Working directory                 |
-| `--cols <n>`        | number | -                       | Terminal columns                  |
-| `--rows <n>`        | number | -                       | Terminal rows                     |
-| `--env <KEY=VALUE>` | string | -                       | Environment override (repeatable) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--project-id <id>` | string | - | Target by project id (gateway) |
+| `--path <dir>` | string | - | Target a repo path |
+| `--gateway <url>` | string | `http://127.0.0.1:7788` | Gateway URL |
+| `--token <token>` | string | - | Gateway write token |
+| `--shell <path>` | string | - | Shell path |
+| `--cwd <path>` | string | - | Working directory |
+| `--cols <n>` | number | - | Terminal columns |
+| `--rows <n>` | number | - | Terminal rows |
+| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
 
 Notes:
-
 - `--project` and `--project-id` are mutually exclusive.
 
 ### Cloudflare extension (`hack x cloudflare`)
@@ -468,15 +474,15 @@ Usage: `hack x cloudflare tunnel-print [options]`
 
 Options:
 
-| Flag                        | Type   | Default                 | Description                  |
-| --------------------------- | ------ | ----------------------- | ---------------------------- |
-| `--hostname <host>`         | string | -                       | Gateway hostname             |
-| `--tunnel <name>`           | string | `hack-gateway`          | Tunnel name                  |
-| `--origin <url>`            | string | `http://127.0.0.1:7788` | Gateway origin               |
-| `--ssh-hostname <host>`     | string | -                       | SSH hostname (optional)      |
-| `--ssh-origin <url>`        | string | `ssh://127.0.0.1:22`    | SSH origin                   |
-| `--credentials-file <path>` | string | -                       | Cloudflared credentials file |
-| `--out <path>`              | string | -                       | Write config to a file       |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--hostname <host>` | string | - | Gateway hostname |
+| `--tunnel <name>` | string | `hack-gateway` | Tunnel name |
+| `--origin <url>` | string | `http://127.0.0.1:7788` | Gateway origin |
+| `--ssh-hostname <host>` | string | - | SSH hostname (optional) |
+| `--ssh-origin <url>` | string | `ssh://127.0.0.1:22` | SSH origin |
+| `--credentials-file <path>` | string | - | Cloudflared credentials file |
+| `--out <path>` | string | - | Write config to a file |
 
 #### tunnel-setup
 
@@ -503,11 +509,11 @@ Usage: `hack x cloudflare tunnel-start [options]`
 
 Options:
 
-| Flag              | Type   | Default                     | Description          |
-| ----------------- | ------ | --------------------------- | -------------------- |
-| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path          |
-| `--out <path>`    | string | -                           | Alias for `--config` |
-| `--tunnel <name>` | string | -                           | Override tunnel name |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path |
+| `--out <path>` | string | - | Alias for `--config` |
+| `--tunnel <name>` | string | - | Override tunnel name |
 
 #### tunnel-stop
 
@@ -519,10 +525,10 @@ Usage: `hack x cloudflare access-setup [options]`
 
 Options:
 
-| Flag                    | Type   | Default | Description  |
-| ----------------------- | ------ | ------- | ------------ |
-| `--ssh-hostname <host>` | string | -       | SSH hostname |
-| `--user <user>`         | string | -       | SSH username |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--ssh-hostname <host>` | string | - | SSH hostname |
+| `--user <user>` | string | - | SSH username |
 
 ### Tailscale extension (`hack x tailscale`)
 
@@ -555,7 +561,6 @@ Usage: `hack x tailscale oauth-disconnect [--auth-ref <ref>] [--json]`
 Usage: `hack x tailscale ip [args...]`
 
 Notes:
-
 - `status` and `ip` forward extra args directly to `tailscale`.
 - `ip` defaults to `-4` when no args are provided.
 
@@ -604,18 +609,17 @@ The gateway binds to `127.0.0.1` by default. Expose it through one of:
 - SSH tunnel (ad‑hoc): `ssh -L 7788:127.0.0.1:7788 <host>`
 - Zero Trust/VPN (persistent): Tailscale, Cloudflare, etc. targeting the gateway port
 - Optional Caddy route for local convenience (`https://gateway.hack`):
-  - Add a small labeled container in the global Caddy compose that proxies to `host.docker.internal:7788` (or `host-gateway` on Linux).
+  - Add a small labeled container in the global Caddy compose that proxies to
+    `host.docker.internal:7788` (or `host-gateway` on Linux).
 
 Keep tokens read-only unless you explicitly need writes.
 
 Recommended order:
-
-1. Start with SSH tunneling for quick remote access.
-2. Move to a private Zero Trust/VPN network once you want persistent access.
-3. Add the Caddy route only for nicer local URLs (not required for remote access).
+1) Start with SSH tunneling for quick remote access.
+2) Move to a private Zero Trust/VPN network once you want persistent access.
+3) Add the Caddy route only for nicer local URLs (not required for remote access).
 
 Remote helper commands:
-
 - `hack remote status` shows gateway + exposure status.
 - `hack remote qr` emits QR payloads for SSH or gateway clients.
 

From 75b33bc95dd8153b8da82e018a4d8bcca66937da Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 19:04:54 +0000
Subject: [PATCH 075/134] docs: format github workflow docs

---
 docs/cli.md        | 832 ++++++++++++++++++++++-----------------------
 docs/extensions.md | 216 ++++++------
 2 files changed, 519 insertions(+), 529 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 247f0f85c..61e0c0e35 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,7 +1,6 @@
 # CLI Reference
 
-This reference mirrors the CLI spec in `src/cli/spec.ts`.
-Run `hack help` or `hack help <command>` for interactive help.
+This reference mirrors the CLI spec in `src/cli/spec.ts`. Run `hack help` or `hack help <command>` for interactive help.
 
 ## Conventions
 
@@ -61,17 +60,17 @@ Usage: `hack global <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `install` | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy |
-| `up` | Start global infra containers |
-| `down` | Stop global infra containers |
-| `status` | Show status for global infra (containers + networks) |
-| `logs` | Tail global infra logs (caddy|grafana|loki|alloy) |
-| `ca` | Export Caddy Local CA cert (print path or PEM) |
-| `cert` | Generate local TLS certs via mkcert (for non-Caddy services) |
-| `trust` | Trust Caddy Local CA (macOS) so https://*.hack is trusted |
-| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards) |
+| Subcommand   | Summary                                                      |
+| ------------ | ------------------------------------------------------------ | ------- | ---- | ------ |
+| `install`    | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy     |
+| `up`         | Start global infra containers                                |
+| `down`       | Stop global infra containers                                 |
+| `status`     | Show status for global infra (containers + networks)         |
+| `logs`       | Tail global infra logs (caddy                                | grafana | loki | alloy) |
+| `ca`         | Export Caddy Local CA cert (print path or PEM)               |
+| `cert`       | Generate local TLS certs via mkcert (for non-Caddy services) |
+| `trust`      | Trust Caddy Local CA (macOS) so https://\*.hack is trusted   |
+| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards)          |
 
 #### hack global logs
 
@@ -79,18 +78,18 @@ Usage: `hack global logs [service] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | no | Filter to one global service (caddy, grafana, loki, alloy) |
+| Name      | Type   | Required | Description                                                |
+| --------- | ------ | -------- | ---------------------------------------------------------- |
+| `service` | string | no       | Filter to one global service (caddy, grafana, loki, alloy) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-f`, `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--tail <n>` | number | 200 | Tail last N log lines |
-| `--pretty` | boolean | false | Pretty-print logs (best-effort JSON parsing + formatting) |
+| Flag             | Type    | Default | Description                                               |
+| ---------------- | ------- | ------- | --------------------------------------------------------- |
+| `-f`, `--follow` | boolean | true    | Follow logs (default)                                     |
+| `--no-follow`    | boolean | false   | Print logs and exit                                       |
+| `--tail <n>`     | number  | 200     | Tail last N log lines                                     |
+| `--pretty`       | boolean | false   | Pretty-print logs (best-effort JSON parsing + formatting) |
 
 #### hack global ca
 
@@ -98,9 +97,9 @@ Usage: `hack global ca [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--print` | boolean | false | Print the CA cert PEM to stdout (instead of printing its path) |
+| Flag      | Type    | Default | Description                                                    |
+| --------- | ------- | ------- | -------------------------------------------------------------- |
+| `--print` | boolean | false   | Print the CA cert PEM to stdout (instead of printing its path) |
 
 #### hack global cert
 
@@ -108,16 +107,16 @@ Usage: `hack global cert <hosts...> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `hosts` | string[] | yes | One or more hostnames to generate certs for |
+| Name    | Type     | Required | Description                                 |
+| ------- | -------- | -------- | ------------------------------------------- |
+| `hosts` | string[] | yes      | One or more hostnames to generate certs for |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--install` | boolean | false | Run mkcert -install before generating certs |
-| `--out <dir>` | string | `~/.hack/certs` | Directory for generated cert/key |
+| Flag          | Type    | Default         | Description                                 |
+| ------------- | ------- | --------------- | ------------------------------------------- |
+| `--install`   | boolean | false           | Run mkcert -install before generating certs |
+| `--out <dir>` | string  | `~/.hack/certs` | Directory for generated cert/key            |
 
 ### hack projects
 
@@ -142,9 +141,9 @@ Usage: `hack projects prune [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
+| Flag               | Type    | Default | Description                                   |
+| ------------------ | ------- | ------- | --------------------------------------------- |
+| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
 
 ### hack status
 
@@ -152,12 +151,12 @@ Usage: `hack status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Filter to a registered project name |
-| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
-| `--all` | boolean | false | Include unregistered docker compose projects |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag               | Type    | Default | Description                                   |
+| ------------------ | ------- | ------- | --------------------------------------------- |
+| `--project <name>` | string  | -       | Filter to a registered project name           |
+| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
+| `--all`            | boolean | false   | Include unregistered docker compose projects  |
+| `--json`           | boolean | false   | Output JSON (machine-readable)                |
 
 ### hack usage
 
@@ -200,13 +199,13 @@ Usage: `hack up [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `-d`, `--detach` | boolean | false | Run in background (docker compose up -d) |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack down
 
@@ -215,12 +214,12 @@ Usage: `hack down [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack restart
 
@@ -229,12 +228,12 @@ Usage: `hack restart [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack ps
 
@@ -256,9 +255,9 @@ Usage: `hack logs [service] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | no | Filter logs by service (shortcut for `--services`) |
+| Name      | Type   | Required | Description                                        |
+| --------- | ------ | -------- | -------------------------------------------------- |
+| `service` | string | no       | Filter logs by service (shortcut for `--services`) |
 
 Options:
 
@@ -292,10 +291,10 @@ Usage: `hack run <service> [-- <cmd...>] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | yes | Compose service name |
-| `cmd` | string[] | no | Command to run (defaults to service entrypoint) |
+| Name      | Type     | Required | Description                                     |
+| --------- | -------- | -------- | ----------------------------------------------- |
+| `service` | string   | yes      | Compose service name                            |
+| `cmd`     | string[] | no       | Command to run (defaults to service entrypoint) |
 
 Options:
 
@@ -313,18 +312,18 @@ Usage: `hack open [target] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `target` | string | no | `www` (default), `logs`, a subdomain, or a full URL |
+| Name     | Type   | Required | Description                                         |
+| -------- | ------ | -------- | --------------------------------------------------- |
+| `target` | string | no       | `www` (default), `logs`, a subdomain, or a full URL |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--branch <name>` | string | - | Run against a branch-specific instance |
-| `--json` | boolean | false | Output JSON with `{ "url": "..." }` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--branch <name>`    | string  | -       | Run against a branch-specific instance         |
+| `--json`             | boolean | false   | Output JSON with `{ "url": "..." }`            |
 
 Notes:
 
@@ -339,10 +338,10 @@ Usage: `hack tui [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 Notes:
 
@@ -354,12 +353,12 @@ Usage: `hack branch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `add` | Register a branch alias for this project |
-| `list` | List registered branch aliases |
-| `remove` | Remove a branch alias |
-| `open` | Open the branch host in a browser |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `add`      | Register a branch alias for this project |
+| `list`     | List registered branch aliases           |
+| `remove`   | Remove a branch alias                    |
+| `open`     | Open the branch host in a browser        |
 
 #### hack branch add
 
@@ -367,17 +366,17 @@ Usage: `hack branch add <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--note <text>` | string | - | Optional note for the branch entry |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
+| `--note <text>`      | string | -       | Optional note for the branch entry             |
 
 #### hack branch list
 
@@ -385,10 +384,10 @@ Usage: `hack branch list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack branch remove
 
@@ -396,16 +395,16 @@ Usage: `hack branch remove <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack branch open
 
@@ -413,16 +412,16 @@ Usage: `hack branch open <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 ### hack config
 
@@ -430,10 +429,10 @@ Usage: `hack config <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `get` | Read a value from hack.config.json |
-| `set` | Update a value in hack.config.json |
+| Subcommand | Summary                            |
+| ---------- | ---------------------------------- |
+| `get`      | Read a value from hack.config.json |
+| `set`      | Update a value in hack.config.json |
 
 #### hack config get
 
@@ -441,17 +440,17 @@ Usage: `hack config get <key> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
+| Name  | Type   | Required | Description                             |
+| ----- | ------ | -------- | --------------------------------------- |
+| `key` | string | yes      | Dot path (e.g. `logs.snapshot_backend`) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--global` | boolean | false | Read global `~/.hack/hack.config.json` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--global`           | boolean | false   | Read global `~/.hack/hack.config.json`         |
 
 #### hack config set
 
@@ -459,18 +458,18 @@ Usage: `hack config set <key> <value> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
-| `value` | string | yes | JSON value or raw string (parsed as JSON when valid) |
+| Name    | Type   | Required | Description                                          |
+| ------- | ------ | -------- | ---------------------------------------------------- |
+| `key`   | string | yes      | Dot path (e.g. `logs.snapshot_backend`)              |
+| `value` | string | yes      | JSON value or raw string (parsed as JSON when valid) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--global` | boolean | false | Write global `~/.hack/hack.config.json` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--global`           | boolean | false   | Write global `~/.hack/hack.config.json`        |
 
 ### hack env
 
@@ -478,12 +477,12 @@ Usage: `hack env <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List env contract vars and resolution state |
-| `set` | Set an env value (.hack/.env or secret backend) |
-| `unset` | Unset an env value (.hack/.env and secret backend) |
-| `backend` | Manage env/secret backend strategy |
+| Subcommand | Summary                                            |
+| ---------- | -------------------------------------------------- |
+| `list`     | List env contract vars and resolution state        |
+| `set`      | Set an env value (.hack/.env or secret backend)    |
+| `unset`    | Unset an env value (.hack/.env and secret backend) |
+| `backend`  | Manage env/secret backend strategy                 |
 
 #### hack env list
 
@@ -491,12 +490,12 @@ Usage: `hack env list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--json` | boolean | false | Output JSON (machine-readable) |
-| `--show-secrets` | boolean | false | Print secret values (secret backend) in plaintext |
+| Flag                 | Type    | Default | Description                                       |
+| -------------------- | ------- | ------- | ------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)    |
+| `--project <name>`   | string  | -       | Target a registered project by name               |
+| `--json`             | boolean | false   | Output JSON (machine-readable)                    |
+| `--show-secrets`     | boolean | false   | Print secret values (secret backend) in plaintext |
 
 #### hack env set
 
@@ -518,10 +517,10 @@ Usage: `hack env unset [key] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack env backend
 
@@ -529,10 +528,10 @@ Usage: `hack env backend <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `status` | Show configured env/secret backend strategy |
-| `use` | Select env/secret backend strategy |
+| Subcommand | Summary                                     |
+| ---------- | ------------------------------------------- |
+| `status`   | Show configured env/secret backend strategy |
+| `use`      | Select env/secret backend strategy          |
 
 #### hack env backend status
 
@@ -540,9 +539,9 @@ Usage: `hack env backend status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag     | Type    | Default | Description                    |
+| -------- | ------- | ------- | ------------------------------ |
+| `--json` | boolean | false   | Output JSON (machine-readable) |
 
 #### hack env backend use
 
@@ -551,8 +550,8 @@ Usage: `hack env backend use <keychain|encrypted_file|cloud> [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--provider <aws|gcp|azure|vault>` | string | - | Cloud provider when backend is `cloud` |
+| --- | --- | --- | --- | --- | --- | --- |
+| `--provider <aws | gcp | azure | vault>` | string | - | Cloud provider when backend is `cloud` |
 | `--store-path <path>` | string | - | Encrypted file path when backend is `encrypted_file` |
 | `--secret-project <id>` | string | - | Optional cloud account/project identifier |
 | `--secret-prefix <prefix>` | string | - | Optional cloud secret name prefix |
@@ -566,16 +565,16 @@ With no subcommand, opens an interactive picker of active sessions and available
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List active sessions |
-| `start` | Start or attach to a session for a project |
-| `stop` | Stop (kill) a session |
-| `attach` | Attach to an existing session |
-| `exec` | Execute a command in a session |
-| `panes` | List panes in a tmux session |
-| `capture` | Capture recent output from a tmux session |
-| `tail` | Tail output from a tmux session |
+| Subcommand | Summary                                    |
+| ---------- | ------------------------------------------ |
+| `list`     | List active sessions                       |
+| `start`    | Start or attach to a session for a project |
+| `stop`     | Stop (kill) a session                      |
+| `attach`   | Attach to an existing session              |
+| `exec`     | Execute a command in a session             |
+| `panes`    | List panes in a tmux session               |
+| `capture`  | Capture recent output from a tmux session  |
+| `tail`     | Tail output from a tmux session            |
 
 #### hack session start
 
@@ -583,11 +582,11 @@ Usage: `hack session start [project] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--up` | boolean | false | Run hack up -d before attaching |
-| `--new` | boolean | false | Force create new session even if one exists |
-| `--name <suffix>` | string | - | Custom suffix for new session (e.g., agent-1) |
+| Flag              | Type    | Default | Description                                   |
+| ----------------- | ------- | ------- | --------------------------------------------- |
+| `--up`            | boolean | false   | Run hack up -d before attaching               |
+| `--new`           | boolean | false   | Force create new session even if one exists   |
+| `--name <suffix>` | string  | -       | Custom suffix for new session (e.g., agent-1) |
 
 #### hack session panes
 
@@ -595,10 +594,10 @@ Usage: `hack session panes <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag       | Type    | Default | Description                          |
+| ---------- | ------- | ------- | ------------------------------------ |
+| `--json`   | boolean | false   | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false   | Output human-friendly text           |
 
 #### hack session capture
 
@@ -606,12 +605,12 @@ Usage: `hack session capture <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--target <target>` | string | - | Tmux pane target (default: active pane) |
-| `--lines <n>` | number | 200 | Number of lines to capture |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag                | Type    | Default | Description                             |
+| ------------------- | ------- | ------- | --------------------------------------- |
+| `--target <target>` | string  | -       | Tmux pane target (default: active pane) |
+| `--lines <n>`       | number  | 200     | Number of lines to capture              |
+| `--json`            | boolean | false   | Output NDJSON stream (start/log/end)    |
+| `--pretty`          | boolean | false   | Output human-friendly text              |
 
 #### hack session tail
 
@@ -619,14 +618,14 @@ Usage: `hack session tail <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--target <target>` | string | - | Tmux pane target (default: active pane) |
-| `--lines <n>` | number | 200 | Number of lines to capture |
-| `--interval-ms <ms>` | number | 500 | Polling interval in milliseconds |
-| `--max-ms <ms>` | number | 5000 | Stop tailing after N milliseconds |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag                 | Type    | Default | Description                             |
+| -------------------- | ------- | ------- | --------------------------------------- |
+| `--target <target>`  | string  | -       | Tmux pane target (default: active pane) |
+| `--lines <n>`        | number  | 200     | Number of lines to capture              |
+| `--interval-ms <ms>` | number  | 500     | Polling interval in milliseconds        |
+| `--max-ms <ms>`      | number  | 5000    | Stop tailing after N milliseconds       |
+| `--json`             | boolean | false   | Output NDJSON stream (start/log/end)    |
+| `--pretty`           | boolean | false   | Output human-friendly text              |
 
 ### hack ssh
 
@@ -634,27 +633,25 @@ Usage: `hack ssh [session] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-H`, `--host <host>` | string | - | SSH host (hostname or IP) |
-| `-u`, `--user <user>` | string | - | SSH username |
-| `-t`, `--tailscale` | boolean | false | Use Tailscale SSH |
-| `-d`, `--direct` | boolean | false | Use direct SSH (requires --host) |
-| `-p`, `--port <port>` | string | - | SSH port for direct connection (default: 22) |
+| Flag                  | Type    | Default | Description                                  |
+| --------------------- | ------- | ------- | -------------------------------------------- |
+| `-H`, `--host <host>` | string  | -       | SSH host (hostname or IP)                    |
+| `-u`, `--user <user>` | string  | -       | SSH username                                 |
+| `-t`, `--tailscale`   | boolean | false   | Use Tailscale SSH                            |
+| `-d`, `--direct`      | boolean | false   | Use direct SSH (requires --host)             |
+| `-p`, `--port <port>` | string  | -       | SSH port for direct connection (default: 22) |
 
 ### hack tickets
 
 Usage: `hack tickets <args...>`
 
-`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`).
-Run `hack tickets` with no args to see available subcommands.
+`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`). Run `hack tickets` with no args to see available subcommands.
 
 ### hack linear
 
 Usage: `hack linear <args...>`
 
-`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`).
-Run `hack linear` with no args to see available subcommands.
+`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`). Run `hack linear` with no args to see available subcommands.
 
 ## Internal commands
 
@@ -664,8 +661,8 @@ Usage: `hack internal <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
+| Subcommand    | Summary                             |
+| ------------- | ----------------------------------- |
 | `extra-hosts` | Manage internal Compose extra_hosts |
 
 #### hack internal extra-hosts
@@ -674,17 +671,17 @@ Usage: `hack internal extra-hosts <subcommand> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <path>` | string | - | Start directory (defaults to cwd) |
+| Flag                  | Type   | Default | Description                       |
+| --------------------- | ------ | ------- | --------------------------------- |
+| `-p`, `--path <path>` | string | -       | Start directory (defaults to cwd) |
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `set` | Set an internal extra_hosts entry |
-| `unset` | Remove an internal extra_hosts entry |
-| `list` | List internal extra_hosts entries |
+| Subcommand | Summary                              |
+| ---------- | ------------------------------------ |
+| `set`      | Set an internal extra_hosts entry    |
+| `unset`    | Remove an internal extra_hosts entry |
+| `list`     | List internal extra_hosts entries    |
 
 #### hack internal extra-hosts set
 
@@ -706,11 +703,11 @@ Usage: `hack gateway <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `enable` | Enable the gateway and start hackd |
-| `setup` | Guided gateway setup (enable + token) |
-| `disable` | Disable the gateway (does not stop hackd) |
+| Subcommand | Summary                                   |
+| ---------- | ----------------------------------------- |
+| `enable`   | Enable the gateway and start hackd        |
+| `setup`    | Guided gateway setup (enable + token)     |
+| `disable`  | Disable the gateway (does not stop hackd) |
 
 #### hack gateway enable
 
@@ -718,10 +715,10 @@ Usage: `hack gateway enable [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack gateway setup
 
@@ -729,13 +726,13 @@ Usage: `hack gateway setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--qr` | boolean | true | Force QR output after setup (default) |
-| `--no-qr` | boolean | false | Skip QR output after setup |
-| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
+| Flag                 | Type    | Default | Description                                         |
+| -------------------- | ------- | ------- | --------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
+| `--project <name>`   | string  | -       | Target a registered project by name                 |
+| `--qr`               | boolean | true    | Force QR output after setup (default)               |
+| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
+| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
 
 #### hack gateway disable
 
@@ -743,10 +740,10 @@ Usage: `hack gateway disable [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 ### hack node
 
@@ -754,20 +751,20 @@ Usage: `hack node <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `init` | Initialize this host as a node and emit enrollment bundle |
-| `pair` | Pair node with one-command or expiring verification-code flow |
-| `ssh` | Manage SSH bootstrap for node pairing and remote runs |
-| `add` | Add a node from an enrollment bundle |
-| `list` | List registered nodes |
-| `status` | Probe node health and report live status |
-| `use` | Set default node |
-| `remove` | Remove node registration |
-| `workspace` | Inspect and repair node workspace map entries |
-| `routes` | Inspect and repair controller-side remote route bridge |
-| `provider` | Manage provider-specific node bootstrap workflows |
-| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints |
+| Subcommand     | Summary                                                       |
+| -------------- | ------------------------------------------------------------- |
+| `init`         | Initialize this host as a node and emit enrollment bundle     |
+| `pair`         | Pair node with one-command or expiring verification-code flow |
+| `ssh`          | Manage SSH bootstrap for node pairing and remote runs         |
+| `add`          | Add a node from an enrollment bundle                          |
+| `list`         | List registered nodes                                         |
+| `status`       | Probe node health and report live status                      |
+| `use`          | Set default node                                              |
+| `remove`       | Remove node registration                                      |
+| `workspace`    | Inspect and repair node workspace map entries                 |
+| `routes`       | Inspect and repair controller-side remote route bridge        |
+| `provider`     | Manage provider-specific node bootstrap workflows             |
+| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints    |
 
 Examples:
 
@@ -872,12 +869,12 @@ Usage: `hack node workspace <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List node-local workspace map entries |
-| `resolve` | Resolve a map entry by controller project selector |
-| `attach` | Attach an existing local workspace to project selector |
-| `remove` | Remove a map entry by project selector |
+| Subcommand | Summary                                                |
+| ---------- | ------------------------------------------------------ |
+| `list`     | List node-local workspace map entries                  |
+| `resolve`  | Resolve a map entry by controller project selector     |
+| `attach`   | Attach an existing local workspace to project selector |
+| `remove`   | Remove a map entry by project selector                 |
 
 Examples:
 
@@ -894,10 +891,10 @@ Usage: `hack node routes <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `status` | Show controller-side remote route bridge state |
-| `repair` | Re-render and re-apply persisted route bridge stack |
+| Subcommand | Summary                                             |
+| ---------- | --------------------------------------------------- |
+| `status`   | Show controller-side remote route bridge state      |
+| `repair`   | Re-render and re-apply persisted route bridge stack |
 
 Examples:
 
@@ -913,11 +910,11 @@ Usage: `hack dispatch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `run` | Dispatch a command to a node workspace |
-| `status` | Show dispatched run status |
-| `logs` | Show or follow persisted/remote run logs |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `run`      | Dispatch a command to a node workspace   |
+| `status`   | Show dispatched run status               |
+| `logs`     | Show or follow persisted/remote run logs |
 
 #### hack dispatch run
 
@@ -926,15 +923,15 @@ Usage: `hack dispatch run --project <name|id> [options] -- <command...>`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name|id>` | string | - | Project name or id |
-| `--node <id|default|auto>` | string | auto | Target node id, or use default/auto |
+| --- | --- | --- | --- | --- | --- | --- |
+| `--project <name | id>` | string | - | Project name or id |
+| `--node <id | default | auto>` | string | auto | Target node id, or use default/auto |
 | `--provider <provider>` | string | - | Provider route override used when resolving profile/bootstrap intent |
 | `--profile <profile-id>` | string | - | Provider profile route override |
 | `--bootstrap-if-needed` | boolean | false | Allow guarded provider bootstrap handoff when no reachable node is found |
 | `--branch <branch>` | string | current | Target branch on selected node |
 | `--ticket <ticket-id>` | string | - | Ticket id to associate with run metadata |
-| `--runner <generic|codex|claude|cursor>` | string | `generic` | Runner identity for policy and audit |
+| `--runner <generic | codex | claude | cursor>` | string | `generic` | Runner identity for policy and audit |
 | `--approve` | boolean | false | Approve high/critical risk commands non-interactively |
 | `--pr` | boolean | false | Push branch + create/update GitHub PR on successful run |
 | `--pr-base <branch>` | string | `main` | Base branch used with `--pr` |
@@ -981,12 +978,12 @@ If you run `hack remote` with no subcommand, it prints status and offers to run
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `setup` | Run the guided gateway setup |
-| `status` | Show remote/gateway status |
-| `monitor` | Open a remote status TUI |
-| `qr` | Print a QR payload for remote access |
+| Subcommand | Summary                              |
+| ---------- | ------------------------------------ |
+| `setup`    | Run the guided gateway setup         |
+| `status`   | Show remote/gateway status           |
+| `monitor`  | Open a remote status TUI             |
+| `qr`       | Print a QR payload for remote access |
 
 #### hack remote setup
 
@@ -994,13 +991,13 @@ Usage: `hack remote setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--qr` | boolean | true | Force QR output after setup (default) |
-| `--no-qr` | boolean | false | Skip QR output after setup |
-| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
+| Flag                 | Type    | Default | Description                                         |
+| -------------------- | ------- | ------- | --------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
+| `--project <name>`   | string  | -       | Target a registered project by name                 |
+| `--qr`               | boolean | true    | Force QR output after setup (default)               |
+| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
+| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
 
 #### hack remote status
 
@@ -1008,10 +1005,10 @@ Usage: `hack remote status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack remote monitor
 
@@ -1019,10 +1016,10 @@ Usage: `hack remote monitor [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack remote qr
 
@@ -1048,9 +1045,9 @@ Usage: `hack x <namespace> <command> [args...]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `args` | string[] | no | Extension command args (passed through) |
+| Name   | Type     | Required | Description                             |
+| ------ | -------- | -------- | --------------------------------------- |
+| `args` | string[] | no       | Extension command args (passed through) |
 
 Notes:
 
@@ -1065,15 +1062,15 @@ Usage: `hack setup <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `cursor` | Install Cursor rules for hack CLI usage |
-| `claude` | Install Claude Code hooks for hack CLI usage |
-| `codex` | Install Codex skill for hack CLI usage |
-| `tickets` | Install Codex skill for hack tickets usage |
-| `agents` | Install AGENTS.md / CLAUDE.md snippets |
-| `sync` | Refresh agent docs, skills, and MCP configs |
-| `mcp` | Install MCP configs for hack CLI usage (no-shell only) |
+| Subcommand | Summary                                                |
+| ---------- | ------------------------------------------------------ |
+| `cursor`   | Install Cursor rules for hack CLI usage                |
+| `claude`   | Install Claude Code hooks for hack CLI usage           |
+| `codex`    | Install Codex skill for hack CLI usage                 |
+| `tickets`  | Install Codex skill for hack tickets usage             |
+| `agents`   | Install AGENTS.md / CLAUDE.md snippets                 |
+| `sync`     | Refresh agent docs, skills, and MCP configs            |
+| `mcp`      | Install MCP configs for hack CLI usage (no-shell only) |
 
 #### hack setup cursor
 
@@ -1081,12 +1078,12 @@ Usage: `hack setup cursor [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup claude
 
@@ -1094,12 +1091,12 @@ Usage: `hack setup claude [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup codex
 
@@ -1107,12 +1104,12 @@ Usage: `hack setup codex [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup agents
 
@@ -1120,14 +1117,14 @@ Usage: `hack setup agents [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported docs |
-| `--agents-md` | boolean | false | Target AGENTS.md |
-| `--claude-md` | boolean | false | Target CLAUDE.md |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean | false   | Target all supported docs                      |
+| `--agents-md`        | boolean | false   | Target AGENTS.md                               |
+| `--claude-md`        | boolean | false   | Target CLAUDE.md                               |
+| `--check`            | boolean | false   | Check whether integration is installed         |
+| `--remove`           | boolean | false   | Remove integration files/config                |
 
 #### hack setup sync
 
@@ -1135,13 +1132,13 @@ Usage: `hack setup sync [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Target global (user) scope only |
-| `--all-scopes` | boolean | false | Target both project and global (user) scopes |
-| `--check` | boolean | false | Check whether integrations are installed |
-| `--remove` | boolean | false | Remove generated integration files/config |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--global`           | boolean | false   | Target global (user) scope only                |
+| `--all-scopes`       | boolean | false   | Target both project and global (user) scopes   |
+| `--check`            | boolean | false   | Check whether integrations are installed       |
+| `--remove`           | boolean | false   | Remove generated integration files/config      |
 
 Automatic guardrail:
 
@@ -1154,16 +1151,16 @@ Usage: `hack setup mcp [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor integration |
-| `--claude` | boolean | false | Target Claude integration |
-| `--codex` | boolean | false | Target Codex integration |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--all`              | boolean | false   | Target all supported clients                     |
+| `--cursor`           | boolean | false   | Target Cursor integration                        |
+| `--claude`           | boolean | false   | Target Claude integration                        |
+| `--codex`            | boolean | false   | Target Codex integration                         |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 ### hack agent
 
@@ -1171,11 +1168,11 @@ Usage: `hack agent <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `prime` | Print agent primer text |
+| Subcommand | Summary                         |
+| ---------- | ------------------------------- |
+| `prime`    | Print agent primer text         |
 | `patterns` | Print agent init patterns guide |
-| `init` | Print agent init prompt |
+| `init`     | Print agent init prompt         |
 
 #### hack agent init
 
@@ -1183,10 +1180,10 @@ Usage: `hack agent init [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `-c`, `--client <cursor|claude|codex|print>` | string | - | Open init prompt in an agent client (or print) |
+| Flag                    | Type   | Default | Description                                    |
+| ----------------------- | ------ | ------- | ---------------------------------------------- | ------ | --- | ---------------------------------------------- |
+| `-p`, `--path <dir>`    | string | -       | Run against a repo path (overrides cwd search) |
+| `-c`, `--client <cursor | claude | codex   | print>`                                        | string | -   | Open init prompt in an agent client (or print) |
 
 ### hack mcp
 
@@ -1194,11 +1191,11 @@ Usage: `hack mcp <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `serve` | Run the MCP server over stdio |
-| `install` | Install MCP config for supported clients |
-| `print` | Print MCP config snippets |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `serve`    | Run the MCP server over stdio            |
+| `install`  | Install MCP config for supported clients |
+| `print`    | Print MCP config snippets                |
 
 #### hack mcp install
 
@@ -1206,17 +1203,17 @@ Usage: `hack mcp install [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <user|project>` | string | `user` | Write MCP config to user or project scope |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor MCP config |
-| `--claude` | boolean | false | Target Claude CLI MCP config |
-| `--codex` | boolean | false | Target Codex MCP config |
-| `--docs` | boolean | false | Update AGENTS.md and CLAUDE.md with hack usage |
-| `--agents-md` | boolean | false | Update AGENTS.md with hack usage |
-| `--claude-md` | boolean | false | Update CLAUDE.md with hack usage |
+| Flag                 | Type      | Default | Description                                    |
+| -------------------- | --------- | ------- | ---------------------------------------------- | ----------------------------------------- |
+| `--scope <user       | project>` | string  | `user`                                         | Write MCP config to user or project scope |
+| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean   | false   | Target all supported clients                   |
+| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
+| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
+| `--codex`            | boolean   | false   | Target Codex MCP config                        |
+| `--docs`             | boolean   | false   | Update AGENTS.md and CLAUDE.md with hack usage |
+| `--agents-md`        | boolean   | false   | Update AGENTS.md with hack usage               |
+| `--claude-md`        | boolean   | false   | Update CLAUDE.md with hack usage               |
 
 Notes:
 
@@ -1229,14 +1226,14 @@ Usage: `hack mcp print [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <user|project>` | string | `user` | Print MCP config for user or project scope |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor MCP config |
-| `--claude` | boolean | false | Target Claude CLI MCP config |
-| `--codex` | boolean | false | Target Codex MCP config |
+| Flag                 | Type      | Default | Description                                    |
+| -------------------- | --------- | ------- | ---------------------------------------------- | ------------------------------------------ |
+| `--scope <user       | project>` | string  | `user`                                         | Print MCP config for user or project scope |
+| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean   | false   | Target all supported clients                   |
+| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
+| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
+| `--codex`            | boolean   | false   | Target Codex MCP config                        |
 
 ## Diagnostics commands
 
@@ -1275,17 +1272,17 @@ Usage: `hack daemon <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `start` | Start hackd (local daemon) |
-| `stop` | Stop hackd |
-| `restart` | Restart hackd |
-| `status` | Show hackd status |
-| `metrics` | Show hackd metrics |
-| `logs` | Show hackd logs |
-| `clear` | Clear stale hackd pid/socket files |
-| `install` | Install hackd as a launchd service (macOS) |
-| `uninstall` | Uninstall hackd launchd service (macOS) |
+| Subcommand  | Summary                                    |
+| ----------- | ------------------------------------------ |
+| `start`     | Start hackd (local daemon)                 |
+| `stop`      | Stop hackd                                 |
+| `restart`   | Restart hackd                              |
+| `status`    | Show hackd status                          |
+| `metrics`   | Show hackd metrics                         |
+| `logs`      | Show hackd logs                            |
+| `clear`     | Clear stale hackd pid/socket files         |
+| `install`   | Install hackd as a launchd service (macOS) |
+| `uninstall` | Uninstall hackd launchd service (macOS)    |
 
 Autostart + self-heal behavior:
 
@@ -1302,9 +1299,9 @@ Usage: `hack daemon start [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--foreground` | boolean | false | Run hackd in the foreground (debug) |
+| Flag           | Type    | Default | Description                         |
+| -------------- | ------- | ------- | ----------------------------------- |
+| `--foreground` | boolean | false   | Run hackd in the foreground (debug) |
 
 #### hack daemon status
 
@@ -1312,9 +1309,9 @@ Usage: `hack daemon status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output JSON (machine-readable, includes launchd info on macOS) |
+| Flag     | Type    | Default | Description                                                    |
+| -------- | ------- | ------- | -------------------------------------------------------------- |
+| `--json` | boolean | false   | Output JSON (machine-readable, includes launchd info on macOS) |
 
 #### hack daemon logs
 
@@ -1322,35 +1319,32 @@ Usage: `hack daemon logs [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--tail <n>` | number | 200 | Tail last N log lines |
+| Flag         | Type   | Default | Description           |
+| ------------ | ------ | ------- | --------------------- |
+| `--tail <n>` | number | 200     | Tail last N log lines |
 
 #### hack daemon install
 
 Usage: `hack daemon install [options]`
 
-Installs hackd as a launchd service on macOS. The daemon will be managed by launchd
-and can optionally start automatically on login.
+Installs hackd as a launchd service on macOS. The daemon will be managed by launchd and can optionally start automatically on login.
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--run-at-load` | boolean | true | Start hackd automatically on login |
-| `--no-run-at-load` | boolean | - | Do not start hackd automatically on login |
-| `--gui-only` | boolean | true | Only run in GUI sessions (Aqua) |
-| `--no-gui-only` | boolean | - | Run in all session types (including SSH) |
+| Flag               | Type    | Default | Description                               |
+| ------------------ | ------- | ------- | ----------------------------------------- |
+| `--run-at-load`    | boolean | true    | Start hackd automatically on login        |
+| `--no-run-at-load` | boolean | -       | Do not start hackd automatically on login |
+| `--gui-only`       | boolean | true    | Only run in GUI sessions (Aqua)           |
+| `--no-gui-only`    | boolean | -       | Run in all session types (including SSH)  |
 
-The service uses the label `dance.hack.hackd` and writes its plist to
-`~/Library/LaunchAgents/dance.hack.hackd.plist`.
+The service uses the label `dance.hack.hackd` and writes its plist to `~/Library/LaunchAgents/dance.hack.hackd.plist`.
 
 #### hack daemon uninstall
 
 Usage: `hack daemon uninstall`
 
-Uninstalls the hackd launchd service on macOS. Removes the plist and unloads
-the service from launchd.
+Uninstalls the hackd launchd service on macOS. Removes the plist and unloads the service from launchd.
 
 ### hack log-pipe
 
@@ -1358,10 +1352,10 @@ Usage: `hack log-pipe [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--format <auto|docker-compose|plain>` | string | `auto` | How to parse incoming lines from stdin |
-| `--stream <stdout|stderr>` | string | `stdout` | Treat stdin as stdout or stderr |
+| Flag              | Type           | Default | Description |
+| ----------------- | -------------- | ------- | ----------- | ------------------------------- | -------------------------------------- |
+| `--format <auto   | docker-compose | plain>` | string      | `auto`                          | How to parse incoming lines from stdin |
+| `--stream <stdout | stderr>`       | string  | `stdout`    | Treat stdin as stdout or stderr |
 
 ### hack help
 
@@ -1369,9 +1363,9 @@ Usage: `hack help [path...]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `path` | string[] | no | Command path to show help for (e.g. `global logs`) |
+| Name   | Type     | Required | Description                                        |
+| ------ | -------- | -------- | -------------------------------------------------- |
+| `path` | string[] | no       | Command path to show help for (e.g. `global logs`) |
 
 ### hack update
 
@@ -1379,12 +1373,12 @@ Usage: `hack update [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--check` | boolean | false | Check for updates (do not install) |
-| `--yes` | boolean | false | Apply update without prompting |
-| `--tag <tag>` | string | - | Update to a specific release tag (e.g. v1.4.0) |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag          | Type    | Default | Description                                    |
+| ------------- | ------- | ------- | ---------------------------------------------- |
+| `--check`     | boolean | false   | Check for updates (do not install)             |
+| `--yes`       | boolean | false   | Apply update without prompting                 |
+| `--tag <tag>` | string  | -       | Update to a specific release tag (e.g. v1.4.0) |
+| `--json`      | boolean | false   | Output JSON (machine-readable)                 |
 
 ### hack version
 
@@ -1398,23 +1392,23 @@ Usage: `hack secrets <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `set` | Store a secret |
-| `get` | Print a secret (exit 1 if missing) |
-| `delete` | Delete a stored secret |
+| Subcommand | Summary                            |
+| ---------- | ---------------------------------- |
+| `set`      | Store a secret                     |
+| `get`      | Print a secret (exit 1 if missing) |
+| `delete`   | Delete a stored secret             |
 
 Options (all subcommands):
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| Flag                  | Type   | Default    | Description                       |
+| --------------------- | ------ | ---------- | --------------------------------- |
 | `--service <service>` | string | `hack-cli` | Override Bun.secrets service name |
 
 Arguments (set/get/delete):
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | no | Secret name (prompted if omitted) |
+| Name   | Type   | Required | Description                       |
+| ------ | ------ | -------- | --------------------------------- |
+| `name` | string | no       | Secret name (prompted if omitted) |
 
 ## Fun
 
@@ -1424,7 +1418,7 @@ Usage: `hack the planet [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--variant <cut|mash|cycle|random>` | string | `cycle` | Animation variant |
-| `--loop` | boolean | true | Loop until Ctrl+C |
+| Flag            | Type    | Default | Description       |
+| --------------- | ------- | ------- | ----------------- | ------ | ------- | ----------------- |
+| `--variant <cut | mash    | cycle   | random>`          | string | `cycle` | Animation variant |
+| `--loop`        | boolean | true    | Loop until Ctrl+C |
diff --git a/docs/extensions.md b/docs/extensions.md
index 689dc93c5..2a6155c37 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -1,7 +1,6 @@
 # Extensions & SDK (v0.1)
 
-This doc defines the extension surface area for `hack` and how extension commands are authored,
-configured, and dispatched.
+This doc defines the extension surface area for `hack` and how extension commands are authored, configured, and dispatched.
 
 ## Quick start (one command)
 
@@ -11,8 +10,7 @@ If you just want remote access working, start here:
 hack remote setup
 ```
 
-The wizard enables the gateway for the current project, creates a token + QR, and can configure
-Cloudflare/Tailscale/SSH exposure in one flow.
+The wizard enables the gateway for the current project, creates a token + QR, and can configure Cloudflare/Tailscale/SSH exposure in one flow.
 
 ## Behavior
 
@@ -20,8 +18,7 @@ Cloudflare/Tailscale/SSH exposure in one flow.
 - Each extension provides a manifest + commands (`ExtensionDefinition`).
 - The CLI dispatches extension commands via `hack x <namespace> <command>`.
 - Global enablement lives in `~/.hack/hack.config.json` (`hack config set --global ...`).
-- Per-project overrides live in `.hack/hack.config.json` and typically win over global values
-  (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
+- Per-project overrides live in `.hack/hack.config.json` and typically win over global values (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
 - Built-in Gateway enablement is project-scoped: `controlPlane.gateway.enabled` opts a project into routing.
 
 ## Extension definition (API surface)
@@ -47,14 +44,14 @@ export type ExtensionCommand = {
 ```
 
 The `ExtensionCommandContext` includes:
+
 - `controlPlaneConfig` (parsed config)
 - `projectId` and `projectName` (when available)
 - `logger` and `cwd`
 
 ## Config + enablement
 
-Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by
-`src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
+Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by `src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
 
 Enable a global extension by id:
 
@@ -78,10 +75,10 @@ Shortcut for gateway (project-scoped):
 }
 ```
 
-Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config.
-Project overrides for these are ignored.
+Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config. Project overrides for these are ignored.
 
 CLI helpers:
+
 - `hack gateway enable` (sets both gateway + extension flags)
 - `hack gateway setup` (guided enable + optional writes + token creation + QR by default)
 - `hack config set --global 'controlPlane.extensions[\"dance.hack.gateway\"].enabled' true`
@@ -106,10 +103,10 @@ Use `hack x <namespace> help` to list commands.
 - GitHub: `hack x github connect|oauth-connect|disconnect|profiles|use|status|pr-upsert`
 - Linear: `hack x linear setup|connect|oauth-connect|disconnect|status|profiles|use|projects|project-bind|sync-issue|sync-project`
 
-Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also
-requires global `controlPlane.gateway.allowWrites = true`).
+Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also requires global `controlPlane.gateway.allowWrites = true`).
 
 Current gateway API surface (HTTP/WS):
+
 - `GET /v1/status`, `GET /v1/metrics`, `GET /v1/projects`, `GET /v1/ps`
 - `GET/POST /control-plane/projects/:id/jobs`
 - `GET /control-plane/projects/:id/jobs/:jobId`
@@ -120,6 +117,7 @@ Current gateway API surface (HTTP/WS):
 - `WS /control-plane/projects/:id/shells/:shellId/stream` (requires write token + allowWrites)
 
 Local auth service surface (daemon + global Caddy route):
+
 - `GET /health`
 - `GET /v1/auth/providers`
 - `GET /gh/start` (GitHub browser OAuth entrypoint)
@@ -128,15 +126,14 @@ Local auth service surface (daemon + global Caddy route):
 - `GET /v1/auth/github/start`
 - `GET /v1/auth/github/flows/:id`
 
-Interactive shell/TTY is available via the shell stream endpoints; use
-`hack x supervisor shell` or see protocol below.
+Interactive shell/TTY is available via the shell stream endpoints; use `hack x supervisor shell` or see protocol below.
 
 For full usage guidance and structured workflow patterns, see `gateway-api.md`.
 
 For exposure helpers, see the guides:
+
 - `guides/remote-cloudflare.md`
-- `guides/remote-tailscale.md`
-DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
+- `guides/remote-tailscale.md` DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
 
 ## Command reference
 
@@ -148,13 +145,14 @@ Usage: `hack x gateway token-create [options] [label]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <read|write>` | string | `read` | Token scope |
-| `--write` | boolean | false | Shortcut for `--scope write` |
-| `--label <label>` | string | - | Optional label |
+| Flag              | Type    | Default | Description                  |
+| ----------------- | ------- | ------- | ---------------------------- | ----------- |
+| `--scope <read    | write>` | string  | `read`                       | Token scope |
+| `--write`         | boolean | false   | Shortcut for `--scope write` |
+| `--label <label>` | string  | -       | Optional label               |
 
 Notes:
+
 - The first non-flag argument is treated as the label if `--label` is not used.
 
 #### token-list
@@ -175,11 +173,11 @@ Usage: `hack x supervisor job-list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-create
 
@@ -187,14 +185,14 @@ Usage: `hack x supervisor job-create [options] -- <command...>`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--runner <name>` | string | `generic` | Runner name |
-| `--cwd <path>` | string | - | Working directory (relative to project root) |
-| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
-| `--json` | boolean | false | Output JSON |
+| Flag                | Type    | Default   | Description                                  |
+| ------------------- | ------- | --------- | -------------------------------------------- |
+| `--project <name>`  | string  | -         | Target a registered project                  |
+| `--path <dir>`      | string  | -         | Target a repo path                           |
+| `--runner <name>`   | string  | `generic` | Runner name                                  |
+| `--cwd <path>`      | string  | -         | Working directory (relative to project root) |
+| `--env <KEY=VALUE>` | string  | -         | Environment override (repeatable)            |
+| `--json`            | boolean | false     | Output JSON                                  |
 
 ### GitHub extension (`hack x github`)
 
@@ -257,10 +255,9 @@ hack x github pr-upsert \
 ```
 
 Notes:
-- Profile config lives at:
-  `controlPlane.extensions["dance.hack.github"].config.profiles`.
-- Profile selection precedence is:
-  `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
+
+- Profile config lives at: `controlPlane.extensions["dance.hack.github"].config.profiles`.
+- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
 - Keychain storage uses profile-specific `authRef` + `service`.
 - Token resolution order is keychain first, then environment fallback (`tokenEnv`).
 - If token metadata includes `expiresAt`, auth resolution attempts automatic GitHub App refresh using profile `appId`, `installationId`, and private key source.
@@ -339,8 +336,7 @@ Detailed design and sequencing live in:
 
 ### Linear extension (`hack x linear`)
 
-Linear integration supports multiple auth profiles, project-level binding, and manual sync in both
-directions between Linear issues and hack tickets.
+Linear integration supports multiple auth profiles, project-level binding, and manual sync in both directions between Linear issues and hack tickets.
 
 Quick start:
 
@@ -363,11 +359,9 @@ hack x linear sync-project --from hack --owner both
 ```
 
 Notes:
-- Profile selection precedence is:
-  `--profile` -> `controlPlane.routing.overrides.linear.profile` ->
-  `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
-- Project mapping is stored in project config:
-  `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
+
+- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.linear.profile` -> `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
+- Project mapping is stored in project config: `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
 - Sync is manual by default (`sync-issue` / `sync-project`); there is no background autosync yet.
 - Ticket provenance is preserved during sync via `owner`, `source`, `tags`, and `external*` linkage fields.
 - `hack x linear connect` uses token mode when `--token`/`--stdin`/`$HACK_LINEAR_API_TOKEN` is present, and otherwise falls back to browser OAuth.
@@ -380,8 +374,7 @@ Notes:
 - Auth-broker Linear endpoints:
   - OAuth callback page: `/linear/callback`
   - Webhook ingest: `/linear/webhooks` (legacy alias: `/v1/integrations/linear/webhook`)
-- Sync toggles are configurable at
-  `controlPlane.extensions["dance.hack.linear"].config.sync`:
+- Sync toggles are configurable at `controlPlane.extensions["dance.hack.linear"].config.sync`:
   - `labels` (default `false`)
   - `statuses` (default `true`)
   - `dependencies` (default `true`)
@@ -394,11 +387,11 @@ Usage: `hack x supervisor job-show <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-cancel
 
@@ -406,10 +399,10 @@ Usage: `hack x supervisor job-cancel <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
+| Flag               | Type   | Default | Description                 |
+| ------------------ | ------ | ------- | --------------------------- |
+| `--project <name>` | string | -       | Target a registered project |
+| `--path <dir>`     | string | -       | Target a repo path          |
 
 #### job-tail
 
@@ -417,15 +410,15 @@ Usage: `hack x supervisor job-tail <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--logs-from <n>` | number | 0 | Resume from log offset |
-| `--from <n>` | number | 0 | Alias for `--logs-from` |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--follow`         | boolean | true    | Follow logs (default)       |
+| `--no-follow`      | boolean | false   | Print logs and exit         |
+| `--logs-from <n>`  | number  | 0       | Resume from log offset      |
+| `--from <n>`       | number  | 0       | Alias for `--logs-from`     |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-attach
 
@@ -433,16 +426,16 @@ Usage: `hack x supervisor job-attach <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--logs-from <n>` | number | 0 | Resume from log offset |
-| `--from <n>` | number | 0 | Alias for `--logs-from` |
-| `--events-from <n>` | number | 0 | Resume from event sequence |
-| `--json` | boolean | false | Output JSON |
+| Flag                | Type    | Default | Description                 |
+| ------------------- | ------- | ------- | --------------------------- |
+| `--project <name>`  | string  | -       | Target a registered project |
+| `--path <dir>`      | string  | -       | Target a repo path          |
+| `--follow`          | boolean | true    | Follow logs (default)       |
+| `--no-follow`       | boolean | false   | Print logs and exit         |
+| `--logs-from <n>`   | number  | 0       | Resume from log offset      |
+| `--from <n>`        | number  | 0       | Alias for `--logs-from`     |
+| `--events-from <n>` | number  | 0       | Resume from event sequence  |
+| `--json`            | boolean | false   | Output JSON                 |
 
 #### shell
 
@@ -450,20 +443,21 @@ Usage: `hack x supervisor shell [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--project-id <id>` | string | - | Target by project id (gateway) |
-| `--path <dir>` | string | - | Target a repo path |
-| `--gateway <url>` | string | `http://127.0.0.1:7788` | Gateway URL |
-| `--token <token>` | string | - | Gateway write token |
-| `--shell <path>` | string | - | Shell path |
-| `--cwd <path>` | string | - | Working directory |
-| `--cols <n>` | number | - | Terminal columns |
-| `--rows <n>` | number | - | Terminal rows |
-| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
+| Flag                | Type   | Default                 | Description                       |
+| ------------------- | ------ | ----------------------- | --------------------------------- |
+| `--project <name>`  | string | -                       | Target a registered project       |
+| `--project-id <id>` | string | -                       | Target by project id (gateway)    |
+| `--path <dir>`      | string | -                       | Target a repo path                |
+| `--gateway <url>`   | string | `http://127.0.0.1:7788` | Gateway URL                       |
+| `--token <token>`   | string | -                       | Gateway write token               |
+| `--shell <path>`    | string | -                       | Shell path                        |
+| `--cwd <path>`      | string | -                       | Working directory                 |
+| `--cols <n>`        | number | -                       | Terminal columns                  |
+| `--rows <n>`        | number | -                       | Terminal rows                     |
+| `--env <KEY=VALUE>` | string | -                       | Environment override (repeatable) |
 
 Notes:
+
 - `--project` and `--project-id` are mutually exclusive.
 
 ### Cloudflare extension (`hack x cloudflare`)
@@ -474,15 +468,15 @@ Usage: `hack x cloudflare tunnel-print [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--hostname <host>` | string | - | Gateway hostname |
-| `--tunnel <name>` | string | `hack-gateway` | Tunnel name |
-| `--origin <url>` | string | `http://127.0.0.1:7788` | Gateway origin |
-| `--ssh-hostname <host>` | string | - | SSH hostname (optional) |
-| `--ssh-origin <url>` | string | `ssh://127.0.0.1:22` | SSH origin |
-| `--credentials-file <path>` | string | - | Cloudflared credentials file |
-| `--out <path>` | string | - | Write config to a file |
+| Flag                        | Type   | Default                 | Description                  |
+| --------------------------- | ------ | ----------------------- | ---------------------------- |
+| `--hostname <host>`         | string | -                       | Gateway hostname             |
+| `--tunnel <name>`           | string | `hack-gateway`          | Tunnel name                  |
+| `--origin <url>`            | string | `http://127.0.0.1:7788` | Gateway origin               |
+| `--ssh-hostname <host>`     | string | -                       | SSH hostname (optional)      |
+| `--ssh-origin <url>`        | string | `ssh://127.0.0.1:22`    | SSH origin                   |
+| `--credentials-file <path>` | string | -                       | Cloudflared credentials file |
+| `--out <path>`              | string | -                       | Write config to a file       |
 
 #### tunnel-setup
 
@@ -509,11 +503,11 @@ Usage: `hack x cloudflare tunnel-start [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path |
-| `--out <path>` | string | - | Alias for `--config` |
-| `--tunnel <name>` | string | - | Override tunnel name |
+| Flag              | Type   | Default                     | Description          |
+| ----------------- | ------ | --------------------------- | -------------------- |
+| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path          |
+| `--out <path>`    | string | -                           | Alias for `--config` |
+| `--tunnel <name>` | string | -                           | Override tunnel name |
 
 #### tunnel-stop
 
@@ -525,10 +519,10 @@ Usage: `hack x cloudflare access-setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--ssh-hostname <host>` | string | - | SSH hostname |
-| `--user <user>` | string | - | SSH username |
+| Flag                    | Type   | Default | Description  |
+| ----------------------- | ------ | ------- | ------------ |
+| `--ssh-hostname <host>` | string | -       | SSH hostname |
+| `--user <user>`         | string | -       | SSH username |
 
 ### Tailscale extension (`hack x tailscale`)
 
@@ -561,6 +555,7 @@ Usage: `hack x tailscale oauth-disconnect [--auth-ref <ref>] [--json]`
 Usage: `hack x tailscale ip [args...]`
 
 Notes:
+
 - `status` and `ip` forward extra args directly to `tailscale`.
 - `ip` defaults to `-4` when no args are provided.
 
@@ -609,17 +604,18 @@ The gateway binds to `127.0.0.1` by default. Expose it through one of:
 - SSH tunnel (ad‑hoc): `ssh -L 7788:127.0.0.1:7788 <host>`
 - Zero Trust/VPN (persistent): Tailscale, Cloudflare, etc. targeting the gateway port
 - Optional Caddy route for local convenience (`https://gateway.hack`):
-  - Add a small labeled container in the global Caddy compose that proxies to
-    `host.docker.internal:7788` (or `host-gateway` on Linux).
+  - Add a small labeled container in the global Caddy compose that proxies to `host.docker.internal:7788` (or `host-gateway` on Linux).
 
 Keep tokens read-only unless you explicitly need writes.
 
 Recommended order:
-1) Start with SSH tunneling for quick remote access.
-2) Move to a private Zero Trust/VPN network once you want persistent access.
-3) Add the Caddy route only for nicer local URLs (not required for remote access).
+
+1. Start with SSH tunneling for quick remote access.
+2. Move to a private Zero Trust/VPN network once you want persistent access.
+3. Add the Caddy route only for nicer local URLs (not required for remote access).
 
 Remote helper commands:
+
 - `hack remote status` shows gateway + exposure status.
 - `hack remote qr` emits QR payloads for SSH or gateway clients.
 

From 66fbf02f6ed7c9a52d8813a0250b246bfb7340be Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 19:10:48 +0000
Subject: [PATCH 076/134] HACK-459: checkpoint merge prep

---
 tests/env-backend-command.test.ts | 174 ++++++++++++++++--------------
 1 file changed, 91 insertions(+), 83 deletions(-)

diff --git a/tests/env-backend-command.test.ts b/tests/env-backend-command.test.ts
index 36f7702b8..737af43e3 100644
--- a/tests/env-backend-command.test.ts
+++ b/tests/env-backend-command.test.ts
@@ -86,96 +86,104 @@ test("env backend use encrypted_file persists selection", async () => {
   expect(configText).toContain('"/tmp/custom-secrets.enc.json"');
 });
 
-test("env backend use encrypted_file can provision a stable key file", async () => {
-  if (!(tempDir && tempGlobalConfigPath)) {
-    throw new Error("Missing temp global config state");
-  }
+test(
+  "env backend use encrypted_file can provision a stable key file",
+  async () => {
+    if (!(tempDir && tempGlobalConfigPath)) {
+      throw new Error("Missing temp global config state");
+    }
 
-  const keyPath = resolve(tempDir, "secrets-file.key");
-  const result = await runHack({
-    args: [
-      "env",
-      "backend",
-      "use",
-      "encrypted_file",
-      "--store-path",
-      "/tmp/custom-secrets.enc.json",
-      "--key-path",
-      keyPath,
-      "--provision-key",
-      "--json",
-    ],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath,
-    },
-  });
-  expect(result.exitCode).toBe(0);
+    const keyPath = resolve(tempDir, "secrets-file.key");
+    const result = await runHack({
+      args: [
+        "env",
+        "backend",
+        "use",
+        "encrypted_file",
+        "--store-path",
+        "/tmp/custom-secrets.enc.json",
+        "--key-path",
+        keyPath,
+        "--provision-key",
+        "--json",
+      ],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath,
+      },
+    });
+    expect(result.exitCode).toBe(0);
 
-  const json = JSON.parse(result.stdout) as {
-    readonly backend: string;
-    readonly encrypted_file: {
-      readonly path: string;
-      readonly keyPath?: string;
+    const json = JSON.parse(result.stdout) as {
+      readonly backend: string;
+      readonly encrypted_file: {
+        readonly path: string;
+        readonly keyPath?: string;
+      };
     };
-  };
-  expect(json.backend).toBe("encrypted_file");
-  expect(json.encrypted_file.keyPath).toBe(keyPath);
+    expect(json.backend).toBe("encrypted_file");
+    expect(json.encrypted_file.keyPath).toBe(keyPath);
 
-  const keyText = await readFile(keyPath, "utf8");
-  expect(keyText.trim().length).toBeGreaterThan(10);
+    const keyText = await readFile(keyPath, "utf8");
+    expect(keyText.trim().length).toBeGreaterThan(10);
 
-  const configText = await readFile(tempGlobalConfigPath, "utf8");
-  expect(configText).toContain('"keyPath"');
-  expect(configText).toContain(keyPath);
-});
+    const configText = await readFile(tempGlobalConfigPath, "utf8");
+    expect(configText).toContain('"keyPath"');
+    expect(configText).toContain(keyPath);
+  },
+  { timeout: 40_000 }
+);
 
-test("env backend use cloud requires provider and stores cloud settings", async () => {
-  const invalid = await runHack({
-    args: ["env", "backend", "use", "cloud"],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-    },
-  });
-  expect(invalid.exitCode).toBe(1);
-  expect(`${invalid.stdout}\n${invalid.stderr}`).toContain(
-    "Cloud backend requires --provider"
-  );
+test(
+  "env backend use cloud requires provider and stores cloud settings",
+  async () => {
+    const invalid = await runHack({
+      args: ["env", "backend", "use", "cloud"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+      },
+    });
+    expect(invalid.exitCode).toBe(1);
+    expect(`${invalid.stdout}\n${invalid.stderr}`).toContain(
+      "Cloud backend requires --provider"
+    );
 
-  const valid = await runHack({
-    args: [
-      "env",
-      "backend",
-      "use",
-      "cloud",
-      "--provider",
-      "aws",
-      "--secret-project",
-      "dev-account",
-      "--secret-prefix",
-      "hack-cli",
-      "--json",
-    ],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-    },
-  });
-  expect(valid.exitCode).toBe(0);
-  const json = JSON.parse(valid.stdout) as {
-    readonly backend: string;
-    readonly cloud: {
-      readonly provider?: string;
-      readonly project?: string;
-      readonly secretPrefix: string;
+    const valid = await runHack({
+      args: [
+        "env",
+        "backend",
+        "use",
+        "cloud",
+        "--provider",
+        "aws",
+        "--secret-project",
+        "dev-account",
+        "--secret-prefix",
+        "hack-cli",
+        "--json",
+      ],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+      },
+    });
+    expect(valid.exitCode).toBe(0);
+    const json = JSON.parse(valid.stdout) as {
+      readonly backend: string;
+      readonly cloud: {
+        readonly provider?: string;
+        readonly project?: string;
+        readonly secretPrefix: string;
+      };
     };
-  };
-  expect(json.backend).toBe("cloud");
-  expect(json.cloud.provider).toBe("aws");
-  expect(json.cloud.project).toBe("dev-account");
-  expect(json.cloud.secretPrefix).toBe("hack-cli");
-});
+    expect(json.backend).toBe("cloud");
+    expect(json.cloud.provider).toBe("aws");
+    expect(json.cloud.project).toBe("dev-account");
+    expect(json.cloud.secretPrefix).toBe("hack-cli");
+  },
+  { timeout: 40_000 }
+);
 
 test(
   "env set --secret stores value using encrypted backend",
@@ -262,7 +270,7 @@ test(
     expect(apiKey?.source).toBe("keychain");
     expect(apiKey?.value).toBe("super-secret");
   },
-  { timeout: 20_000 }
+  { timeout: 40_000 }
 );
 
 async function runHack(input: {

From 3bb11fbc6e75bf63b4067260a101406c2c1731b5 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 19:18:13 +0000
Subject: [PATCH 077/134] HACK-448: checkpoint merge prep

---
 docs/cli.md        | 58 +++++++++++++++++++++++-----------------------
 docs/extensions.md |  6 ++---
 2 files changed, 32 insertions(+), 32 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 61e0c0e35..53c3e3234 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -61,12 +61,12 @@ Usage: `hack global <subcommand>`
 Subcommands:
 
 | Subcommand   | Summary                                                      |
-| ------------ | ------------------------------------------------------------ | ------- | ---- | ------ |
+| ------------ | ------------------------------------------------------------ |
 | `install`    | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy     |
 | `up`         | Start global infra containers                                |
 | `down`       | Stop global infra containers                                 |
 | `status`     | Show status for global infra (containers + networks)         |
-| `logs`       | Tail global infra logs (caddy                                | grafana | loki | alloy) |
+| `logs`       | Tail global infra logs (`caddy`, `grafana`, `loki`, `alloy`) |
 | `ca`         | Export Caddy Local CA cert (print path or PEM)               |
 | `cert`       | Generate local TLS certs via mkcert (for non-Caddy services) |
 | `trust`      | Trust Caddy Local CA (macOS) so https://\*.hack is trusted   |
@@ -199,13 +199,13 @@ Usage: `hack up [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `-d`, `--detach` | boolean | false | Run in background (docker compose up -d) |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto \| local \| remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack down
 
@@ -214,12 +214,12 @@ Usage: `hack down [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto \| local \| remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack restart
 
@@ -228,12 +228,12 @@ Usage: `hack restart [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto \| local \| remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack ps
 
@@ -550,8 +550,8 @@ Usage: `hack env backend use <keychain|encrypted_file|cloud> [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- | --- |
-| `--provider <aws | gcp | azure | vault>` | string | - | Cloud provider when backend is `cloud` |
+| --- | --- | --- | --- |
+| `--provider <aws \| gcp \| azure \| vault>` | string | - | Cloud provider when backend is `cloud` |
 | `--store-path <path>` | string | - | Encrypted file path when backend is `encrypted_file` |
 | `--secret-project <id>` | string | - | Optional cloud account/project identifier |
 | `--secret-prefix <prefix>` | string | - | Optional cloud secret name prefix |
@@ -923,15 +923,15 @@ Usage: `hack dispatch run --project <name|id> [options] -- <command...>`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- | --- |
-| `--project <name | id>` | string | - | Project name or id |
-| `--node <id | default | auto>` | string | auto | Target node id, or use default/auto |
+| --- | --- | --- | --- |
+| `--project <name \| id>` | string | - | Project name or id |
+| `--node <id \| default \| auto>` | string | auto | Target node id, or use default/auto |
 | `--provider <provider>` | string | - | Provider route override used when resolving profile/bootstrap intent |
 | `--profile <profile-id>` | string | - | Provider profile route override |
 | `--bootstrap-if-needed` | boolean | false | Allow guarded provider bootstrap handoff when no reachable node is found |
 | `--branch <branch>` | string | current | Target branch on selected node |
 | `--ticket <ticket-id>` | string | - | Ticket id to associate with run metadata |
-| `--runner <generic | codex | claude | cursor>` | string | `generic` | Runner identity for policy and audit |
+| `--runner <generic \| codex \| claude \| cursor>` | string | `generic` | Runner identity for policy and audit |
 | `--approve` | boolean | false | Approve high/critical risk commands non-interactively |
 | `--pr` | boolean | false | Push branch + create/update GitHub PR on successful run |
 | `--pr-base <branch>` | string | `main` | Base branch used with `--pr` |
@@ -1181,9 +1181,9 @@ Usage: `hack agent init [options]`
 Options:
 
 | Flag                    | Type   | Default | Description                                    |
-| ----------------------- | ------ | ------- | ---------------------------------------------- | ------ | --- | ---------------------------------------------- |
+| ----------------------- | ------ | ------- | ---------------------------------------------- |
 | `-p`, `--path <dir>`    | string | -       | Run against a repo path (overrides cwd search) |
-| `-c`, `--client <cursor | claude | codex   | print>`                                        | string | -   | Open init prompt in an agent client (or print) |
+| `-c`, `--client <cursor \| claude \| codex \| print>` | string | - | Open init prompt in an agent client (or print) |
 
 ### hack mcp
 
@@ -1203,9 +1203,9 @@ Usage: `hack mcp install [options]`
 
 Options:
 
-| Flag                 | Type      | Default | Description                                    |
-| -------------------- | --------- | ------- | ---------------------------------------------- | ----------------------------------------- |
-| `--scope <user       | project>` | string  | `user`                                         | Write MCP config to user or project scope |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `--scope <user \| project>` | string | `user` | Write MCP config to user or project scope |
 | `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
 | `--all`              | boolean   | false   | Target all supported clients                   |
 | `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
@@ -1226,9 +1226,9 @@ Usage: `hack mcp print [options]`
 
 Options:
 
-| Flag                 | Type      | Default | Description                                    |
-| -------------------- | --------- | ------- | ---------------------------------------------- | ------------------------------------------ |
-| `--scope <user       | project>` | string  | `user`                                         | Print MCP config for user or project scope |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `--scope <user \| project>` | string | `user` | Print MCP config for user or project scope |
 | `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
 | `--all`              | boolean   | false   | Target all supported clients                   |
 | `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
@@ -1352,10 +1352,10 @@ Usage: `hack log-pipe [options]`
 
 Options:
 
-| Flag              | Type           | Default | Description |
-| ----------------- | -------------- | ------- | ----------- | ------------------------------- | -------------------------------------- |
-| `--format <auto   | docker-compose | plain>` | string      | `auto`                          | How to parse incoming lines from stdin |
-| `--stream <stdout | stderr>`       | string  | `stdout`    | Treat stdin as stdout or stderr |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--format <auto \| docker-compose \| plain>` | string | `auto` | How to parse incoming lines from stdin |
+| `--stream <stdout \| stderr>` | string | `stdout` | Treat stdin as stdout or stderr |
 
 ### hack help
 
@@ -1418,7 +1418,7 @@ Usage: `hack the planet [options]`
 
 Options:
 
-| Flag            | Type    | Default | Description       |
-| --------------- | ------- | ------- | ----------------- | ------ | ------- | ----------------- |
-| `--variant <cut | mash    | cycle   | random>`          | string | `cycle` | Animation variant |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--variant <cut \| mash \| cycle \| random>` | string | `cycle` | Animation variant |
 | `--loop`        | boolean | true    | Loop until Ctrl+C |
diff --git a/docs/extensions.md b/docs/extensions.md
index 2a6155c37..d90809452 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -145,9 +145,9 @@ Usage: `hack x gateway token-create [options] [label]`
 
 Options:
 
-| Flag              | Type    | Default | Description                  |
-| ----------------- | ------- | ------- | ---------------------------- | ----------- |
-| `--scope <read    | write>` | string  | `read`                       | Token scope |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--scope <read \| write>` | string | `read` | Token scope |
 | `--write`         | boolean | false   | Shortcut for `--scope write` |
 | `--label <label>` | string  | -       | Optional label               |
 

From cf74c612841ca50a816c622bc65118abecd12c1b Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:44:12 +0000
Subject: [PATCH 078/134] docs(linear): align help with project routing UX

---
 docs/cli.md                                     | 2 +-
 src/control-plane/extensions/linear/commands.ts | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 34e0b73fc..788db28b0 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -28,7 +28,7 @@ Run `hack help` or `hack help <command>` for interactive help.
 | `hack open` | Open a URL for the project (default: https://<project>.hack) | Project |
 | `hack tui` | Open the project TUI (services + logs) | Project |
 | `hack branch` | Manage branch aliases for a project | Project |
-| `hack linear` | Linear account connection and ticket sync | Project |
+| `hack linear` | Linear project routing, connection status, and ticket sync | Project |
 | `hack config` | Read/write hack.config.json values | Project |
 | `hack env` | Manage project environment variables and secrets | Project |
 | `hack session` | Manage terminal sessions for hack projects | Project |
diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index 670890055..c06ac858a 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -62,7 +62,7 @@ const TRAILING_SLASH_REGEX = /\/+$/;
 export const LINEAR_COMMANDS: readonly ExtensionCommand[] = [
   {
     name: "setup",
-    summary: "Enable Linear extension and wire project defaults",
+    summary: "Set the active Linear profile and repo project route",
     scope: "project",
     allowWhenDisabled: true,
     handler: async ({ ctx, args }) => {
@@ -290,7 +290,7 @@ export const LINEAR_COMMANDS: readonly ExtensionCommand[] = [
   },
   {
     name: "status",
-    summary: "Show Linear profile/config resolution and token status",
+    summary: "Show the active Linear profile, repo route, and next steps",
     scope: "global",
     allowWhenDisabled: true,
     handler: async ({ ctx, args }) =>
@@ -738,7 +738,7 @@ export const LINEAR_COMMANDS: readonly ExtensionCommand[] = [
   },
   {
     name: "project-bind",
-    summary: "Bind current hack project to a default Linear profile/project",
+    summary: "Bind this repo to its default Linear project route",
     scope: "project",
     allowWhenDisabled: true,
     handler: async ({ ctx, args }) => {

From 0b5078c255b72c30f99eee1edf42df4dee787bf7 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:45:01 +0000
Subject: [PATCH 079/134] feat: harden project ownership inspection

---
 .hack/hack.config.json              |   5 ++
 docs/cli.md                         |  28 ++++++++
 src/commands/project-admin.ts       |   4 ++
 src/commands/projects.ts            |  19 ++++--
 src/lib/project-meta.ts             |   6 +-
 src/lib/project-views.ts            |   2 +-
 src/lib/project.ts                  | 100 ++++++++++++++++++++++------
 tests/project-config.test.ts        |  42 ++++++++++++
 tests/project-owner-command.test.ts |  85 ++++++++++++++++++++---
 tests/project-views.test.ts         |  23 +++++++
 tests/runtime-cache.test.ts         |   1 +
 11 files changed, 277 insertions(+), 38 deletions(-)

diff --git a/.hack/hack.config.json b/.hack/hack.config.json
index 43867b9e4..fd4279595 100644
--- a/.hack/hack.config.json
+++ b/.hack/hack.config.json
@@ -11,6 +11,11 @@
         "enabled": true
       }
     },
+    "tickets": {
+      "git": {
+        "enabled": false
+      }
+    },
     "gateway": {
       "enabled": true
     }
diff --git a/docs/cli.md b/docs/cli.md
index beeffda24..ca457cb27 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -35,6 +35,7 @@ Current practical rule:
 | `hack status` | Show project status (shortcut for `hack projects --details`) | Global |
 | `hack usage` | Show resource usage across running projects | Global |
 | `hack init` | Initialize a repo (generate .hack/ with compose + config) | Project |
+| `hack project` | Inspect or manage project metadata | Project |
 | `hack up` | Start project services (docker compose up) | Project |
 | `hack down` | Stop project services (docker compose down) | Project |
 | `hack restart` | Restart project services (down then up) | Project |
@@ -209,6 +210,33 @@ Options:
 | `--oauth-tld <tld>` | string | `gy` | OAuth alias TLD override |
 | `--no-discovery` | boolean | false | Skip discovery and generate a minimal compose |
 
+### hack project
+
+Usage: `hack project [options]`
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `owner` | Inspect or manage project ownership |
+
+#### hack project owner show
+
+Usage: `hack project owner show [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+Notes:
+
+- This is a read-only ownership inspection surface.
+- If the project config cannot be parsed, the command fails instead of guessing a local owner.
+
 ### hack up
 
 Usage: `hack up [options]`
diff --git a/src/commands/project-admin.ts b/src/commands/project-admin.ts
index 9c06016b4..2a8ea64e2 100644
--- a/src/commands/project-admin.ts
+++ b/src/commands/project-admin.ts
@@ -50,6 +50,10 @@ const handleOwnerShow: CommandHandlerFor<typeof ownerShowSpec> = async ({
     projectOpt: args.options.project,
   });
   const config = await readProjectConfig(project);
+  if (config.parseError) {
+    const configPath = config.configPath ?? project.configFile;
+    throw new Error(`Failed to parse ${configPath}: ${config.parseError}`);
+  }
   const payload = {
     project_root: project.projectRoot,
     ownership: {
diff --git a/src/commands/projects.ts b/src/commands/projects.ts
index d3c040cb6..bf15ae88f 100644
--- a/src/commands/projects.ts
+++ b/src/commands/projects.ts
@@ -573,13 +573,20 @@ async function renderProjectMeta(opts: {
 }): Promise<void> {
   await display.section("Meta");
 
+  const ownershipEntries: Array<readonly [string, string]> = opts.meta.ownership
+    ? [
+        ["Ownership mode", opts.meta.ownership.mode],
+        ["Owner type", opts.meta.ownership.ownerType],
+        ["Owner id", opts.meta.ownership.ownerId ?? ""],
+        ["Managed by", opts.meta.ownership.managedBy],
+      ]
+    : [["Ownership", "unavailable"]];
+  if (opts.meta.configError) {
+    ownershipEntries.push(["Config error", opts.meta.configError]);
+  }
+
   await display.kv({
-    entries: [
-      ["Ownership mode", opts.meta.ownership.mode],
-      ["Owner type", opts.meta.ownership.ownerType],
-      ["Owner id", opts.meta.ownership.ownerId ?? ""],
-      ["Managed by", opts.meta.ownership.managedBy],
-    ],
+    entries: ownershipEntries,
   });
   await renderGitMeta({ git: opts.meta.git });
   await renderGitWorktrees({ worktrees: opts.meta.git.worktrees });
diff --git a/src/lib/project-meta.ts b/src/lib/project-meta.ts
index 538cccc78..255973beb 100644
--- a/src/lib/project-meta.ts
+++ b/src/lib/project-meta.ts
@@ -73,7 +73,8 @@ export type ComposeBuildMeta = {
 };
 
 export type ProjectMeta = {
-  readonly ownership: ProjectOwnershipConfig;
+  readonly ownership: ProjectOwnershipConfig | null;
+  readonly configError: string | null;
   readonly git: GitMeta;
   readonly hackBranches: HackBranchesMeta;
   readonly env: EnvMeta;
@@ -108,7 +109,8 @@ export async function resolveProjectMeta(opts: {
     ]);
 
   return {
-    ownership: config.ownership,
+    ownership: config.parseError ? null : config.ownership,
+    configError: config.parseError ?? null,
     git,
     hackBranches,
     env,
diff --git a/src/lib/project-views.ts b/src/lib/project-views.ts
index 6548b51dc..a95a4e32e 100644
--- a/src/lib/project-views.ts
+++ b/src/lib/project-views.ts
@@ -275,7 +275,7 @@ async function buildRegisteredProjectView(opts: {
     devHost: opts.registration.devHost ?? null,
     repoRoot: opts.registration.repoRoot,
     projectDir: opts.registration.projectDir,
-    ownership: config?.ownership ?? null,
+    ownership: config && !config.parseError ? config.ownership : null,
     definedServices,
     extensionsEnabled: extensions?.enabled ?? null,
     features: extensions?.features ?? null,
diff --git a/src/lib/project.ts b/src/lib/project.ts
index 90b1317fe..74ec35264 100644
--- a/src/lib/project.ts
+++ b/src/lib/project.ts
@@ -145,6 +145,11 @@ export interface ProjectOwnershipConfig {
   readonly managedBy: ProjectOwnershipManager;
 }
 
+type ParsedProjectOwnership = {
+  readonly ownership: ProjectOwnershipConfig;
+  readonly parseError?: string;
+};
+
 export interface ProjectSessionsConfig {
   /**
    * Mux backend for `hack session`.
@@ -323,7 +328,11 @@ function parseProjectConfigToml(opts: {
 
 function parseProjectConfigRecord(value: unknown, path: string): ProjectConfig {
   if (!isRecord(value)) {
-    return { configPath: path, ownership: defaultProjectOwnership() };
+    return {
+      configPath: path,
+      parseError: "Project config root must be an object.",
+      ownership: defaultProjectOwnership(),
+    };
   }
 
   const name = getString(value, "name");
@@ -338,7 +347,7 @@ function parseProjectConfigRecord(value: unknown, path: string): ProjectConfig {
     lifecycle: lifecycleBase,
     startup,
   });
-  const ownership = parseProjectOwnership(getRecord(value, "ownership"));
+  const parsedOwnership = parseProjectOwnership(value.ownership);
 
   return {
     ...(name ? { name } : {}),
@@ -348,7 +357,10 @@ function parseProjectConfigRecord(value: unknown, path: string): ProjectConfig {
     ...(internal ? { internal } : {}),
     ...(sessions ? { sessions } : {}),
     ...(lifecycle ? { lifecycle } : {}),
-    ownership,
+    ownership: parsedOwnership.ownership,
+    ...(parsedOwnership.parseError
+      ? { parseError: parsedOwnership.parseError }
+      : {}),
     configPath: path,
   };
 }
@@ -362,26 +374,72 @@ export function defaultProjectOwnership(): ProjectOwnershipConfig {
   };
 }
 
-function parseProjectOwnership(
-  value: Record<string, unknown> | undefined
-): ProjectOwnershipConfig {
-  const mode =
-    parseProjectOwnershipMode(value ? getString(value, "mode") : undefined) ??
-    "local";
+function parseProjectOwnership(value: unknown): ParsedProjectOwnership {
+  if (value === undefined) {
+    return { ownership: defaultProjectOwnership() };
+  }
+  if (!isRecord(value)) {
+    return {
+      ownership: defaultProjectOwnership(),
+      parseError: "Project ownership must be an object.",
+    };
+  }
+
+  const modeValue = value.mode;
+  const mode = parseProjectOwnershipMode(
+    typeof modeValue === "string" ? modeValue : undefined
+  );
+  if (modeValue !== undefined && mode === undefined) {
+    return {
+      ownership: defaultProjectOwnership(),
+      parseError: "Project ownership.mode must be 'local' or 'shared'.",
+    };
+  }
+  if (modeValue === undefined) {
+    if (value.owner_type !== undefined || value.owner_id !== undefined) {
+      return {
+        ownership: defaultProjectOwnership(),
+        parseError:
+          "Project ownership.mode is required when ownership.owner_type or ownership.owner_id is set.",
+      };
+    }
+    return { ownership: defaultProjectOwnership() };
+  }
   if (mode === "local") {
-    return defaultProjectOwnership();
+    return { ownership: defaultProjectOwnership() };
+  }
+
+  const ownerTypeValue = value.owner_type;
+  const ownerType = parseProjectOwnershipOwnerType(
+    typeof ownerTypeValue === "string" ? ownerTypeValue : undefined
+  );
+  if (ownerType === undefined) {
+    return {
+      ownership: defaultProjectOwnership(),
+      parseError:
+        "Project ownership.owner_type must be 'user', 'team', or 'organization'.",
+    };
+  }
+
+  const ownerIdValue = value.owner_id;
+  if (
+    ownerIdValue !== undefined &&
+    ownerIdValue !== null &&
+    typeof ownerIdValue !== "string"
+  ) {
+    return {
+      ownership: defaultProjectOwnership(),
+      parseError: "Project ownership.owner_id must be a string when provided.",
+    };
   }
 
   return {
-    mode: "shared",
-    ownerType:
-      parseProjectOwnershipOwnerType(
-        value ? getString(value, "owner_type") : undefined
-      ) ?? "team",
-    ownerId: normalizeProjectOwnerId(
-      value ? getString(value, "owner_id") : undefined
-    ),
-    managedBy: "broker",
+    ownership: {
+      mode: "shared",
+      ownerType,
+      ownerId: normalizeProjectOwnerId(ownerIdValue),
+      managedBy: "broker",
+    },
   };
 }
 
@@ -403,7 +461,9 @@ function parseProjectOwnershipOwnerType(
   return undefined;
 }
 
-function normalizeProjectOwnerId(value: string | undefined): string | null {
+function normalizeProjectOwnerId(
+  value: string | null | undefined
+): string | null {
   const trimmed = value?.trim() ?? "";
   return trimmed.length > 0 ? trimmed : null;
 }
diff --git a/tests/project-config.test.ts b/tests/project-config.test.ts
index 6d5f59c7a..2dbe044a2 100644
--- a/tests/project-config.test.ts
+++ b/tests/project-config.test.ts
@@ -113,6 +113,48 @@ test("readProjectConfig captures parse errors", async () => {
   expect(cfg.parseError).toBeTruthy();
 });
 
+test("readProjectConfig rejects non-object config roots", async () => {
+  const ctx = await createProjectDir();
+  await writeFile(ctx.configFile, JSON.stringify(["not", "an", "object"]));
+
+  const cfg = await readProjectConfig(ctx);
+
+  expect(cfg.parseError).toBe("Project config root must be an object.");
+});
+
+test("readProjectConfig rejects malformed ownership payloads", async () => {
+  const ctx = await createProjectDir();
+  await writeFile(
+    ctx.configFile,
+    JSON.stringify({
+      ownership: [],
+    })
+  );
+
+  const cfg = await readProjectConfig(ctx);
+
+  expect(cfg.parseError).toBe("Project ownership must be an object.");
+});
+
+test("readProjectConfig rejects ownership fields without an explicit mode", async () => {
+  const ctx = await createProjectDir();
+  await writeFile(
+    ctx.configFile,
+    JSON.stringify({
+      ownership: {
+        owner_type: "team",
+        owner_id: "team_123",
+      },
+    })
+  );
+
+  const cfg = await readProjectConfig(ctx);
+
+  expect(cfg.parseError).toBe(
+    "Project ownership.mode is required when ownership.owner_type or ownership.owner_id is set."
+  );
+});
+
 test("readProjectConfig defaults ownership to local user scope", async () => {
   const ctx = await createProjectDir();
 
diff --git a/tests/project-owner-command.test.ts b/tests/project-owner-command.test.ts
index 7ff018788..c820d5bd4 100644
--- a/tests/project-owner-command.test.ts
+++ b/tests/project-owner-command.test.ts
@@ -99,12 +99,78 @@ test("project owner show returns explicit shared ownership as json", async () =>
   });
 });
 
+test("project owner show fails when config parsing fails", async () => {
+  const projectRoot = await createHackProject({
+    rawConfig: "{ invalid json",
+  });
+
+  const result = await runCliWithCapturedOutput([
+    "project",
+    "owner",
+    "show",
+    "--path",
+    projectRoot,
+    "--json",
+  ]);
+
+  expect(result.exitCode).toBe(1);
+  expect(`${result.stdout}\n${result.stderr}`).toContain("Failed to parse");
+});
+
+test("project owner show fails when ownership payload is malformed", async () => {
+  const projectRoot = await createHackProject({
+    rawConfig: JSON.stringify({
+      ownership: [],
+    }),
+  });
+
+  const result = await runCliWithCapturedOutput([
+    "project",
+    "owner",
+    "show",
+    "--path",
+    projectRoot,
+    "--json",
+  ]);
+
+  expect(result.exitCode).toBe(1);
+  expect(`${result.stdout}\n${result.stderr}`).toContain(
+    "Project ownership must be an object."
+  );
+});
+
+test("project owner show fails when ownership fields omit mode", async () => {
+  const projectRoot = await createHackProject({
+    rawConfig: JSON.stringify({
+      ownership: {
+        owner_type: "team",
+        owner_id: "team_123",
+      },
+    }),
+  });
+
+  const result = await runCliWithCapturedOutput([
+    "project",
+    "owner",
+    "show",
+    "--path",
+    projectRoot,
+    "--json",
+  ]);
+
+  expect(result.exitCode).toBe(1);
+  expect(`${result.stdout}\n${result.stderr}`).toContain(
+    "Project ownership.mode is required when ownership.owner_type or ownership.owner_id is set."
+  );
+});
+
 async function createHackProject(opts?: {
   readonly ownership?: {
     readonly mode: "local" | "shared";
     readonly owner_type: "user" | "team" | "organization";
     readonly owner_id?: string;
   };
+  readonly rawConfig?: string;
 }): Promise<string> {
   if (!tempDir) {
     throw new Error("Missing temp directory");
@@ -117,15 +183,16 @@ async function createHackProject(opts?: {
   await writeFile(join(projectDir, PROJECT_ENV_FILENAME), "");
   await writeFile(
     join(projectDir, PROJECT_CONFIG_FILENAME),
-    JSON.stringify(
-      opts?.ownership
-        ? {
-            ownership: opts.ownership,
-          }
-        : {},
-      null,
-      2
-    )
+    opts?.rawConfig ??
+      JSON.stringify(
+        opts?.ownership
+          ? {
+              ownership: opts.ownership,
+            }
+          : {},
+        null,
+        2
+      )
   );
 
   return projectRoot;
diff --git a/tests/project-views.test.ts b/tests/project-views.test.ts
index 65a7e2928..99b179795 100644
--- a/tests/project-views.test.ts
+++ b/tests/project-views.test.ts
@@ -228,6 +228,29 @@ test("buildProjectViews includes explicit project ownership metadata", async ()
   });
 });
 
+test("buildProjectViews omits ownership when config parsing fails", async () => {
+  const alpha = await createProject({
+    name: "alpha",
+    services: ["api"],
+    configJson: "{ invalid json",
+  });
+
+  const views = await buildProjectViews({
+    registryProjects: [alpha],
+    runtime: [],
+    runtimeOk: true,
+    filter: null,
+    includeUnregistered: false,
+    muxSessions: [],
+  });
+
+  const alphaView = views.find((view) => view.name === "alpha");
+  expect(alphaView?.ownership).toBeNull();
+
+  const serialized = alphaView ? serializeProjectView(alphaView) : null;
+  expect(serialized?.ownership).toBeNull();
+});
+
 test("buildProjectViews includes lifecycle and startup summaries", async () => {
   const lifecycleConfig = JSON.stringify(
     {
diff --git a/tests/runtime-cache.test.ts b/tests/runtime-cache.test.ts
index fe2c96196..bbbba334f 100644
--- a/tests/runtime-cache.test.ts
+++ b/tests/runtime-cache.test.ts
@@ -175,6 +175,7 @@ test("getProjectsPayload keeps working when resolveProjectMeta fails for one pro
             ownerId: null,
             managedBy: "local",
           },
+          configError: null,
           git: {
             isRepo: false,
             head: null,

From 66b9fa52d07c85d1a7198a203bb37c7ba760089f Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:45:30 +0000
Subject: [PATCH 080/134] chore: remove unrelated merge-prep artifacts

---
 .cursor/rules/hack.mdc                          |   6 ------
 .../hack-449-normalized-ticket-model.bundle     | Bin 11271 -> 0 bytes
 2 files changed, 6 deletions(-)
 delete mode 100644 artifacts/hack-449-normalized-ticket-model.bundle

diff --git a/.cursor/rules/hack.mdc b/.cursor/rules/hack.mdc
index 8f55277b3..835164c17 100644
--- a/.cursor/rules/hack.mdc
+++ b/.cursor/rules/hack.mdc
@@ -37,12 +37,6 @@ hack down
 hack global status
 hack session
 hack tickets list
-hack node list
-hack node status --watch
-hack node ssh setup --node <id>
-hack node routes status
-hack node routes repair
-hack dispatch run --project <name|id> --node default --branch <branch> --runner generic -- "pwd"
 hack internal extra-hosts list
 hack internal extra-hosts set <hostname> <target>
 hack internal extra-hosts unset <hostname>
diff --git a/artifacts/hack-449-normalized-ticket-model.bundle b/artifacts/hack-449-normalized-ticket-model.bundle
deleted file mode 100644
index 5548df9950f8825da5d0cfca17a83918d93b1297..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 11271
zcmV+iEcnwSAa*h!XK8dGVs&n0Y-I{9I5jggH85r{Vq!C6GB;ymVK*@~GdN>5W;r-v
zG-WkoHaR#rWnpGDAY*86a%CuTWo%_(b7d(yATcg6H!d*>WMwomV`X78H!wA3Vly)_
zI5K27H#lWtF=043I5aV2VqrNkVl_E8AaZ49b1!IRVPtbJXklY(Ei^PaEpBgeZDDL_
zdSzrSbZKL2WppiVZ)9a`3JOp`LrVYv00IC201llIc$}q=OKt-p5JdN!qL+yxMKI6<
zSXPupc0L84CP5w;3wIXI>5Vi;NUf?~wOT43M3AM%q&!AbFebg&X;)7at)b{u@zQEJ
zk+_9Hox!0tD2t3yr^TietU~S5TD%K}Fs<G>3I#>@<)3}PS8bI?g$wmg`2pvAfa{Sz
zzgwu=d)nIvC~LJb3he@Ka!O1(Z<+r0MHCAB!Zlrq@2@AwRB9*a`)FaSf0W_qV9u-j
zfVOAa#1j=|TMYUIOi0y<MQ*prwnImA9Fh+3rr9Qgc$@)R0Hy!#4DJlDsRR_Y0^`og
ze1Hs>!dkP#-$-?iqUT?;y#y`+G-b<5IU>Kv>Hzj#24c$OQ#=e~I5aRYFfbr=Wpi|M
z07N0NcKHuIM!<xGmd%sIn1tcgNRuB1PjAX7nD7G36K>M?#B}o}Um2noT;O670!C|i
zoO{9if_Z}!qew+poS&rEiXy?cojPe+7V<$Y*E=WcG428Y#sds3{05Hmu!?f1)tgeu
zB1*)aF_l@*^bL5N0c-%1|E&e#1(53$2gcDFe!8lIw!vp9^+cpl4|FUlvHz9<Of7D2
za&2L3X?kIFX>V>WZDatkU-&;gvI+QAzAx*&uk);)qch4eFfcYWG$3?oV{2t}b1rRU
z0H-M?D<LAfKuiW<ka)Uc>TkMbCqcR{Uh@(H^V^%$9~Qr0k?ySNJ4tkYDA}!eoJEgK
zP6IIvg;#XZ0{}~}k!EreHgt(ZLhR{8P3+3{&<>j(h6`{Yj==$lDgnzUy`S%W-G1MH
zzHBbLnSe!Gs^y&!l#VrJYQzqcDELf9FxAv$p^65@0BI`R&4nSNWDEPHAX)H|59Bud
z_9ZXEW5c*jj1Wz8$il8thrYrT=zMWv>#o0W_=g#qAl1<=j_^n)u$6N#7fpMDljs3#
zmZc&bl_t`y&z-V^7hmC37RID2$Qvmn#KL=Mq6Cr7PRgl1#D3}S`pE_2?z;c9wAN$s
z<9T!Q11bt_ld#hQc$~FZO_Lk95xvi^Kv9=OMRF_Gm1EaNQQ1l?S*2BygUjUsXPP9u
z7+?Zmmdn`s?|I$8d~kQ|at=9cEe8Yi^w)dcjTh>ZY3?XR_1=e0Tk{{CjCbmtZ^>5G
zrz0s>UQnx2+1v43Wz9WBWt^&GXs#OXQt)=uTkYtI9um0-N%5*2x|-!|<oq_pdRx6s
zs-?Ygkd*MTMmz6Jqpc#BOggK0)IH&qPAVoJ^nsLit<tUT69pB|uE8EZ*j7P<dkWY9
z{dctYfzMH8>7bjl+FOXIv$eNF*XeMsRUiCM)QH6<szAvEYPVJO;)VL!Ya6R-qyA3R
zL*!DoY|^MAzND<j`o=qZ7WLWzPe<RuXD1)-wh;49-_dx`2XioPt=LP!X?CT%i)%T$
zHw0VskdD{|>GaTB)0ng!Re{d;rlqinJvC-;8rABgl^-B?zfe*HMLu?$^jRIqQNU($
zemERO>2Kk79oFh=lfD^t`SUkXJDol7CYyK55vZ!Vu2Zbi8PRw@MKZgyZ2YtOxl$@N
zN9y!HDRA_!)t|6*XIy)&R@wL!77QL^3dSAqFll@(=M|ikEG;%Dwe#)ytBaMGbQ&Ur
z`kvfM{i0UJ{Rqz-0>voLJA~wpTKU}~d@DJpV>AaxbSbT*0TzFTZqvJ0%IR+2sy=7+
z^dXK*-~S*>fvmtL9!(!dGZYdV%C+%3_h>r|V&xu7DdJ5>u&!GQY69s*?M=GSTB)IL
zpIK)){KttxPP>LiNjdMX%jsWWZ3&H}@9Guc6ccq=IO^tZRW!QTIi~D#vz0s&PajM=
z4m<g&Ig_xBbNg-k$cd8h*H1DD8F^Q{F(KgTuAA|d82Xu0Qxf*WWH8b-+gc;3;|a;A
zPDjdwFoF<H4shNzW4smz)T$$FUvA1$*vU+E-@q$^k`90ZfcT&DNgee)2^C?RSf<V-
zfUQS&JtO+0L7rXjSqZfdzEgU_wtS@b#(``>TYPHt2NDe*<F9NNR)W273~!34=!ekA
zHUed?MayOg0hFcu2~5DLx>Yx$G5{ev<gALsZFWd?IvUH2J5yDTI)703dMT4#B7_Xj
z9@qg@E#9bA3h-Q1q?_X`X^EPN=Ir_UH@Sv0q%h58Vlnmno`l3clqq8B5KHA%j-C7r
zv`3=gaU~L6^H<aaDG@l*57x@Aeu&3RGo~Hi0~AbW-nsnz)d)L8bq_bbZ7*3zH;o@$
zdc4d9Blfy^vVVH<e#uG&?14I;CZJysEC`q$(dQ8C<pNi4Z8$Gx)+vZD<S5oA(p~XV
z@8!p&RQ86~A-mC<m{vv5BW=_rt!B;=)UzR_vcIFGxvpW`M{0a%zsS4SrD3_vWk%b9
zz8opwU&p!3%?1Ib2?7P@x#FoIqTQ&AVYPs*X47hH$;Gg2VKaGAs$yB2EUwqH4Ez+^
z@dF^J+4`E>Cm$)}YSBd*hcwkKS8KyPQ#&+Fj2$;D6JdPFf?w8~n9hJ;^8LorJ<WBU
z8E<C7YWm60lm-i*iqz`>_Ci}Cw2)IC-BF`q3<!rYG&OdG1&n2EcDfMWhOx~}(Qlw~
z{&<EaS~@-0^l`9LO7<T32AOl}*fC#p&lNI5kkXHX18j2EoD5(Tq#|F`DD`<+jYbGx
zEV50{*B$;7_pxHg^be>2M%ypsizUsblDCpRWHmo?7qWQFEy!YF>@5~cBX$--(LF34
zrxs!P9cd0$>#{P!@qc#V|ILkav+`xde+7Q8OD!nDj~Q{fG0u5cMuBTpFA@YPQ|!4a
zMQ5Yl6cqg4gQW~|#bpOG94F5THpQhi&QCrPcp6~`P)VFBS)mB2V>?1+Hvn`lgO>0F
z9|R95aRXhr0>6YH=8jyFteOg~LZPFOA)ARyy><6G7>xp-r>xvIGj_oVJXml&0c_dr
z4Np24fgE=TmT~#F+wb1z(THpKJ)qb=ozqk|#H29A_$s2%#{HQ~HelZbALAxSzN;Wm
zkS1tu7`IZlzkm6|Hiy6FZw&B~21mht{~idbm5zp0%3s_5O0bz!r2Ehz@NhJC81;tB
z@Z|`!{q@jiW27bGj!5UYaWpRFu^3TJ+LMSvgP2QSAUuzJt&2(gu^V?@j9M8i`E-4W
zgLT1y`dnvCrZ%CFXdY4N0mL790OiS3<?qk_sdt01?Q<>7AO2Y9Fd|W6Ddwn~oCwGz
z6fv$*|M>WAM9<Gu?$R1P-ZTa`;QKsEv8$;w2_uGvR-#&tbmWFZL~>$DxbkEiWg0g4
zZnix4jx~x0I!}Mm{7wC-_`tZv4lPZgVCRloZ)cy+i}3m@iOVjS7K3^qW=Br>#&^A?
zbeRv_x-P1vbU7zPilYt-(Ld`vcuy`a71vDQl7u~RXgZm{@$Gzh(ZeYQTNmT-c)!q@
zLy*RF&0WMEoXg>k-VU-@$p8QjGMmXA!WN6V{u8@rN35t;t#5{o-Ok7J9YKa}F5xAF
zW5c8Vf~K(50VVzQqgkFc>^b}EX=W}x$Ozj4h4u4T&S_Q4pkFO_Ob`GlsyFu(&Pky4
z^s3?D%azZgHVs1Ah4i2~j>}$)%Ot0AWSVTwjg^PF(Xx8S;m~L6bsN|4KKLl{eT(5o
z95OM2Zlv$%%IBt*tbwDMjI)0@h~srmE5r(C?TSA^-ziQ(2Da%z@?pW7MGV7$uTyXi
z&`a<ZJA>FSGXjdnIf(DZlvzaY(_%cr6tdar=5BF^#)?qswmL2kMwEz8?x+Nm`SxlA
z$IH4ZU7)Hb^)s3;4l}EiL9HOp>T|9o42V9zDi>tSyD*o0^~g8nvI_%?v9lLrL5nnq
zuYJdPo<Vn6#>(wfY&@dKnUc8nHgZR|yiD6Fxa~Z)pJV%4_EaO08Fw*!W>+#S%S|Bq
zTi*%VP2kaVX-B>>9Ks%bgM#qmR9mx8nY`=gZ@7St{{nbqM{4{AC!b)TDxMk-wi|e#
zDZ9C#l`<y-c$~YZv|o9{WS)3kg^-L?g}l^?65ZmG)B=UP{G!~%oXo1!6ou5hlFX7y
zh1~p<)EtG(Vuh6a<kDQAAW$kZPay%wE!Iyj%}hxx)-TCS&Q2{U)`jU#EXmBz)5}ds
z*gTQvEDHd@(kXcV0kt@F_>Js27>df&%47%=)ib{2)Oehm#xjj%!a<P<YRYCuT9+!Z
z9Qcx{k{TqJDSqa{#;cBu0K-oVx26bqoHH>10)^CylGME7%>2A!2Ie;lmU=9ch`YAx
zc+l^vw#@teOP-p56&2*?WF}WK*qtbzeE-vD|7or2S(|Qhm!!?*eFITYlwVqsnU~HW
zpJ19$8Bisve}CD&vuo?`SZ?KC1W{3(lFh)g<%qC@x!o=KT}u}H_0)f&x7O$x0M_d`
zx$pu|Htn$v7F{&b)1lh4>hX4J&|_$LoV&<;k$J;RMv;J<Tc2OIWqeRl<}bn}nDjVI
zWuM&SwTvnN=vfUZ@&k)y=ooHiWUOqiLl?P0k^eFLo}74`0Wtv1|M3E#1CW0xZf|mJ
zVQgu7Wn?XFZ)9a`E_8DMjzoWw&g;ol^1fnn=x3vTt=XB@k$Cwqf*AX@n+$lIwLD#O
z+c=W%{uPKSm6E13n%!4<9G5rasnx|}Pub4i?WJ51Ey6a>5~(GrWPFbP`vK?%(D)*0
z@7z30WTMe%H2S+i7MpEVx2%2Ia`w!wi`64<uXdYFRzI;lyQ`}W8_j-d+N$QWwiz8B
z9PmHXj8#=OEjz!s{O#my@!zMve7RnH_;`B#<?6%VPk%f4@{iNYtHs4RJ7RxjSp(4i
zWIf~h<oeUq>6L)}e8AYK+VXNVmA{Je%eJoWYu+^Q;C5XJ0(1ByuSza{-6Zj!{@3;C
z<@w2(A?=@6*QdX!bw=x=<XJtMveA9fKJ0GgudK<+Y?Q`_XwDYrAHRIKIKMtwoS$BP
z`M5a$#n3Lu{U5$+fxwn$8~9c8Z3Vx+RrO=D%~l*YRAn`8XI(UH=XP-UlTX)wzqnjn
z|MSbQi_<f^bX&A*gEfDGUrn2}J7iwgG{t?%5yqu7yGNj$3-0I5MM)UmB*;=igCe8W
z5u}Xe!|KjI+sWs0x4Gr@&7m{-^pBR;Wwu5nPfg1=1WDom6UYF`Sy4WIsLD1I2V8$F
z%A6gEjd*0mj<6H!$*z5<>Y{!6wczVK+^2si1X+w*s|UWx{*kSBTv7L(HEms#_v$B1
zR6lR4YR$6}AFtQyN6j-K`Rk_;*XJ7r@N7XoKk}zJBEOkOR^NN{o$>o@_2im?BiAfM
zcjRzg%y<@*7%CpcDa=#Hb4VeJTvO{jF0&0kwj(~#4(3t_by1Z*4MN=SiZx&4$I%tC
z)vDT+ZEDzPZ7;xiH>u}Uy~)<a|MJ`t?UO1@)8it}h(>A1JgPSiU@Zh^E=*}%+!y6Y
z2*s#*Dp$gC%AYmA<24t5jy&Y$>X)Jh{)x$3A#n<RyK5fQkJ}>G<JsDsyfU0Wo<|SF
zC68~aRuCxnojiUjLHy}BF|@1KsiBpYvu5sVjU$GiZ{)<iD-e0M6+Hfpx8hfui6vgB
zR&gOUcH}>cQfZ2>v7jp>VRi+F**-C>&ownJMQC)G5~)DzJ=!jJYaZxNwJug-)6$i#
zrTdcdkZq;20P*7Omt85&*%ga#YMVwRyzTevhne8hlk>Z5w{9h=0do1!q2f*&ZTVCP
z!tYt#7TNk|B`TMERn_^=F&jUPVSO)Vz3->`LLHAjT(weQ4)KT&{ZXyrqlawuh{O9%
zL>!Gl8du6(IKZLVVS%9d8$B)C$k{ZY2}19bAwf^s7b-d@hFfdZDx)DjVwIIuSqPQ}
zRz(Fy2@@eBrIh)A*lF%WI39=&sZuB~$U2^fhgam@q_n@olW;dBBDOiDRf2*cbL{Lo
zlg77sD7H<62ovokQBhv0STG40P*`lZVBsdZ@Jjq@d4AF+d9d5&F^GL=ss)q3@-h?t
zEI4|wlk<dvdIU=apxcZ2>VU(UHV@$<#&RIZLt=qNx!tvaJ`MKz%B?112N?Y5c~Woq
zljlt%zVvvAGj#%y<B&Ismm@hia^amIBstN6@-VzC68Y2pydgLeN=Hu@Y}`B+dOMV^
zk;}r|CpO03`SKsxov&wodvw)K?pAFRAb!4n9|Q_n-3Ub-7jmz2wksdY>RUNsNAKCS
z!!1Z^%aqc<0&~4kQn}tMHw)Wx)>ccZC&{@8I6ZJYU7Rp*bv;x8kmkuia$u67MN;z9
z4?i5RAK2e^#X4_Trc7Ls^ZLi^zN{J{F-$vsB^HAFGLB*GL)MB|nQt3AquKIRaaXJ)
zJ}CpNC>t@rmY!@ZS)H{HA|w?^O7TB#Jt~SQgi*~*VEW1B)vcs6k=l#}BTyES2Jc`J
zACxSUjD%IRbrVPx!kK<B6T-V0PYyjuVd?~^Ime4F<Skc9)W;NsfDC2}OE_@0fF!f6
zp`_D|d2Dbh0XsfspKn|YHi@Me@TtXs56E2aP$_~FcL=d~69g)Q%W8l;i_{6B>gnil
z`SuwQgVWm2-#+VO+ApUHRJ$_@2P2TRB5%cS$r_!w>bXvis!@=KYL1(z!qnMpHYTh+
z7KWbuxo5&Q?k7lxlb$jaa_U`7@tH(t<xFBzhSWZCFj9CaSrT4ku5%)69=sJ0c(S*<
z@DEuc^PdrHdv&HYZ+CSWw?OhF$L?`Y4yhsf9pcyq?82_Dc`3|+h%L2gXs}jPlx?Me
zEH=g=NoXE2;WwH};*<5{?4Gl%%+--<@*8P%<kr9PS`3SGsY;Id1iR&TRm~N4{#6p7
zs?ri&(XdT%U(0wgVx7tkkDM@2Dc>D4R5}L&QzbG2UbiqGXI`S@aAN0Yz&E0~YtSZT
zO639kT2~tf%^0LnhYJ+V)Tkf^2zr=2Qj$Q{t1w3uIY3=}<q#1MTEoYbksKY6SqBUF
zU@d<hCP&mpp`76~sdkiv8P3p3DAS}kgsj5p<s$YheTb;?UIyEjx&k?F&N_{60shfD
z2$EK&vsG`Bc!pk%+7kyzrn2nK(UAzba(*W)N3INmeC(l9ke<2G$*uzk59x~C{t&0>
ztaySG8CWQM>aC$4<Mvdo1O5xlrxqBAP5<_`0co+J5~w>Xn%1RIf|)sqB$?6dxEG^=
zHE5Yhn0qG!pqaThyNRUGjONY`7W3RvK$2(&)I9f=#DBt!n(DB&1A-`Jv_$wK|Gg0>
z@%csr7^6TCJC3L;zMd&BMLZIEBNA;!O{BEuXv+VD6sy-8s4k+OAhXbYDvte5l+uZ5
z8{P6Ud(}xkr1!3zaAzzCSygB}NJBNEMXrz(cWnG-jI_LaXV6V1CZSYkW;UU+L2FrQ
zp*>m>kUh$q!1BMG-rx1a(2Yow|4MXns^Np7P4C@qZYCQcW33Qq?r9%YTYS$?Io3<j
zDJ>XyFZ$H6W#B0ZlVvyg<s7?Kv&`-Q$-u3d{<Yp0%ns;7=}2aQh}VhqooLzw&7PUk
zn-C)u@RJOjqkv*$>g~+QEE=s{I^2neI$ACF+JhaNmdk<mO`Um3Gy$>MMj||8eiR>p
zJN7d+9p+g3NCUb*!y+cCaB*{|mjxpyMGoR1vkzfkyeE+A9f`=r^tBMiO8Pf(lxM{w
zS0yP|(wk~mulPhEAV}c|1sczWc`|OACngYbvQvVJy1qs30KlUusgx15c&5Q2G=1DW
z7&<*uTVSKdNE=|$lk6*T#}0`grOv3Yr=}`x`s85U*`vB)A<xcm(&&s0Sy<RVoRUH4
z63Wu6-`})Qd!u=;N2|N41nXgNQiKZtN4tk6N>_2FrNq!-`=CKIN5aXMP1JGZOJ?l@
zdFstfF&FMI4Kn@xS`~f_qZII}FOqT9)r1{%wyUb1|8s+%{)PUXU@0CZ0SCbZDLQ?U
zgc>-^Afc3-nZX$um63f9H7{pt#dTd)srkQl!jClmO0sTZiIW=VcmUte{kvYEy8$IF
z4Bk|dg7HeD-5|CDFIoTHR0*P6C=wTP{3}C~`9ZXY{?azA!jcH)i~i`Wppk1iBxEgV
zaQbE}*7*Ki&Fl%zJ*%e51yB(X|2UDR%Ij%V>J<<7;h{M9tVjVZ+La>wk_My?hQ<zW
zuyryh3o%!`dU<LfX%$P~0PCG?AjxcUL9BN^fsJ7pl*l;HP~-ynuuKqQV)rEepd`{i
z&--O5CQNoAEXUwqfoNGGR29hl6#!BKB`Ezn4Q%o$_sI|uwtX5R!ri^?K!9zAODzE{
zH4aIL8_rd;hks*Ny!{z0&igSO>|Ir}v6pDG>W(?OF~9<u$=V8O9W(hL<V{6sy1oQ;
zkFm1Ijlt40A5|Z2`S#hu$aqY)hKhW@w3J9L%pS64EM`o)X;PqBo-5EpH(AJI$*jA!
zO=_LuX37Z0vR%7eRJ?4dk9e-&=FDVnex?P;LcB_53K=lO#pNs9Ku+5l9XM(00uw}7
z^TwQ&dNdh&TmT(EFgx}FKA!{)Pom2&y2|1EsaH>awF47jcwKO5k1lRy%rnCWcr^fQ
z-zM9R$C98a9N&$)SRfzh1_3@d7xr<Yu+M@~Fc&7tIcr|tw-4++`-}A=xU3$NG1^~-
zItZj(zBqD<)FZk{^!!|jbB_;it9s`WK6O<`3$;RWOzs9Cg)n}M|IX=FV)Qvd?Ca_4
zbmtR6W_4D5<MoHE;Yx))GEV*Er<aWAs};RW>kQsa7>dv`>&N$KWJE!p;yX3oQ+U6|
zlccZuk`W16qes$lcgE!hUODRT)#`Lm-JLlS`U2O1VY5><B0X%(#~@K2#j`;`G;?}~
zYU9J&hsovKZY106WDkV1zhc^#ro`4}oStNQAvHnc$2qWw;g;!GUIuKVOB=AhB@Lk2
zjS1$l1=YQfh3i|%LfSn6=gzD0bhB-rP$dzwhz&Zh6*-jx4+FSZms8NhO%h2jTgmsh
zG&iKW`Iy2^uhuD`Mu%jPY0)j&wbhGb6RnMajb48aa6*STNvUq`c2OJSUC2F+NylrQ
z+c0msDPS8?#7NYQ<S2zshbbY5A*~2Mh*aG^vXn;jndv+94kfb!wHq9Ow6+MHfQJyC
z%y<cfU>AyVwch3O;*QKUM35<QI>eJ6nk6&J+-?D2!DemMb`ZTqt}D?K8j6PWDYpCx
z6qb1D<OMWZ?m1NMt!*M#1_FbU-8Vh@tlsOS=G(dJkPv8p9cRt}1LnYcPKs;?t$09>
zy-G1)E&ICa%h!Rj`hZ37C0NfB+RGUO`DiB$@&X#z+u5S2uJzd1r-9r7iK5q|qrnL6
zO_3NvGwKMLxmp$t*|7EMJ9um;#RHm?y3U?vMWg-=r>fg1lO$Kwu!(Dg>B=M;FW>;6
zqag4A<dAmBpE7e&3#D&TDzFgyB5&gPy34mSxLOl``^3}$NP@4rs>0X<7aZT}_>eb9
zgi6~<-_qPWTE<z&-aZrPy<z08EdI6QOKSY}3NqEFD_GYMZ}?h+OLzcPfi+x4bxfl~
z6!agVx!19Oikhaj9bQo3)bcEpv#hKO#HWhuu|Ol;Aa$dQP1dd+geY7X^28xiT7^q8
zp@tDbM%b&+<8t`q-8)8F*A&3?#k<0d2u+dxRXp0(FD4*=l(d*Pj#*}KQwI9{>v?S>
z&{2EaOpD-zHg++^%bG+&*qdfLUHBl=l-$5&kLT<Xt42i0W2tDO2mg|6)a)9}xuQJM
zws-QSpu63Lm-fO(Q>x*vb+aAvRGMZX2CQm<jg2Pej@G`U+4E{;cJidd7K~FL(-1Ne
zR%vIb^H7=YFqhsQgyj?y_VRwZv>eTDE3c*V+_9P6$Hri%!`D<>pTWXQ_s&W~wQPWL
zkQW$x^uxB91LcUxzI#dN<$|xh#<1cC-un3dJsk3G|0I`kD<j$~FnZ<1mQND|bV#GF
z99d&+?*u8jU`3ZCgw{l<2~@6nkJr8gOY)6a*>LR8mo9tMHeg!F;)!tuF5xgfqBYrm
zB6|c-zij5cbvW#`vf+ZKeARFU#1Sl<($R|;9*TK*cg|D+0toX7kR*itGDv4It*%oV
z$-|rB4A4)dVpu!}JvB=A-7Q4~es|=%uN)CT^<9#Fz}Rif)YjbTdXJK(DU%DT{kaHZ
z+D~3B>!>VQsAO>|z}Ho@F+h$bASM0=zZQj$oyG07h-nJKbnlZ8q-oy|b8adoH>N!W
zT|lX#Si>R>1T0&n<5t)sX=)8(mRH&mg1|GGj+LAh>TaBHthK|@;o*qC`AJW03A}yG
z&l7slyZdPoz1|kelU8;$95qfb)M?)=>QsFkU`%}+RDw*Cw*iJ%gZ-&pONwDzyAIaf
z)$6WxKh^61zH2ct>=(+D^$G{Cy_udaSl}Au9pPm0B6T?=wWe==;CU!5W++}r(xV-^
zIPUsfUQd{fC>Zl^muN{4v6a4?Kk3$SWQmH#L>yj}Lc?@v*dgANJb%fAxZ4%9#ABPm
zoBsMDa|}~=nc0xkRbD2(%71sb!(nX@rq5kPUQ$R<i;xEMEA6aHSf7<mSrVTZYf~($
z;P!_-DkoKoCu{x!Xv!0Z)Ege-ix_Tj9KE`qs#|2Ye68;g3@T(qu@4HU)moj=Alz%$
zv8evgm>1wtAoB&X4jBKA{POLyqGXTP=#6p36{ifasz}dFUdEz4c*CGeVE`iOjbV67
zXo4rpv|XhbV_B{dzXV{AC!|rzY{yg{JPIQz@zkUOf^l-PQ|FLu>sqKsWu2)y!wQIk
zfu&JdU2>KcLGu1Ygst*FS|E?CM_%oX@B=Hae!a6~{Ewn(Wx><3gs?^TCDS?|QMmBE
zj_^)ekPS~=W%u6Ya9`C@=ORBjs>K9@aXaXDokIZlkZA`1zBHg>nfRL@k|;Npf{RER
zocaeLP5ck)A>gL8b`XI}2<^Czz4gg{mftcFNcT51)Q%DvZmv@PX%wTh+mpqu<{*z|
zWm5dP?DbpzerI7`5p1@7sH<<PiFI1nRXw&#nh=%!$JNF8kL%)*TQ{ecT24Z_joy<T
zB(PM6V=_Y7;fK%5pr|}ldODM~l;G@B>T1549Mr7<tU-w?8s^RjS)iyJ`=8YAiL;$c
zh&ms^PzA2`*eZ{3iBm?t$USBFHEw0@)yKFGy!VjO6|Q8dIM{c5c545rPkz6K4}SU5
zE4aeV$0>umj*1Cz!7<JS+Gc;9sCz=!A5^_LR~A_4#d&r<{v~TUeptcTXH-iTR~PmQ
z!ZN-i_(InI!$#Wr3AIhynNOEz<ofBJtz`cY$A?%WmG4O`DP6Qzk6&wklFl(|gAiZL
z8oHc$9Z5sP1K-6{SEFgQEJ|)!l|OPxRf2F6-1ZU+keEzNHQf88I{ys<1pNWMckd!W
z1o~O^QbN=Xq=g)&E_Epd124cW3`T<5@YGDaB_8Glyx@<q%~ZI+rpfMkN7VJkOq(Rc
z8gW?p{XgckWZd}!yh#uHI=Y<6F@T%G<uK-35R8cac$@(_0LK5LBHtpg*$^#mZ*py6
zY-xIBWG!uPWMynFbY*jNE_8DMss6zEiBC*;QOOTT#QNXPLw?N7lgbcT+Pxb4ywL@C
zoYh+WZ`(E+{=I(%;r)^Tv7OI#&9K7-Y3~}eU5CcI!&U?aEipDP5~+#QGOx)0zLy`8
zNQ#o}tj%^sfmjknz9gULc|Rzc7rd0{6C%GAB#{S55+Tt8x-EH*MvID_s~e+lpFN|t
z<uim970uG`d70yk{!Y>vP40+%OWEB4JY>QBi%PC|N#*)FS&<yan!I8%{`@Uj;$&?a
zT~~RI%e8twySjYyYBs<4arXNChpX97^M75vdi(PF;8|_=WHJ?HGEF#>CC|o1h8dZX
z-y~szaweuy_b8^VA>*8<B%4T~rV8)DA|xfjlDwmgLYr{5=sUExkG}f{ShJ^=1R<f#
z{|_nE5a;OVK;ONiEImgfGvLVFqw3CVe0X^H;)T7HV8$6uaCVMNZwSGXWCR+vBO|XD
z7*S$b324F#!kW7hFX7(DoBFyW8J23+D_V%QdxTN~uchKWb6dmaW<0s`dU$BMra6EC
z=YBtCoze>lmK+}*e?2}t86Ta@j=niRJcR!fnCH)<w*RU~`<kD1n%kl6pQ7Zy5{6kq
z+VKHeOUhh(?2^MYaOR9F)<TjT9;|S37Y=|>2JrP}jceTcYj%sPOn#^`;@$?+ct#Uw
zIw}dEEg{ap2;Ec0NC_|awzY#J_vbAoS*k`*tNajKiHCiJ1=1)5v?_w`jT$Hmgpuxl
z%vrX!m;n>y%G_=zR?kL^4h)#}j12f&W&qNM_-N5@hH=rWuCE%TpB}dWwZMKuNa0#~
z&&xaH@7jW=YfS+_an2>tyM&hnt%;m$;K5F?+zFIX;&f@l@AanpcoV!T6@2}>mb0UT
zmt@p*0C4{wXtG{J^?U9wj(z++&Q*V}p+9s{6eABO01srPeQ!v0Cj~AAahmM!Pb7c!
zONBG{=C`rlCM_)|hK=pJpIi}i&F`}DVRP@AqiyFOZ#KWufPLanH?*&Zyo0puGq+Ll
ziQS)YFdE%X7THBLgx<mk!@=7UT#n6p*CeM*a<n91G))|_JTT&RfG|s2_CE#bPdcQ(
z(oqBqpdGcDMM(D#hU<nZirs6`m<_J%R}!H<WpkMDvLr%mp#Vp_D8SLM0yO%zg%o7|
zd>b(c?qeb7k`eU;b|4}DjEaR=vjjG=ez_S;#W^Lz*>z2^p!fQ@-Y0lAKRQ0?JbXjc
zPQ1Rjd^0{hebIURW0@)LN(rIBbZQ2e;G&o+OH&29DHWn3)7~C_aKz2LKevRLAN4i1
zQfHtjP#qcR@CIEf?F?U>5uCe2NVs<T?<%anRGTH%1P+%FXu^;!6X3;Lni1Wx6`rP3
z<>y2JGUFQ7+;psK?z!W?REygpCB+5I^c|7#OJX-BQPeO)z%NBPCnPCKYD1gjczp4<
z@*DMLhOWcgEVT{Jf}Xp;-omwfRzG28v%yge_%+>Yy^})|>t7Ct`?(feYfIajB`;|S
zw&*Nnw4iBy<%AaC4p`mflY^RmQ11Zit$^Lcy(aK;&7d*e0<gpt3zYrQTBR34VtAue
zit9x5Zs_0O)T)IS`nTrB70&!)TML`FHocZ8nHw-8P{E+jZr=B0ROZGHZ*);XG~r84
zdK0@Kxxx~*7%~QH49cxFh*wh3l(adt$)I9cjp_?Ro8J0GoyymgT0+)TE$oyG67^g)
zUgj^pdG0+jK2xD;Y+$8-CK>%IZ0WmCGs-04`84vf0jHR@eZ)Z7Nq<42xU&~}`y;(O
zO)Ln98rki;Y3%5zgsTyX=B=kn5?(RmYANgm&P-Wiz~8l&_#U?xju~E%OvgsHz@x$=
z9VRuH&cQe#IopbE5of3n6uN~*q0L5~hv?{mlhJ2oUc;Jg)cLPk^-zduj0m+150fC&
z<Xs8Sr^~Ju#%Zt>5w@a&Bab(KF*+R)RSGGP@~3`kC~WQLegz|di791EWS|!)?Ng+M
zr=7I$hf1svB(MLb@^!U9_*N;rF<EDEF!e{5dyaQW_Ku&j+++2iKXda0Bgotg^_;cz
zQ@0ocBaI*9iJEQ(lZ7WP3w=DiQT@NeGFiP}s3>dLnMc$&uH$yLPn|=AwI+w;QbAo9
zz^Ov8AdrOto=r`~^8S8BSX~Kj>O&&reD)+|ptBC&-zu}Rb<J9c$fRSFo?6-^{BA{_
zlU;a!@~3&<SKEm)|4-L!oHdP=Y`RZ(tk|6W4JjUG$mWd+*KEHu5drwMy`jw6S(y!q
zvnLG?`;m+#0rN_gnz*?~d%9w>5Qv+8sUV00jITBO>Hxv_w08DAC!68SN18|0wvj5E
z*1ru`>Z`htSYP`Y>PVrn{@tLx=~W|r6q$EPR42kEtU-H<GA$BK(4n)ol!J(<;&hT#
zkfzy_9LU&o9Vxa7^~vh+N${SpH*QwiQJ}A#xUEx)R^pQb_*G2Qv95V79(D`~(CKc+
zpQl|3+ToD4SBUz{%>8n-S&-^PejolQbk0^Kzuz;+*@TOl5+WEypHH+(H&R`Dz)Ly2
zqp);~7bUO_HmXSkV9SJYfOag4bsft;NmTp1<K-HJ>C;#2nS|7t=c8lVvt4}K*%$L|
z!TrzY-JW-z`9}ci5Be{xDhKXfOT2)r<|^&H)Rg~q#jELcYp1qzVb(GHOVnitilNTP
zJC-f`iiQ4~nSTRi!dOi&^b~b)3Nzzn>idU+Qzj8yW0b2PUa7Hdu2y;zg9pFX+4J@~
z;$HfXHtHptOeSsXdg`$cQi7%qoE)j{e6-Sc*fETyJ{VeW7Asb?U%EJbY$}LuV~1BD
z?Uv_tgDCX1dHVyviuo94@2yh_F_u?Cd74{N5?K2_RCRnz4cRu1GpU&cYujPP?ilFf
zc2$%AD|CJifCQC`4nS;feY_b3JzruCe2cZ=YphtZZ3HG>0I132pSyS$@lUp#M!P||
z^M#h`+FEUm?7*7=eyETN-*I4Tzz7v-uoP#U5oefEnQp%kQ%58<<nOJAHNmiUD?qbY
z$Q}i3@aboO*`ECy*t^~K4ZzjefMBbFKsfqApCEExF}DCYu&-|J8=YV8>>fQg`zJQ9
za8?6z3XlIIinz!yK*LLrU{Hk;Rcg`-q0r~RxhstwjoU0Njig|K84f}ry)ueKQGP|J
x)tGMxv`~%#Qui^*3jnx~rDD3B{~wTsJE0wr1po3Pl*l_+jUqm>pHLC<h_2t@&cpx!


From 79ef745ce5f58d272bc052c816ca80256d5d1fcb Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:46:53 +0000
Subject: [PATCH 081/134] test(env): avoid env backend timeout flakes

---
 tests/env-backend-command.test.ts | 94 +++++++++++++++++--------------
 1 file changed, 51 insertions(+), 43 deletions(-)

diff --git a/tests/env-backend-command.test.ts b/tests/env-backend-command.test.ts
index 737af43e3..c2114a054 100644
--- a/tests/env-backend-command.test.ts
+++ b/tests/env-backend-command.test.ts
@@ -40,51 +40,59 @@ afterEach(async () => {
   }
 });
 
-test("env backend status defaults to keychain", async () => {
-  const result = await runHack({
-    args: ["env", "backend", "status", "--json"],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-    },
-  });
-  expect(result.exitCode).toBe(0);
-  const json = JSON.parse(result.stdout) as {
-    readonly backend: string;
-    readonly encrypted_file: { readonly path: string };
-  };
-  expect(json.backend).toBe("keychain");
-  expect(json.encrypted_file.path).toBe("~/.hack/secrets.enc.json");
-});
+test(
+  "env backend status defaults to keychain",
+  async () => {
+    const result = await runHack({
+      args: ["env", "backend", "status", "--json"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+      },
+    });
+    expect(result.exitCode).toBe(0);
+    const json = JSON.parse(result.stdout) as {
+      readonly backend: string;
+      readonly encrypted_file: { readonly path: string };
+    };
+    expect(json.backend).toBe("keychain");
+    expect(json.encrypted_file.path).toBe("~/.hack/secrets.enc.json");
+  },
+  { timeout: 20_000 }
+);
 
-test("env backend use encrypted_file persists selection", async () => {
-  const result = await runHack({
-    args: [
-      "env",
-      "backend",
-      "use",
-      "encrypted_file",
-      "--store-path",
-      "/tmp/custom-secrets.enc.json",
-      "--json",
-    ],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-    },
-  });
-  expect(result.exitCode).toBe(0);
-  const json = JSON.parse(result.stdout) as {
-    readonly backend: string;
-    readonly encrypted_file: { readonly path: string };
-  };
-  expect(json.backend).toBe("encrypted_file");
-  expect(json.encrypted_file.path).toBe("/tmp/custom-secrets.enc.json");
+test(
+  "env backend use encrypted_file persists selection",
+  async () => {
+    const result = await runHack({
+      args: [
+        "env",
+        "backend",
+        "use",
+        "encrypted_file",
+        "--store-path",
+        "/tmp/custom-secrets.enc.json",
+        "--json",
+      ],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+      },
+    });
+    expect(result.exitCode).toBe(0);
+    const json = JSON.parse(result.stdout) as {
+      readonly backend: string;
+      readonly encrypted_file: { readonly path: string };
+    };
+    expect(json.backend).toBe("encrypted_file");
+    expect(json.encrypted_file.path).toBe("/tmp/custom-secrets.enc.json");
 
-  const configText = await readFile(tempGlobalConfigPath!, "utf8");
-  expect(configText).toContain('"backend": "encrypted_file"');
-  expect(configText).toContain('"/tmp/custom-secrets.enc.json"');
-});
+    const configText = await readFile(tempGlobalConfigPath!, "utf8");
+    expect(configText).toContain('"backend": "encrypted_file"');
+    expect(configText).toContain('"/tmp/custom-secrets.enc.json"');
+  },
+  { timeout: 20_000 }
+);
 
 test(
   "env backend use encrypted_file can provision a stable key file",

From e1ad2e8fd9c35eec15390c07182a4d3ad2ed7a76 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:48:18 +0000
Subject: [PATCH 082/134] fix(session): preserve workspace backend for isolated
 siblings

---
 src/commands/session.ts       | 22 +++++++++++++++-------
 tests/session-command.test.ts |  9 +++++++++
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/src/commands/session.ts b/src/commands/session.ts
index 7659cf774..4c40c5216 100644
--- a/src/commands/session.ts
+++ b/src/commands/session.ts
@@ -372,7 +372,7 @@ async function handleSelectedSession(opts: {
     : await resolveCurrentProjectContext();
   const resolvedBackend = await resolveWorkspaceBackendForCreate({
     project: projectContext,
-    fallback: session.backend,
+    preferredBackendName: session.backend,
   });
   if (!resolvedBackend) {
     logger.error({
@@ -530,19 +530,19 @@ async function listWorkspaceSessions(opts: {
 
 async function resolveWorkspaceBackendForCreate(opts: {
   readonly project: ProjectContext | null;
-  readonly fallback?: MuxBackendName;
+  readonly preferredBackendName?: MuxBackendName;
 }): Promise<{
   readonly backendName: MuxBackendName;
   readonly backend: MuxBackend;
 } | null> {
   const mux = await resolveMux({ project: opts.project });
-  const backendName =
-    resolveDefaultBackendName({
+  const backendName = resolveWorkspaceBackendNameForCreate({
+    preferredBackendName: opts.preferredBackendName,
+    defaultBackendName: resolveDefaultBackendName({
       mode: mux.mode,
       backends: mux.backends,
-    }) ??
-    opts.fallback ??
-    null;
+    }),
+  });
   if (!backendName) {
     return null;
   }
@@ -553,6 +553,13 @@ async function resolveWorkspaceBackendForCreate(opts: {
   return { backendName, backend };
 }
 
+function resolveWorkspaceBackendNameForCreate(opts: {
+  readonly preferredBackendName?: MuxBackendName | null;
+  readonly defaultBackendName?: MuxBackendName | null;
+}): MuxBackendName | null {
+  return opts.preferredBackendName ?? opts.defaultBackendName ?? null;
+}
+
 function resolveWorkspaceBackendName(opts: {
   readonly workspaceName: string;
   readonly sessions: readonly MuxSession[];
@@ -1373,6 +1380,7 @@ async function runHackUp(projectPath: string): Promise<void> {
 
 export const __testOnlySessionCommand = {
   resolveNextIsolatedWorkspaceName,
+  resolveWorkspaceBackendNameForCreate,
   resolveTmuxOnlyWorkspaceError,
   resolveRunUpCwd,
   resolveWorkspaceBackendName,
diff --git a/tests/session-command.test.ts b/tests/session-command.test.ts
index ba6dff7da..5b5abddcf 100644
--- a/tests/session-command.test.ts
+++ b/tests/session-command.test.ts
@@ -97,3 +97,12 @@ test("resolveTmuxOnlyWorkspaceError explains tmux-only pane tooling on zellij",
     })
   ).toContain("tmux-only");
 });
+
+test("resolveWorkspaceBackendNameForCreate prefers the existing workspace backend over the default", () => {
+  expect(
+    __testOnlySessionCommand.resolveWorkspaceBackendNameForCreate({
+      preferredBackendName: "zellij",
+      defaultBackendName: "tmux",
+    })
+  ).toBe("zellij");
+});

From 59c5c013beb93e3995c9aa673505829ad1b2ef0b Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:49:07 +0000
Subject: [PATCH 083/134] fix(auth): allow org admins to administer teams

---
 .../auth-broker/src/modules/orgs/service.ts   | 159 +++++++++++-------
 .../tests/org-team-membership.test.ts         |  92 ++++++++++
 2 files changed, 186 insertions(+), 65 deletions(-)

diff --git a/services/auth-broker/src/modules/orgs/service.ts b/services/auth-broker/src/modules/orgs/service.ts
index 20f0522a2..88f4bd4fa 100644
--- a/services/auth-broker/src/modules/orgs/service.ts
+++ b/services/auth-broker/src/modules/orgs/service.ts
@@ -233,15 +233,14 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
     readonly orgKey: string | null;
     readonly actorUserId: string;
   }): MaybePromise<readonly TeamRecord[]> {
-    const allowedTeamIds = new Set(
+    const allowedOrgIds = new Set(
       [...this.activeMemberships.values()]
         .filter(
           (membership) =>
-            membership.scope === "team" &&
+            membership.scope === "organization" &&
             membership.userId === input.actorUserId
         )
-        .map((membership) => membership.teamId)
-        .filter((teamId): teamId is string => typeof teamId === "string")
+        .map((membership) => membership.organizationId)
     );
     const organization = input.orgKey
       ? this.findOrganization({ orgKey: input.orgKey })
@@ -250,7 +249,7 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
       if (organization && team.organizationId !== organization.id) {
         return false;
       }
-      return allowedTeamIds.has(team.id);
+      return allowedOrgIds.has(team.organizationId);
     });
   }
 
@@ -268,8 +267,8 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
     }
     const allowed = [...this.activeMemberships.values()].some(
       (membership) =>
-        membership.scope === "team" &&
-        membership.teamId === team.id &&
+        membership.scope === "organization" &&
+        membership.organizationId === team.organizationId &&
         membership.userId === input.actorUserId
     );
     return allowed ? team : null;
@@ -410,66 +409,30 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
       return null;
     }
     const normalizedTarget = input.target.trim();
-    for (const invitation of this.invitations.values()) {
-      if (
-        invitation.status === "pending" &&
-        invitation.scope === input.scope &&
-        invitation.organizationId === organization.id &&
-        invitation.teamId === (team?.id ?? null) &&
-        invitation.email === normalizedTarget
-      ) {
-        const removed: InvitationRecord = {
-          ...invitation,
-          status: "removed",
-          updatedAt: new Date().toISOString(),
-        };
-        this.invitations.set(invitation.id, removed);
-        const membership = this.toRemovedMembership({
-          scope: invitation.scope,
-          organizationId: invitation.organizationId,
-          teamId: invitation.teamId,
-          userId: null,
-          email: invitation.email,
-          target: invitation.email,
-        });
-        this.removedMemberships.set(membership.id, membership);
-        if (input.scope === "organization") {
-          this.cascadeRemovedOrganizationTarget({
-            organizationId: organization.id,
-            target: normalizedTarget,
-          });
-        }
-        return membership;
-      }
+    const teamId = team?.id ?? null;
+    const removedMembership =
+      this.removePendingInvitationMembership({
+        scope: input.scope,
+        organizationId: organization.id,
+        teamId,
+        target: normalizedTarget,
+      }) ??
+      this.removeActiveMembership({
+        scope: input.scope,
+        organizationId: organization.id,
+        teamId,
+        target: normalizedTarget,
+      });
+    if (!removedMembership) {
+      return null;
     }
-
-    for (const [key, membership] of this.activeMemberships.entries()) {
-      if (
-        membership.scope === input.scope &&
-        membership.organizationId === organization.id &&
-        membership.teamId === (team?.id ?? null) &&
-        membership.target === normalizedTarget
-      ) {
-        this.activeMemberships.delete(key);
-        const removed = this.toRemovedMembership({
-          scope: membership.scope,
-          organizationId: membership.organizationId,
-          teamId: membership.teamId,
-          userId: membership.userId,
-          email: membership.email,
-          target: membership.target,
-        });
-        this.removedMemberships.set(removed.id, removed);
-        if (input.scope === "organization") {
-          this.cascadeRemovedOrganizationTarget({
-            organizationId: organization.id,
-            target: normalizedTarget,
-          });
-        }
-        return removed;
-      }
+    if (input.scope === "organization") {
+      this.cascadeRemovedOrganizationTarget({
+        organizationId: organization.id,
+        target: normalizedTarget,
+      });
     }
-    return null;
+    return removedMembership;
   }
 
   listInvitationsForEmail(input: {
@@ -636,6 +599,72 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
     };
   }
 
+  private removePendingInvitationMembership(input: {
+    readonly scope: "organization" | "team";
+    readonly organizationId: string;
+    readonly teamId: string | null;
+    readonly target: string;
+  }): MembershipRecord | null {
+    for (const invitation of this.invitations.values()) {
+      if (
+        invitation.status !== "pending" ||
+        invitation.scope !== input.scope ||
+        invitation.organizationId !== input.organizationId ||
+        invitation.teamId !== input.teamId ||
+        invitation.email !== input.target
+      ) {
+        continue;
+      }
+      const removed: InvitationRecord = {
+        ...invitation,
+        status: "removed",
+        updatedAt: new Date().toISOString(),
+      };
+      this.invitations.set(invitation.id, removed);
+      const membership = this.toRemovedMembership({
+        scope: invitation.scope,
+        organizationId: invitation.organizationId,
+        teamId: invitation.teamId,
+        userId: null,
+        email: invitation.email,
+        target: invitation.email,
+      });
+      this.removedMemberships.set(membership.id, membership);
+      return membership;
+    }
+    return null;
+  }
+
+  private removeActiveMembership(input: {
+    readonly scope: "organization" | "team";
+    readonly organizationId: string;
+    readonly teamId: string | null;
+    readonly target: string;
+  }): MembershipRecord | null {
+    for (const [key, membership] of this.activeMemberships.entries()) {
+      if (
+        membership.scope !== input.scope ||
+        membership.organizationId !== input.organizationId ||
+        membership.teamId !== input.teamId ||
+        membership.target !== input.target
+      ) {
+        continue;
+      }
+      this.activeMemberships.delete(key);
+      const removed = this.toRemovedMembership({
+        scope: membership.scope,
+        organizationId: membership.organizationId,
+        teamId: membership.teamId,
+        userId: membership.userId,
+        email: membership.email,
+        target: membership.target,
+      });
+      this.removedMemberships.set(removed.id, removed);
+      return removed;
+    }
+    return null;
+  }
+
   private cascadeRemovedOrganizationTarget(input: {
     readonly organizationId: string;
     readonly target: string;
diff --git a/services/auth-broker/tests/org-team-membership.test.ts b/services/auth-broker/tests/org-team-membership.test.ts
index b6977e6ce..c6e8013d4 100644
--- a/services/auth-broker/tests/org-team-membership.test.ts
+++ b/services/auth-broker/tests/org-team-membership.test.ts
@@ -249,6 +249,98 @@ describe("org and team membership broker routes", () => {
     expect(listMembersResponse.status).toBe(404);
   });
 
+  test("active org members can administer teams without direct team membership", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const ownerApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "cli",
+          org: "hack",
+          name: "CLI",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "user-456",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "user-789",
+        }),
+      })
+    );
+
+    const orgAdminApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(
+        createSession({
+          userId: "user-456",
+          email: "org-admin@example.com",
+        })
+      ),
+      orgTeamsStore: store,
+    });
+
+    const listTeamsResponse = await orgAdminApp.handle(
+      new Request("http://localhost/v1/auth/teams?org=hack")
+    );
+    expect(listTeamsResponse.status).toBe(200);
+    const listedTeams = (await listTeamsResponse.json()) as {
+      readonly teams?: ReadonlyArray<{ readonly slug?: string }>;
+    };
+    expect(listedTeams.teams?.map((team) => team.slug)).toEqual(["cli"]);
+
+    const addTeamMemberResponse = await orgAdminApp.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "user-789",
+        }),
+      })
+    );
+    expect(addTeamMemberResponse.status).toBe(200);
+    const addedMembership = (await addTeamMemberResponse.json()) as {
+      readonly membership?: {
+        readonly scope?: string;
+        readonly state?: string;
+      };
+    };
+    expect(addedMembership.membership?.scope).toBe("team");
+    expect(addedMembership.membership?.state).toBe("active");
+  });
+
   test("team membership changes require an active parent org membership", async () => {
     const store = new InMemoryOrgTeamsStore();
     const ownerApp = createAuthBrokerApp({

From 8f39413b9c5c5a223c0739d8cf5bda12cf92cc1b Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:52:00 +0000
Subject: [PATCH 084/134] fix: clarify env trust model boundaries

---
 docs/env.md                       |  12 +-
 src/commands/env.ts               |  13 +-
 src/lib/hack-env.ts               |  21 ++-
 tests/env-backend-command.test.ts | 280 +++++++++++++++++++++---------
 4 files changed, 233 insertions(+), 93 deletions(-)

diff --git a/docs/env.md b/docs/env.md
index 02905d506..1b9b7acaa 100644
--- a/docs/env.md
+++ b/docs/env.md
@@ -7,8 +7,8 @@ hack supports a project-scoped env contract (shareable, no values) plus safe sec
 Hack currently has three env layers, and they should be understood separately:
 
 - Contract: `.hack/hack.env.json` defines what keys exist and how they should materialize locally.
-- Local values: `.hack/.env` stores local plaintext values for `plain_env`.
-- Local secrets: the configured secret backend stores secret values for keys that should not live in `.hack/.env`.
+- Local values: `.hack/.env` is the usual plaintext file for `plain_env`, and `plain_env` falls back to the current process env when `.hack/.env` does not provide a value.
+- Local secrets: the configured secret backend stores secret values for keys that should not live in `.hack/.env`. In `cloud` mode today, this is still a local shim over encrypted-file storage, not a remote portable copy.
 
 Current status:
 
@@ -27,7 +27,8 @@ See `docs/plans/2026-03-13-env-portability-and-secret-management-design.md` for
 ## Files and storage
 
 - `.hack/hack.env.json` (committed): declares env vars, required vs optional, per-service scope, and where values should come from.
-- `.hack/.env` (gitignored): stores non-secret values (`source: "plain_env"`).
+- `.hack/.env` (local plaintext file): stores non-secret values (`source: "plain_env"`). Most repos should gitignore it, but Hack does not currently enforce that.
+- `process.env` (ambient fallback): supplies `plain_env` values when `.hack/.env` is missing a key.
 - Configured secret backend (`controlPlane.secrets.backend`): stores secret values for `source: "keychain"` contract vars.
 
 ## Contract format (`.hack/hack.env.json`)
@@ -69,7 +70,7 @@ Fields:
 
 - `hack env list [--json] [--show-secrets]`
   - shows contract + resolution state
-  - includes a storage summary for the committed contract, local `.hack/.env`, configured secret backend, and current portable-state status
+  - includes a storage summary for the committed contract, local `.hack/.env`, ambient `process.env` fallback, configured secret backend mode, and current portable-state status
   - exits `1` if required vars are missing
 - `hack env set KEY=VALUE`
   - writes to `.hack/.env`
@@ -134,7 +135,8 @@ When you run `hack up`, `hack restart`, or `hack run`, hack:
 Security posture:
 
 - Secret values are never written into `.hack/` YAML files.
-- Plain env values live in `.hack/.env` (expected to be gitignored in most repos).
+- Plain env values typically live in `.hack/.env`, but Hack can also read them from the current process env for `plain_env` keys.
+- `.hack/.env` should be gitignored by the repo, but Hack does not currently enforce that invariant during `hack init`.
 
 ## Remote node secret behavior
 
diff --git a/src/commands/env.ts b/src/commands/env.ts
index 5d031d3c9..3d4d2eee8 100644
--- a/src/commands/env.ts
+++ b/src/commands/env.ts
@@ -273,11 +273,15 @@ const handleEnvList: CommandHandlerFor<typeof listSpec> = async ({
       ],
       [
         "local_plaintext",
-        `${resolved.storage.localPlaintext.path} (${resolved.storage.localPlaintext.exists ? "present" : "missing"} local plaintext for plain_env)`,
+        `${resolved.storage.localPlaintext.path} (${resolved.storage.localPlaintext.exists ? "present" : "missing"} plaintext file for plain_env, gitignore not enforced)`,
+      ],
+      [
+        "local_fallback",
+        `${resolved.storage.localPlaintext.fallback.source} (used when .env does not provide a plain_env value)`,
       ],
       [
         "local_secrets",
-        `${formatSecretStoreDescriptor({ descriptor: resolved.storage.localSecrets })} (local secret backend)`,
+        `${formatSecretStoreDescriptor({ descriptor: resolved.storage.localSecrets })} (${resolved.storage.localSecrets.mode === "shim" ? "local secret backend shim" : "local secret backend"})`,
       ],
       [
         "portable_state",
@@ -330,6 +334,11 @@ function serializeEnvStorageForJson(input: {
       path: input.storage.localPlaintext.path,
       exists: input.storage.localPlaintext.exists,
       trust_model: input.storage.localPlaintext.trustModel,
+      fallback: {
+        enabled: input.storage.localPlaintext.fallback.enabled,
+        source: input.storage.localPlaintext.fallback.source,
+        trust_model: input.storage.localPlaintext.fallback.trustModel,
+      },
     },
     local_secrets: {
       backend: input.storage.localSecrets.backend,
diff --git a/src/lib/hack-env.ts b/src/lib/hack-env.ts
index c157b12c0..7306f6133 100644
--- a/src/lib/hack-env.ts
+++ b/src/lib/hack-env.ts
@@ -71,10 +71,15 @@ export type HackEnvStorageSummary = {
   readonly localPlaintext: {
     readonly path: string;
     readonly exists: boolean;
-    readonly trustModel: "gitignored_plaintext";
+    readonly trustModel: "unenforced_plaintext_file";
+    readonly fallback: {
+      readonly enabled: true;
+      readonly source: "process_env";
+      readonly trustModel: "ambient_process_env";
+    };
   };
   readonly localSecrets: SecretStoreDescriptor & {
-    readonly trustModel: "local_secret_backend";
+    readonly trustModel: "local_secret_backend" | "local_secret_backend_shim";
   };
   readonly portableState: HackEnvPortableStateSummary;
 };
@@ -208,11 +213,19 @@ export async function resolveHackEnv(opts: {
       localPlaintext: {
         path: envPath,
         exists: envExists,
-        trustModel: "gitignored_plaintext",
+        trustModel: "unenforced_plaintext_file",
+        fallback: {
+          enabled: true,
+          source: "process_env",
+          trustModel: "ambient_process_env",
+        },
       },
       localSecrets: {
         ...secretStore.descriptor,
-        trustModel: "local_secret_backend",
+        trustModel:
+          secretStore.descriptor.mode === "shim"
+            ? "local_secret_backend_shim"
+            : "local_secret_backend",
       },
       portableState: {
         status: "not_configured",
diff --git a/tests/env-backend-command.test.ts b/tests/env-backend-command.test.ts
index 3753e6400..f76644393 100644
--- a/tests/env-backend-command.test.ts
+++ b/tests/env-backend-command.test.ts
@@ -40,95 +40,107 @@ afterEach(async () => {
   }
 });
 
-test("env backend status defaults to keychain", async () => {
-  const result = await runHack({
-    args: ["env", "backend", "status", "--json"],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-    },
-  });
-  expect(result.exitCode).toBe(0);
-  const json = JSON.parse(result.stdout) as {
-    readonly backend: string;
-    readonly encrypted_file: { readonly path: string };
-  };
-  expect(json.backend).toBe("keychain");
-  expect(json.encrypted_file.path).toBe("~/.hack/secrets.enc.json");
-});
-
-test("env backend use encrypted_file persists selection", async () => {
-  const result = await runHack({
-    args: [
-      "env",
-      "backend",
-      "use",
-      "encrypted_file",
-      "--store-path",
-      "/tmp/custom-secrets.enc.json",
-      "--json",
-    ],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
-    },
-  });
-  expect(result.exitCode).toBe(0);
-  const json = JSON.parse(result.stdout) as {
-    readonly backend: string;
-    readonly encrypted_file: { readonly path: string };
-  };
-  expect(json.backend).toBe("encrypted_file");
-  expect(json.encrypted_file.path).toBe("/tmp/custom-secrets.enc.json");
+test(
+  "env backend status defaults to keychain",
+  { timeout: 10_000 },
+  async () => {
+    const result = await runHack({
+      args: ["env", "backend", "status", "--json"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+      },
+    });
+    expect(result.exitCode).toBe(0);
+    const json = JSON.parse(result.stdout) as {
+      readonly backend: string;
+      readonly encrypted_file: { readonly path: string };
+    };
+    expect(json.backend).toBe("keychain");
+    expect(json.encrypted_file.path).toBe("~/.hack/secrets.enc.json");
+  }
+);
 
-  const configText = await readFile(tempGlobalConfigPath!, "utf8");
-  expect(configText).toContain('"backend": "encrypted_file"');
-  expect(configText).toContain('"/tmp/custom-secrets.enc.json"');
-});
+test(
+  "env backend use encrypted_file persists selection",
+  { timeout: 10_000 },
+  async () => {
+    const result = await runHack({
+      args: [
+        "env",
+        "backend",
+        "use",
+        "encrypted_file",
+        "--store-path",
+        "/tmp/custom-secrets.enc.json",
+        "--json",
+      ],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+      },
+    });
+    expect(result.exitCode).toBe(0);
+    const json = JSON.parse(result.stdout) as {
+      readonly backend: string;
+      readonly encrypted_file: { readonly path: string };
+    };
+    expect(json.backend).toBe("encrypted_file");
+    expect(json.encrypted_file.path).toBe("/tmp/custom-secrets.enc.json");
 
-test("env backend use encrypted_file can provision a stable key file", async () => {
-  if (!(tempDir && tempGlobalConfigPath)) {
-    throw new Error("Missing temp global config state");
+    const configText = await readFile(tempGlobalConfigPath!, "utf8");
+    expect(configText).toContain('"backend": "encrypted_file"');
+    expect(configText).toContain('"/tmp/custom-secrets.enc.json"');
   }
+);
 
-  const keyPath = resolve(tempDir, "secrets-file.key");
-  const result = await runHack({
-    args: [
-      "env",
-      "backend",
-      "use",
-      "encrypted_file",
-      "--store-path",
-      "/tmp/custom-secrets.enc.json",
-      "--key-path",
-      keyPath,
-      "--provision-key",
-      "--json",
-    ],
-    env: {
-      ...process.env,
-      HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath,
-    },
-  });
-  expect(result.exitCode).toBe(0);
+test(
+  "env backend use encrypted_file can provision a stable key file",
+  { timeout: 10_000 },
+  async () => {
+    if (!(tempDir && tempGlobalConfigPath)) {
+      throw new Error("Missing temp global config state");
+    }
+
+    const keyPath = resolve(tempDir, "secrets-file.key");
+    const result = await runHack({
+      args: [
+        "env",
+        "backend",
+        "use",
+        "encrypted_file",
+        "--store-path",
+        "/tmp/custom-secrets.enc.json",
+        "--key-path",
+        keyPath,
+        "--provision-key",
+        "--json",
+      ],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath,
+      },
+    });
+    expect(result.exitCode).toBe(0);
 
-  const json = JSON.parse(result.stdout) as {
-    readonly backend: string;
-    readonly encrypted_file: {
-      readonly path: string;
-      readonly keyPath?: string;
+    const json = JSON.parse(result.stdout) as {
+      readonly backend: string;
+      readonly encrypted_file: {
+        readonly path: string;
+        readonly keyPath?: string;
+      };
     };
-  };
-  expect(json.backend).toBe("encrypted_file");
-  expect(json.encrypted_file.keyPath).toBe(keyPath);
+    expect(json.backend).toBe("encrypted_file");
+    expect(json.encrypted_file.keyPath).toBe(keyPath);
 
-  const keyText = await readFile(keyPath, "utf8");
-  expect(keyText.trim().length).toBeGreaterThan(10);
+    const keyText = await readFile(keyPath, "utf8");
+    expect(keyText.trim().length).toBeGreaterThan(10);
 
-  const configText = await readFile(tempGlobalConfigPath, "utf8");
-  expect(configText).toContain('"keyPath"');
-  expect(configText).toContain(keyPath);
-});
+    const configText = await readFile(tempGlobalConfigPath, "utf8");
+    expect(configText).toContain('"keyPath"');
+    expect(configText).toContain(keyPath);
+  }
+);
 
 test(
   "env backend use cloud requires provider and stores cloud settings",
@@ -352,6 +364,11 @@ test(
           readonly path: string;
           readonly exists: boolean;
           readonly trust_model: string;
+          readonly fallback?: {
+            readonly enabled: boolean;
+            readonly source: string;
+            readonly trust_model: string;
+          };
         };
         readonly local_secrets?: {
           readonly backend: string;
@@ -376,7 +393,12 @@ test(
     );
     expect(json.storage?.local_plaintext?.exists).toBe(true);
     expect(json.storage?.local_plaintext?.trust_model).toBe(
-      "gitignored_plaintext"
+      "unenforced_plaintext_file"
+    );
+    expect(json.storage?.local_plaintext?.fallback?.enabled).toBe(true);
+    expect(json.storage?.local_plaintext?.fallback?.source).toBe("process_env");
+    expect(json.storage?.local_plaintext?.fallback?.trust_model).toBe(
+      "ambient_process_env"
     );
     expect(json.storage?.local_secrets?.backend).toBe("encrypted_file");
     expect(json.storage?.local_secrets?.location).toBe(encryptedStorePath);
@@ -390,6 +412,100 @@ test(
   }
 );
 
+test(
+  "env list --json marks cloud backend as a local shim",
+  { timeout: 20_000 },
+  async () => {
+    if (!tempDir) {
+      throw new Error("Missing temp dir");
+    }
+    process.env.HACK_SECRETS_FILE_KEY = "env-storage-cloud-shim-key";
+    const projectRoot = resolve(tempDir, "cloud-storage-repo");
+    const projectDir = resolve(projectRoot, ".hack");
+    const encryptedStorePath = resolve(
+      tempDir,
+      "cloud-storage-secrets.enc.json"
+    );
+    await mkdir(projectDir, { recursive: true });
+    await writeFile(
+      resolve(projectDir, "docker-compose.yml"),
+      "services: {}\n"
+    );
+    await writeFile(
+      resolve(projectDir, "hack.config.json"),
+      `${JSON.stringify(
+        {
+          name: "cloud-storage-project",
+          controlPlane: {
+            secrets: {
+              backend: "cloud",
+              encryptedFile: {
+                path: encryptedStorePath,
+              },
+              cloud: {
+                provider: "aws",
+                project: "dev-account",
+                secretPrefix: "hack-cli",
+              },
+            },
+          },
+        },
+        null,
+        2
+      )}\n`
+    );
+    await writeFile(
+      resolve(projectDir, "hack.env.json"),
+      `${JSON.stringify(
+        {
+          version: 1,
+          vars: [
+            {
+              key: "DATABASE_URL",
+              required: false,
+              source: "keychain",
+            },
+          ],
+        },
+        null,
+        2
+      )}\n`
+    );
+
+    const result = await runHack({
+      args: ["env", "list", "--json"],
+      env: {
+        ...process.env,
+        HACK_GLOBAL_CONFIG_PATH: tempGlobalConfigPath ?? "",
+        HACK_SECRETS_FILE_KEY: "env-storage-cloud-shim-key",
+      },
+      cwd: projectRoot,
+    });
+
+    expect(result.exitCode).toBe(0);
+
+    const json = JSON.parse(result.stdout) as {
+      readonly storage?: {
+        readonly local_secrets?: {
+          readonly backend: string;
+          readonly location: string;
+          readonly mode: string;
+          readonly provider: string | null;
+          readonly trust_model: string;
+        };
+      };
+    };
+
+    expect(json.storage?.local_secrets?.backend).toBe("cloud");
+    expect(json.storage?.local_secrets?.mode).toBe("shim");
+    expect(json.storage?.local_secrets?.provider).toBe("aws");
+    expect(json.storage?.local_secrets?.location).toContain(encryptedStorePath);
+    expect(json.storage?.local_secrets?.trust_model).toBe(
+      "local_secret_backend_shim"
+    );
+  }
+);
+
 test(
   "env list shows storage summary even when no contract exists",
   { timeout: 60_000 },

From 4c7f463d4ba6d27a55c8eb52d67af0668644cf16 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:07:52 +0000
Subject: [PATCH 085/134] docs: clarify core offer and docs ia

---
 README.md                             | 960 +++-----------------------
 apps/macos/README.md                  |   4 +-
 docs/README.md                        |  75 +-
 docs/cli.md                           | 125 +++-
 docs/extensions.md                    |   8 +-
 docs/gateway-api.md                   |   3 +-
 docs/gateway.md                       |   3 +-
 docs/guides/remote-cloudflare.md      |   3 +-
 docs/guides/remote-node-container.md  |   4 +-
 docs/guides/remote-node-laptop-e2e.md |   4 +-
 docs/guides/remote-node-quickstart.md |   4 +-
 docs/guides/remote-node-railway.md    |   4 +-
 docs/guides/remote-ssh.md             |   3 +-
 docs/guides/remote-supervisor.md      |   4 +-
 docs/guides/remote-tailscale.md       |   4 +-
 docs/integrations.md                  | 126 ++++
 docs/supervisor.md                    |   4 +-
 src/cli/command.ts                    |   3 +
 src/cli/help.ts                       |  25 +-
 src/cli/spec.ts                       |   8 +-
 src/commands/auth.ts                  |  14 +-
 src/commands/dispatch.ts              |  10 +-
 src/commands/env.ts                   |   4 +-
 src/commands/gateway.ts               |  10 +-
 src/commands/linear.ts                |   4 +-
 src/commands/node.ts                  |   4 +-
 src/commands/remote.ts                |  12 +-
 src/commands/session.ts               |   4 +-
 src/commands/ssh.ts                   |   4 +-
 src/commands/tickets.ts               |   4 +-
 tests/cli-help.test.ts                |  52 ++
 31 files changed, 532 insertions(+), 964 deletions(-)
 create mode 100644 docs/integrations.md
 create mode 100644 tests/cli-help.test.ts

diff --git a/README.md b/README.md
index 31d64cc93..3c134f4f4 100644
--- a/README.md
+++ b/README.md
@@ -1,942 +1,204 @@
-<a id="readme-top"></a>
+# Hack
 
-<!-- PROJECT LOGO -->
-<br />
-<div align="center">
-<pre style="font-family:monospace;padding:0;margin:0;white-space:pre;font-size:12px;background:none!important;">
- █████   █████   █████████     █████████  █████   ████
-░░███   ░░███   ███░░░░░███   ███░░░░░███░░███   ███░ 
- ░███    ░███  ░███    ░███  ███     ░░░  ░███  ███   
- ░███████████  ░███████████ ░███          ░███████    
- ░███░░░░░███  ░███░░░░░███ ░███          ░███░░███   
- ░███    ░███  ░███    ░███ ░░███     ███ ░███ ░░███  
- █████   █████ █████   █████ ░░█████████  █████ ░░████
-░░░░░   ░░░░░ ░░░░░   ░░░░░   ░░░░░░░░░  ░░░░░   ░░░░ 
-</p>
-<br/>
-</div>
-  <p align="center">
-    Opinionated local-dev orchestration for running <b>multiple projects</b> at the same time without port conflicts.
-    <br />
-  </p>
+Hack is local development without the port-collision tax.
 
----
-**Network isolation per repo / branch**: every instance runs on its own Docker network (so Postgres/Redis/etc can stay on default ports *inside* the project).
+It gives each repo or branch its own network, a stable HTTPS URL, and a single place to manage
+the workflows that usually end up scattered across shell scripts, terminal tabs, and sidecar tools.
 
-**Stable HTTPS hostnames**: `https://<project>.hack` (and subdomains like `https://api.<project>.hack`) routed by a global Caddy proxy.
+## Three core promises
 
-**Good logs UX**: instant `docker compose logs` tailing, plus Loki/Grafana for querying + history.
+1. Run multiple repos or branches at the same time without port conflicts.
+2. Open every project on a stable HTTPS URL like `https://myapp.hack`.
+3. Keep project workflows such as env, sessions, tickets, and integrations close to the repo.
 
-**Opt-in per repo**: no invasive changes to your codebase; config lives in `.hack/`.
-
----
-
-### Why this exists
-
-Most of my projects run the same stack. That’s fine until you want to:
-
-- run two projects at the same time
-- run two branches of the same repo
-- run multiple worktrees in parallel
-
-At that point everything fights over `localhost` and default ports.
-
-The daily choice:
-
-- **Option A:** stop A → start B → ship fix → stop B → restart A  
-  you just spent 5–10 minutes paying the orchestration tax and nuking your focus.
-- **Option B:** don’t run it. code blind. push. let CI tell you what you broke.
-
-Neither scales. Both slow you down in dumb, repeatable ways.
-
-
-## Installation
+## Five-minute start
 
 ### Prerequisites
-- **macOS**: supported.
-- **Docker + Compose**: [Orbstack](https://docs.orbstack.dev/quick-start) | [Docker Desktop](https://www.docker.com/get-started/) 
+
+- macOS
+- Docker + Compose via [OrbStack](https://docs.orbstack.dev/quick-start) or
+  [Docker Desktop](https://www.docker.com/get-started/)
 
 ### Install
 
-**Option A: Shell script (CLI only)**
+CLI:
 
 ```bash
 curl -fsSL https://github.com/hack-dance/hack/releases/latest/download/hack-install.sh | bash
 ```
 
-**Option B: macOS DMG (CLI + Desktop App)**
+macOS app:
 
-Download the latest DMG from [GitHub Releases](https://github.com/hack-dance/hack/releases/latest).
+- Download the latest DMG from
+  [GitHub Releases](https://github.com/hack-dance/hack/releases/latest)
+- `Hack Desktop for macOS` is currently **Beta**
 
-The DMG includes:
-- **Hack Desktop** - macOS menu bar app for managing projects
-- **Install Hack CLI** - double-click to install the CLI to `~/.hack/bin`
+### Start a project
 
-### Setup
 ```bash
 hack global install
-```
-
-### Quick start 
-Manual (CLI):
 
-```bash
 cd /path/to/your-repo
 hack init
 hack up --detach
 hack open
 ```
 
-Agent-assisted (Cursor/Claude/Codex with shell access):
-
-```bash
-hack setup cursor   # or hack setup claude / hack setup codex
-hack setup agents   # optional: adds AGENTS.md + CLAUDE.md snippets
-hack setup sync --all-scopes   # optional: refresh project + user integrations
-hack agent init --client cursor   # or --client claude / --client codex
-hack agent patterns              # optional: dependency/ops checklist
-```
-
-If you omit `--client`, `hack agent init` will prompt you to choose (TTY only).
-If your agent does not auto-open, paste the output into the chat. Example:
-
-```
-I ran `hack agent init` and pasted the output below. Please follow it to set up hack for this repo,
-then run:
-- `hack init` (use --auto if dev scripts are detected)
-- `hack up --detach`
-- `hack open --json`
-If anything fails, use `hack logs --pretty` and summarize next steps.
-
-<PASTE HACK AGENT INIT OUTPUT HERE>
-```
-
-If the agent cannot run shell commands, use MCP instead: `hack setup mcp` and `hack mcp serve`.
-
-### Remote node runtime image (multi-node)
-
-Use the prebuilt node-runtime container to bootstrap remote nodes quickly (Linux/macOS hosts with Docker):
-
-```bash
-bun run build:node-runtime-image --tag hack-node-runtime:dev
-```
-
-Full operator guide: [`docs/guides/remote-node-container.md`](docs/guides/remote-node-container.md)
-
-### Tickets (optional, git-backed issue tracking)
+What those commands do:
 
-`hack` includes a lightweight, git-backed ticket system for tracking work without leaving your repo. Tickets are stored in a hidden git ref (`refs/hack/tickets`) so they sync with your code but don't clutter your branch list.
+- `hack global install` boots the machine-level DNS, TLS, and logging services
+- `hack init` creates the `.hack/` project config
+- `hack up --detach` starts your stack on an isolated network
+- `hack open` opens the project URL in your browser
 
-**Quick setup:**
+Useful next commands:
 
 ```bash
-# Enable tickets for this repo
-hack x tickets setup
-
-# Create a ticket
-hack x tickets create --title "Add dark mode support"
-
-# List tickets
-hack x tickets list
-
-# Interactive TUI for managing tickets
-hack x tickets tui
-
-# Update status
-hack x tickets status T-00001 in_progress
-
-# Sync to remote
-hack x tickets sync
-```
-
-**Why use it:**
-- No external service required - tickets live in git
-- Agent-friendly - Claude/Cursor/Codex can create and manage tickets
-- Syncs with `git push/pull` via hidden refs
-- Works offline
-
-Tickets are ideal for solo devs, small teams, or agent-driven workflows where you want lightweight task tracking without context-switching to Jira/Linear/GitHub Issues.
-
-Full docs: [`docs/guides/tickets.md`](docs/guides/tickets.md)
-
-### macOS app (experimental)
-Source lives in `apps/macos`. See `apps/macos/README.md` for XcodeGen and build/run steps.
-Quick commands (repo root):
-
-```bash
-bun run macos:project-gen
-bun run macos:open
-bun run macos:dev
-bun run macos:build
-bun run macos:test
-```
-
-### Configuration (.hack/hack.config.json)
-- `name`: project slug (also used for Docker Compose project name)
-- `dev_host`: base hostname (`<dev_host>.hack`)
-
-*Optional `[logs]` settings*
-- `follow_backend`: `compose|loki` (default: `compose`)
-- `snapshot_backend`: `compose|loki` (default: `loki`)
-- `clear_on_down`: when running `hack down`, request Loki delete for this project (best-effort)
-- `retention_period`: e.g. `"24h"`; on `hack down`, prune older logs (best-effort)
-
-*Optional `[internal]` settings (container DNS/TLS)*
-- `dns`: use CoreDNS to resolve `*.hack` inside containers (default: `true`)
-- `tls`: mount Caddy Local CA + set common SSL env vars (default: `true`)
-- `extra_hosts`: static Compose `extra_hosts` entries (hostname → IP/target), merged into the internal override
-
-If you need **dynamic** `extra_hosts` (e.g. Pulumi outputs / local tunnels that change), use:
-
-```bash
-hack internal extra-hosts set <hostname> <target>
-hack internal extra-hosts unset <hostname>
-hack internal extra-hosts list
-```
-
-This writes `.hack/.internal/extra-hosts.json` and is merged into `extra_hosts` when you run `hack up` / `hack restart`.
-
-*Optional `[oauth]` settings (OAuth-safe alias host)*
-- `enabled`: when true, `hack init` generates Caddy labels so routed services answer on both:
-- primary: `https://<dev_host>`
-- OAuth alias: `https://<dev_host>.<tld>` (e.g. `https://sickemail.hack.gy`)
-- `tld`: optional (default: `"gy"`). Only `*.hack.gy` is bootstrapped automatically by `hack global install`; other TLDs require manual DNS setup.
-
-The file includes a JSON Schema reference for editor validation:
-
-```json
-{
-  "$schema": "https://schemas.hack/hack.config.schema.json"
-}
-```
-
-Schemas are served locally by the global Caddy proxy at `https://schemas.hack`.
-
-Quick edits:
-
-```bash
-hack config get dev_host
-hack config set dev_host "myapp.hack"
-hack config set logs.snapshot_backend "compose"
-```
-
-## Commands (high level)
-
-Run `hack help` (or `hack help <command>`) for full usage.
-
-Common:
-- `hack global install|up|down`
-- `hack init|up|down|logs|open|tui`
-- `hack status`
-- `hack remote setup`
-- `hack gateway enable`
-
-Full command table + flags: `docs/cli.md`.
-
-Run `hack help <command>` for detailed help.
-
-Project commands that call Docker Compose accept `--profile` (up/down/restart/ps/logs/run).
-
-## JSON output
-
-Use `--json` for machine-readable output:
-
-- `hack projects --json`
-- `hack ps --json`
-- `hack logs --json` (NDJSON stream; use `--no-follow` for snapshots)
-- `hack open --json` (returns `{ "url": "..." }`)
-
-When the daemon is running, `hack projects --json` and `hack ps --json` use it for faster results.
-
-`hack logs --json` emits event envelopes (`start`, `log`, `end`) so MCP/TUI consumers can stream safely.
-
-## Daemon (optional)
-
-`hackd` is a local daemon that caches Docker state for fast status/ps queries.
-
-```bash
-hack daemon start
-hack daemon status
-hack daemon metrics
-hack daemon stop
-hack daemon logs
+hack logs --pretty
+hack run <service> <command...>
+hack status
+hack down
 ```
 
-### launchd integration (macOS)
+## What is core today
 
-On macOS, you can install `hackd` as a launchd service for automatic management:
+These workflows are the main product:
 
-```bash
-# Install (auto-start on login by default)
-hack daemon install
+- Project setup and runtime: `hack init`, `hack up`, `hack down`, `hack restart`, `hack ps`
+- Stable local access: `hack open`, `hack logs`, `hack run`, `hack status`
+- Parallel project work: branch instances, isolated networks, and per-project hostnames
+- Repo-local workflow support: `hack env`, `hack session`, `hack tickets`
 
-# Install without auto-start (manual start/stop via launchd)
-hack daemon install --no-run-at-load
+Supporting capabilities:
 
-# Uninstall the launchd service
-hack daemon uninstall
-```
+- GitHub and Linear integrations
+- Agent setup for Cursor, Claude Code, and Codex
+- CLI and SDK reference surfaces for extensions and automation
 
-Options:
-- `--run-at-load` / `--no-run-at-load`: Start automatically on login
-- `--gui-only` / `--no-gui-only`: Only run in GUI sessions (default: GUI only)
+Beta surfaces:
 
-The service uses label `dance.hack.hackd` and writes to `~/Library/LaunchAgents/`.
+- Remote control plane and gateway flows
+- Multi-node execution and dispatch
+- Hack Desktop for macOS
 
-Use it when:
-- You run `hack projects --json` / `hack ps --json` frequently (scripts, agent workflows, TUI).
-- You want faster status snapshots without shelling out to Docker each time.
+## Integrations overview
 
-Skip it when:
-- You prefer zero background processes.
-- You rarely use JSON status/ps outputs.
+Hack has a few supporting surfaces that matter after your project is already running.
 
-If it is not running (or version-mismatched), the CLI falls back to direct Docker calls.
+### GitHub
 
-## Control plane + extensions (optional)
+Use GitHub integration when you want Hack to authenticate repo workflows or create and update pull
+requests for you.
 
-`hack` includes a small control-plane kernel so features like jobs, tickets, and remote access can
-ship as extensions without bloating the core CLI.
+- Main surface: `hack x github ...`
+- Common use: connect a profile, then use PR or repo automation from Hack workflows
+- Reference: [docs/extensions.md](docs/extensions.md)
 
-- Extension commands run via `hack x <namespace> <command>`.
-- Global control-plane config lives at `~/.hack/hack.config.json` (`hack config set --global ...`).
-- Per-project overrides live in `.hack/hack.config.json` and win over global values.
-- `controlPlane.gateway.enabled` is project-scoped and implicitly enables the gateway extension.
+### Linear
 
-See `SPECS/control-plane/consolidated.md` and `docs/extensions.md` for the extension SDK surface.
+Use Linear when you want selected Linear issues or projects to sync into your repo-local workflow
+instead of treating Linear as a separate universe.
 
-### Gateway (remote access)
+- Main surface: `hack linear ...`
+- Common use: connect a profile, bind a project, sync issues or project state
+- Reference: [docs/integrations.md](docs/integrations.md)
 
-The gateway exposes `hackd` over HTTP/WS with token auth. It binds to `127.0.0.1` by default and
-should be exposed via a Zero Trust/VPN or SSH tunnel when needed. `hack remote setup` is the
-one-command flow that enables the gateway, creates a token, and can configure + start exposure
-(Cloudflare/Tailscale/SSH) via prompts. It prints a QR by default (use `--no-qr` to skip).
+### Tickets
 
-```bash
-hack remote setup
-# or:
-hack gateway setup
-# or manually:
-hack gateway enable
-hack daemon stop && hack daemon start
-hack x gateway token-create
-```
+Use tickets when you want lightweight work tracking in git without leaving the repo.
 
-Gateway tokens default to read-only. For non-GET requests, set
-`controlPlane.gateway.allowWrites = true` globally and create a write-scoped token:
+- Main surface: `hack tickets ...`
+- Common use: create follow-up work, track status, sync hidden ticket refs
+- Reference: [docs/guides/tickets.md](docs/guides/tickets.md)
 
-```bash
-hack config set --global 'controlPlane.gateway.allowWrites' true
-```
+### Sessions
 
-```bash
-hack x gateway token-create --scope write
-```
+Use sessions when you want a durable terminal workspace for yourself or an agent.
 
-Current gateway API (HTTP/WS):
-- status/metrics/projects/ps (`/v1/*`)
-- supervisor jobs: list/create/show/cancel + log/event stream (`/control-plane/*`)
-- supervisor shells: create/show + PTY stream (write token + allowWrites)
-- CLI shell client: `hack x supervisor shell` (gateway + write token required)
+- Main surface: `hack session ...`
+- Common use: keep a project shell alive, reattach later, or run long-lived agent work
+- Reference: [docs/sessions.md](docs/sessions.md)
 
-Interactive shells are available over the gateway WebSocket; the CLI can attach with
-`hack x supervisor shell` (write token + allowWrites required). Use SSH/Zero Trust for a full
-terminal UI, or run commands via supervisor jobs.
+### Env
 
-See `docs/gateway-api.md` for full API usage, structured workflow patterns, and a runnable demo.
+Use env management when you want the repo to declare what configuration it needs without committing
+the secret values themselves.
 
-Remote access options (recommended order):
-1) SSH tunnel to the gateway port for quick, ad-hoc access.
-2) Zero Trust/VPN (Tailscale, Cloudflare, etc.) for persistent access.
-3) Optional Caddy route (`https://gateway.hack`) for local convenience.
+- Main surface: `hack env ...`
+- Common use: define required vars in `.hack/hack.env.json`, keep values in `.hack/.env` or a
+  secret backend
+- Reference: [docs/env.md](docs/env.md)
 
-Note: Cloudflare Tunnel is ideal for the gateway HTTP/WS surface. It is not a direct SSH
-replacement on iOS; use Tailscale/VPN for SSH access from mobile clients.
-If you already use Cloudflare WARP, configure a private network route to your laptop and
-use that IP/hostname for SSH in your mobile client.
+## Docs map
 
-Remote helper:
-- `hack remote` shows status and offers to run setup when needed.
-- `hack remote status` prints gateway + exposure status.
-- `hack remote qr` prints a QR payload for SSH or gateway usage (confirm before sharing).
-- `hack remote monitor` opens a mini TUI (status + gateway audit log tail).
+Start here when you want the product story before the low-level reference:
 
-Cloudflare tunnel helper:
+- Core workflows: [docs/README.md](docs/README.md)
+- CLI quick map and full reference: [docs/cli.md](docs/cli.md)
+- Integrations overview: [docs/integrations.md](docs/integrations.md)
 
-```bash
-hack x cloudflare tunnel-setup --hostname gateway.example.com
-hack x cloudflare tunnel-start
-```
+Beta surfaces are intentionally separate:
 
-Tailscale helper:
+- Remote control plane and gateway: [docs/gateway.md](docs/gateway.md)
+- Multi-node quickstart: [docs/guides/remote-node-quickstart.md](docs/guides/remote-node-quickstart.md)
+- Hack Desktop for macOS: [apps/macos/README.md](apps/macos/README.md)
 
-```bash
-hack x tailscale setup
-hack x tailscale status
-```
-
-DNS note: `cloudflared tunnel route dns <tunnel> <hostname>` creates the required CNAME to
-`<tunnel-id>.cfargotunnel.com` in your Cloudflare zone (proxied).
+Reference surfaces:
 
-### Supervisor (jobs + shells)
+- Extensions and SDK: [docs/extensions.md](docs/extensions.md)
+- Gateway API: [docs/gateway-api.md](docs/gateway-api.md)
+- Architecture: [docs/architecture.md](docs/architecture.md)
 
-The supervisor is the job/shell runner that powers agent workflows and remote execution. It can run
-commands, stream logs, and host PTY-backed shells. Use it locally with `hack x supervisor` or
-remotely over the gateway.
+## `hack help` guide
 
-Docs: `docs/supervisor.md`.
+Root help is organized in the same order as the product:
 
-## Docs
+- `Global commands`: machine setup and shared services
+- `Core workflows`: the day-to-day local-dev path
+- `Collaboration & integrations`: env, sessions, tickets, Linear, and SSH access
+- `Beta workflows`: remote control plane, multi-node, and dispatch
+- `Extension commands`: lower-level extension namespace access
 
-Start here:
-- `docs/README.md` (index)
-- `docs/architecture.md`
-- `docs/gateway.md`
-- `docs/extensions.md`
+Run `hack help` or `hack help <command>` for the CLI version of that map.
 
-## Agent setup (CLI-first)
+## Agent setup
 
-Use `hack setup` to install local integrations. Default is project scope; add `--global` for user scope.
+If you want Hack to teach coding agents how to work in a repo:
 
 ```bash
 hack setup cursor
 hack setup claude
 hack setup codex
-hack setup agents
 hack setup sync --all-scopes
+hack agent init --client codex
 ```
 
-What each setup command does:
-- `hack setup cursor`: installs Cursor rules in `.cursor/rules/hack.mdc`
-- `hack setup claude`: installs Claude Code hooks in `.claude/settings.local.json` (or user scope)
-- `hack setup codex`: installs the Codex skill in `.codex/skills/hack-cli/SKILL.md`
-- `hack setup agents`: adds/updates hack usage snippets in `AGENTS.md` and `CLAUDE.md`
-- `hack setup mcp`: writes MCP configs for no-shell clients
-- `hack setup sync --all-scopes`: refreshes docs, skills, and MCP config at project + user scope
-
-Automatic guardrail:
-- Project-level `hack` commands (interactive sessions) auto-check docs/skills/MCP drift and attempt auto-sync.
-- To warn-only: `HACK_SETUP_SYNC_MODE=warn`
-- To disable: `HACK_SETUP_SYNC_MODE=off`
-
-Primer helpers:
-- `hack agent prime`: short CLI-first primer used by Claude Code hooks
-- `hack agent init`: repo-specific setup prompt agents can follow to scaffold/verify hack config
-- `hack agent init --client cursor|claude|codex`: open the prompt directly in an agent client
-- `hack agent patterns`: dependency/ops checklist for agents
-
-Recommended flow:
-- Use `hack setup cursor|claude|codex` for your agent client
-- Use `hack setup agents` to document hack usage inside the repo
-- Use `hack setup sync --all-scopes` after `hack update` to refresh generated integrations
-- Use `hack setup mcp` only when the agent has no shell access
-
-## MCP (no-shell clients)
-
-Use MCP only when the CLI is not available (e.g. no shell access).
-
-Run the MCP server locally over stdio:
-
-```bash
-hack mcp serve
-```
-
-Most MCP clients spawn this on demand. Running it directly will wait for a client connection.
-
-Install MCP configs (Cursor, Claude CLI, Codex):
+If your agent does not have shell access, use MCP instead:
 
 ```bash
-# Project-scoped (default via setup)
 hack setup mcp
-
-# User-scoped (default; writes to your home config directories)
-hack mcp install --all
-
-# Project-scoped (writes .cursor/.claude/.codex in the repo)
-hack mcp install --all --scope project
-```
-
-Project scope writes `.cursor/mcp.json`, `.claude/settings.json`, and `.codex/config.toml`.
-For `--scope project`, `hack mcp install` also updates `AGENTS.md` and `CLAUDE.md` by default.
-
-Print config snippets without writing:
-
-```bash
-hack mcp print --codex
-```
-
-`hack init` can prompt to install local agent integrations after scaffolding a repo.
-For agent-driven scaffolding without prompts, use `hack init --auto` and run `hack setup` manually.
-
-## Branch builds (worktree-friendly)
-
-Use `--branch <name>` on project commands to run isolated instances with unique hostnames and compose
-project names:
-
-```bash
-hack up --branch feature-x --detach
-hack logs --branch feature-x
-hack open --branch feature-x
-```
-
-Using `--branch` will create/update `.hack/hack.branches.json` with a `last_used_at` timestamp. Branch
-instances show up in `hack projects --details`.
-
-Optional: track branch aliases in `.hack/hack.branches.json` for quick lookup:
-
-```bash
-hack branch add feature-x --note "worktree for PR 123"
-hack branch list
-hack branch open feature-x
-```
-
-
-## Service-to-service connections (HTTP vs DB/Redis)
-
-If your app runs in Docker (the default in `hack`), don’t connect to `127.0.0.1` / `localhost` for Postgres/Redis.
-Inside a container, `localhost` is that container, not the other compose services.
-
-If you previously ran everything on your host and used `localhost:PORT`, update those references when you
-move into containers:
-
-- **HTTP services**: use the same `https://*.hack` hostname you open from the host (whatever you configured in Caddy labels, e.g. `https://api.myapp.hack`).
-- **Non-HTTP services** (DB/Redis/etc.): use the Compose service hostname (e.g. `db`, `redis`).
-
-For HTTP services, use the same `https://*.hack` URLs you use on the host. `hack up` injects internal DNS,
-TLS trust, and `extra_hosts` mappings so `*.hack` resolves reliably inside containers. If you see `ENOTFOUND`
-inside containers, run `hack restart` to refresh the host mappings.
-
-For non-HTTP services, use the Compose service hostname on the default network:
-
-- `Postgres: db:5432`
-- `Redis: redis:6379`
-
-Note: Caddy’s CA is mounted into containers when `internal.tls: true` so HTTPS calls to `*.hack` work for most runtimes.
-If you’re using Java/Kotlin, you’ll need to import the CA into the JVM truststore manually.
-
-Example:
-
-```yaml
-environment:
-  DATABASE_URL: postgres://postgres:postgres@db:5432/mydb
-  REDIS_URL: redis://redis:6379
-```
-
-If you need host access for debugging, prefer `docker compose exec` so you don’t reintroduce port conflicts:
-
-```bash
-docker compose -f .hack/docker-compose.yml exec db psql -U postgres -d mydb
-docker compose -f .hack/docker-compose.yml exec redis redis-cli
-```
-
-## Logs (why both Compose and Loki)
-
-By default, `hack logs` uses `docker compose logs` because it’s the lowest latency tail.
-The daemon does not proxy logs yet; `hack logs` still talks directly to Docker Compose or Loki.
-
-Loki is still valuable for:
-
-- querying across time (history)
-- filtering by labels (project/service/container)
-- Grafana Explore / dashboards
-
-### CLI
-
-```bash
-# Tail (fast)
-hack logs --pretty
-
-# Snapshot
-hack logs --no-follow --pretty
-
-# Snapshot JSON
-hack logs --no-follow --json
-
-# Query/history (force Loki)
-hack logs --loki --pretty
-
-# Range (Loki only)
-hack logs --loki --since 2h --pretty
-hack logs --loki --since 4h --until 1h --pretty
-
-# Filter Loki by service
-hack logs --loki --services api,worker --pretty
-
-# Raw LogQL
-hack logs --loki --query '{project="my-project"} |= "error"' --pretty
-```
-
-### Grafana
-
-- Open: `hack open logs` or visit `https://logs.hack`
-- Explore queries:
-
-```logql
-{project="my-project"}
-{project="my-project", service="api"}
-```
-
-Alloy labels logs with:
-
-- project: `Docker Compose project name`
-- service: `Docker Compose service name`
-- container: `Docker container name`
-
-
-## Projects registry (bird’s-eye view)
-
-`hack` maintains a best-effort registry under `~/.hack/projects.json` so you can target a project from anywhere:
-
-```bash
-hack projects
-hack logs --project my-project --pretty
-hack up --project my-project
-```
-
-## .hack and valid tld requirements
-
-OAuth providers (notably Google) require `localhost` or a host that ends with a real public suffix.
-
-We keep `.hack` as the primary local dev domain, and optionally expose an alias domain for OAuth flows.
-If the OAuth alias is enabled, `hack global install` configures `*.hack.gy` to resolve to the Caddy
-container IP via dnsmasq + the OS resolver (bypasses port forwarding issues with Tailscale/VPNs).
-
-Routing rules:
-
-- `https://*.hack` is the default local-dev hostname space.
-- `https://*.hack.gy` is an OAuth-safe alias host space (public-suffix-style domain).
-- Only services with Caddy labels and attached to `hack-dev` are exposed via these hostnames.
-- These domains are local routes by default; use tunnels/remote ingress separately for internet-reachable webhooks.
-
-If you use Next.js (or another dev server that cares about dev origins), configure its dev allowlist to include the proxy domains.
-Next.js supports `allowedDevOrigins` (wildcards supported) in `next.config.js`:
-
-```js
-module.exports = {
-  allowedDevOrigins: ["*.hack", "*.hack.gy"],
-}
-```
-
-Optionally you can pass in your own custom `dev_host` to the config.
-
-
-## SSL
-
-`hack` uses Caddy’s internal PKI to issue certs for `*.hack` (and any OAuth alias host). This covers
-HTTPS for services routed through Caddy, but it does not create cert/key files for services running
-outside of Caddy.
-
-- macOS: run `hack global trust` to trust the Caddy Local CA in the System keychain.
-- Other OS: run `hack global ca` to export the CA cert path, then add it to your OS/browser trust store.
-- If you need the PEM directly: `hack global ca --print`.
-- If you are running a local service outside of Caddy, use `hack global cert <host...>` (mkcert required) to generate a cert/key under `~/.hack/certs` and wire it into your service. This is only needed for non-Caddy services that still want trusted TLS.
-- macOS: `hack global install` can optionally install mkcert (needed for `hack global cert`).
-
-Install mkcert if you don't already have it (macOS example):
-
-```bash
-brew install mkcert
-mkcert -install
-```
-
-Example (non-Caddy service):
-
-```bash
-hack global cert --install api.myapp.hack
-```
-
-Use `--out <dir>` if you want certs written somewhere else.
-
-## Internal DNS (containers)
-
-`hack global install` runs CoreDNS on the `hack-dev` network. CoreDNS answers `*.hack` and `*.hack.*` with
-Caddy’s current IP so containers can use the same `https://*.hack` URLs as the host.
-
-This is the core isolation model: each repo keeps its own compose network, while routed HTTP services get stable hostnames
-through shared Caddy ingress. That means you can call local services by hostname from host or container without relying on
-host-published `localhost:<port>` patterns.
-
-Some runtimes don’t honor custom DNS for `*.hack` reliably, so `hack up` also injects `extra_hosts` mappings
-to the Caddy IP. If the Caddy IP changes, `hack status`, `hack doctor`, and the TUI show a warning; fix it
-with `hack restart` to refresh the mapping.
-
-If you also need `extra_hosts` for non-`*.hack` hostnames (common when you run host-local tunnels/proxies
-and want containers to reach them by their real domain), use `hack internal extra-hosts set` to write a
-repo-local `.hack/.internal/extra-hosts.json` that gets merged into the generated Compose override.
-
-When `internal.tls` is enabled, `hack up` mounts the Caddy Local CA into each container and sets common
-SSL env vars so HTTPS to `*.hack` is trusted inside containers.
-
-If you update `hack`, rerun `hack global install` once to refresh the CoreDNS config.
-
-
-
-
-## Why not just use X?
-
-### Docker / Compose alone
-
-They run containers. They don’t give you stable hostnames, HTTPS, or a way to run many isolated copies of the same stack without custom glue. 
-
-You can build that layer yourself. I did. That’s this.
-
-### Kubernetes
-
-Kubernetes solves cluster orchestration. This problem is local parallelism.  
-It adds complexity without fixing ports, routing, or developer feedback loops.
-
-### Different ports
-
-This is the default answer and it doesn’t scale.  
-Ports leak into config, break OAuth and cookies, and turn into debt.  
-Hostnames scale. Ports don’t.
-
-There isn’t an off-the-shelf tool that gives you full local network isolation, real HTTPS, and near zero per-repo setup.
-
-If you want that, you have to build it yourself.
-
-
-## How it works
-
-`hack` is a thin layer on top of Docker Compose plus a tiny global proxy.
-
-- each project/branch runs in its own Docker network
-- services use their normal ports inside that network
-- a shared proxy routes `https://*.hack` and handles HTTPS
-- logs are captured centrally
-
-Your code doesn’t change. Your mental overhead does.
-
-### Global (once per machine)
-
-`hack global install` provisions `~/.hack/` and starts:
-
-- **Caddy** (`lucaslorentz/caddy-docker-proxy`) on ports `80/443`
-  - watches Docker labels and auto-routes `https://*.hack`
-- **Logging stack**: Grafana + Loki + Alloy
-  - reachable via `https://logs.hack`
-
-### Per-project (per repo)
-
-`hack init` creates `.hack/` in the repo root:
-
-- `.hack/docker-compose.yml`: your project services
-- `.hack/hack.config.json`: project config (name, dev host, log preferences)
-
-Each project’s compose network stays isolated; only services you want “public” get attached to the shared ingress network so Caddy can reach them.
-
-
-## Common patterns (deps + ops)
-
-Agents: run `hack agent patterns` for a compact checklist based on this section.
-
-### 1) Containerized dependency installs (recommended)
-
-If you run `bun install` on the host and then start Linux containers, you can hit platform
-mismatches (native modules, postinstall scripts, OS-specific binaries). The clean pattern is to
-install dependencies **inside** Docker and share them via a volume.
-
-Add a one-shot deps service and make your app services depend on it:
-
-```yaml
-deps:
-  image: imbios/bun-node:latest
-  working_dir: /app
-  volumes:
-    - ..:/app
-    - node_modules:/app/node_modules
-  command: bun install
-  networks:
-    - default
-
-www:
-  image: imbios/bun-node:latest
-  working_dir: /app/apps/www
-  volumes:
-    - ..:/app
-    - node_modules:/app/node_modules
-  depends_on:
-    deps:
-      condition: service_completed_successfully
-```
-
-This keeps dependency resolution in the same OS as your containers and avoids host/guest drift.
-
-### 2) Networked ops commands (DB schema tooling, migrations)
-
-Because `hack` avoids publishing DB ports to your host, run schema/ops commands inside the
-compose network.
-
-Option A (recommended): add an ops-only service:
-
-```yaml
-db-ops:
-  image: imbios/bun-node:latest
-  working_dir: /app/packages/db # where your db schema + package.json live
-  volumes:
-    - ..:/app
-    - node_modules:/app/node_modules
-  environment:
-    DATABASE_URL: postgres://postgres:postgres@db:5432/mydb
-  depends_on:
-    - db
-    - deps
-  networks:
-    - default
-  profiles: ["ops"]
-  # Examples:
-  # - Prisma:  bunx prisma migrate deploy
-  # - Drizzle: bunx drizzle-kit push
-  command: bun run db:push
-```
-
-Run it on demand:
-
-```bash
-docker compose -f .hack/docker-compose.yml --profile ops run --rm db-ops
-```
-
-Option B: run via `hack run` (thin wrapper over `docker compose run --rm`):
-
-```bash
-hack run --workdir /app/packages/db email-sync -- bunx prisma generate
-hack run --workdir /app/packages/db email-sync -- bunx prisma migrate dev
-hack run --workdir /app/packages/db email-sync -- bunx drizzle-kit push
-hack run --workdir /app bun run turbo db:migrate
-```
-
-If your ops service is behind a compose profile, enable it:
-
-```bash
-hack run --profile ops --workdir /app/packages/db db-ops -- bun run db:push
+hack mcp serve
 ```
 
-See examples:
-- `examples/next-app/README.md`
-
-
-## Troubleshooting
-
-- `*.hack` doesn’t resolve: run `hack doctor`, then `hack global install` (macOS: ensure dnsmasq is running).
-
-- Stale global setup / CoreDNS issues: run `hack doctor --fix` (refreshes network + CoreDNS + CA).
-
-- TLS warnings: run `hack global trust` (macOS).
-
-- Logs missing in Grafana: ensure Alloy is running (`hack global status`) and try `{app="docker"}` in Explore.
-
-- `ENOTFOUND` for `*.hack` inside containers: run `hack restart` to refresh `extra_hosts` mappings (check
-  `hack status` or the TUI for Caddy IP mismatch warnings).
-
-- `EAI_AGAIN` for external domains inside containers (e.g. `api.clerk.com`): CoreDNS isn’t forwarding.
-  Run `hack global install` and restart CoreDNS:
-  `docker compose -f ~/.hack/caddy/docker-compose.yml restart coredns`.
-
-- `hack global up` warns about `hack-dev` network labels or missing subnet: remove the network and reinstall:
-  `docker network rm hack-dev` then `hack global install`.
-
-- OAuth redirect errors: use the OAuth alias host (`*.hack.gy`) or `localhost` (providers may reject non-public suffixes like `.hack`).
-
-
-
 ## Development
 
-### From source
-
-```bash
-bun install
-bun run install:dev
-hack --help
-```
-This installs a small `hack` shim into `~/.hack/bin/hack` that runs your working tree directly (no rebuild needed).
-
-If `hack` isn’t found, add this to your shell config:
-
-```bash
-export PATH="$HOME/.hack/bin:$PATH"
-```
-
-### Compiled binary (release-like)
+If you are working on Hack itself:
 
 ```bash
 bun install
-bun run install:bin
-hack --help
-```
-This builds `dist/hack` via `bun build --compile` and installs it to `~/.hack/bin/hack`.
-
-### Check which install is active
-
-```bash
-bun run install:status
-```
-Reports whether `hack` is a dev shim or a compiled binary (and where it points).
-
-
-### Run in place
-
-```bash
-bun dev --help
-```
-
-### Tests
-
-```bash
-bun run test
-```
-
-Runs workspace tests via Turbo (`@hack/cli`, `@hack/auth-broker`, `@hack/db`).
-
-### Workspace command model
-
-Root commands are orchestration wrappers. For package-local work, run commands directly:
-
-```bash
-bun run --cwd packages/cli build
-bun run --cwd packages/cli macos:ghostty:bundle
-bun run --cwd services/auth-broker test
-bun run --cwd packages/db db:migrate
-```
-
-### Conventional commits
-
-```bash
-bun run commit
-```
-
-Commitlint runs on `git commit` via husky, and semantic-release uses Conventional Commits to
-compute versions.
-
-### Build a standalone binary
-
-```bash
 bun run build
-./dist/hack --help
-```
-
-### Build a release bundle
-
-```bash
-bun run build:release
+bun test
+bun x ultracite check
 ```
-Produces `dist/release/hack-<version>-release/`, a tarball, and `hack-install.sh`.
-
-### Release (tag + GitHub workflow)
-
-```bash
-bun run release:prepare
-git push --follow-tags
-```
-
-Updates `CHANGELOG.md` plus root/workspace `package.json` versions, creates the release commit and tag, and triggers the GitHub Release workflow on push.
-
-See `PACKAGING.md` for details.
 
+Useful repo-level commands:
 
-See also:
-- [Examples](examples/next-app/README.md)
-- [Docs](docs/README.md)
-- [Architecture](docs/architecture.md)
+- `bun run build`
+- `bun run test`
+- `bun run check`
+- `bun run macos:build`
 
+## Beta note
 
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
+Remote control plane, multi-node execution, and the macOS app are all still **Beta**. They are
+useful, but they are not the core path a new user needs to learn first.
diff --git a/apps/macos/README.md b/apps/macos/README.md
index d6dd111c5..a9b3ec9eb 100644
--- a/apps/macos/README.md
+++ b/apps/macos/README.md
@@ -1,7 +1,9 @@
-# Hack Desktop (macOS)
+# Hack Desktop for macOS (Beta)
 
 Native macOS app for managing local hack projects and daemon status.
 
+> Beta: the macOS app is useful, but it is still outside Hack's core getting-started path.
+
 ## Requirements
 
 - macOS 14+
diff --git a/docs/README.md b/docs/README.md
index e493be242..b99b525e0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,45 +1,52 @@
 # Docs
 
-This directory contains the public documentation for hack. Specs remain in `SPECS/` (working notes).
+This directory is organized around the product story instead of the implementation tree.
 
-## Core docs
+If you are new to Hack, start with the core path first, then move into integrations, then only
+visit the beta and reference surfaces you actually need.
 
+## Core workflows
+
+- [Initialize a project](guides/init-project.md)
 - [CLI reference](cli.md)
+- [Env & secrets](env.md)
+- [Sessions](sessions.md)
+- [Lifecycle](lifecycle.md)
+- [Global settings](guides/global-settings.md)
 - [Architecture](architecture.md)
-- [Sessions](sessions.md) - mux session management (tmux or zellij) + API
-- [Env & secrets](env.md) - env contract + `.hack/.env` + OS keychain secrets
-- [Lifecycle](lifecycle.md) - project startup hooks + managed host processes
-- [Gateway overview](gateway.md)
-- [Gateway API](gateway-api.md)
-- [Supervisor](supervisor.md)
-- [Extensions](extensions.md)
-- [Control-plane SDK](sdk.md)
 
-Monorepo note:
-- Root scripts orchestrate workspace tasks through Turbo.
-- Package-local commands remain available via `bun run --cwd <workspace> <script>`.
+## Integrations & collaboration
 
-Quick diagnostics:
-- `hack usage` (resource usage across running projects)
-- `hack usage --watch` (live resource trends)
-- `hack node routes status` (controller-side remote route bridge state)
-- `hack node routes repair` (re-apply persisted remote route bridge routes)
+- [Integrations overview](integrations.md)
+- [Tickets (git-backed)](guides/tickets.md)
+- [Linear integration architecture](guides/linear-integration-architecture.md)
 
-## Guides
+## Beta workflows
 
-- Start here (first remote node in ~10 minutes):
-  - [Remote node quickstart](guides/remote-node-quickstart.md)
-  - [Run laptop-to-laptop node pairing e2e](guides/remote-node-laptop-e2e.md)
-  - [Bootstrap a remote node on Railway](guides/remote-node-railway.md)
-- Remote setup (one command): `hack remote setup`
-- [Initialize a project](guides/init-project.md)
-- [Global settings](guides/global-settings.md)
-- [Tickets (git-backed)](guides/tickets.md)
-- [Expose the gateway over SSH](guides/remote-ssh.md)
-- [Expose the gateway with Cloudflare](guides/remote-cloudflare.md)
-- [Expose the gateway with Tailscale](guides/remote-tailscale.md)
-- [Run remote supervisor jobs](guides/remote-supervisor.md)
-- [Run a remote node via container image](guides/remote-node-container.md)
-- [Bootstrap a remote node on Railway](guides/remote-node-railway.md)
-- [Bootstrap auth-broker with Neon + Railway](guides/auth-broker-neon-bootstrap.md)
+- [Gateway (Beta)](gateway.md)
+- [Remote node quickstart (Beta)](guides/remote-node-quickstart.md)
+- [Remote node runtime container (Beta)](guides/remote-node-container.md)
+- [Remote node on Railway (Beta)](guides/remote-node-railway.md)
+- [Laptop-to-laptop remote node validation (Beta)](guides/remote-node-laptop-e2e.md)
+- [Expose the gateway over SSH (Beta)](guides/remote-ssh.md)
+- [Expose the gateway with Cloudflare (Beta)](guides/remote-cloudflare.md)
+- [Expose the gateway with Tailscale (Beta)](guides/remote-tailscale.md)
+- [Run remote supervisor jobs (Beta)](guides/remote-supervisor.md)
+- [Hack Desktop for macOS (Beta)](../apps/macos/README.md)
+
+## Extensions & reference
+
+- [Extensions & SDK reference](extensions.md)
+- [Gateway API (Beta)](gateway-api.md)
+- [Supervisor (Beta)](supervisor.md)
+- [Gateway auth-broker bootstrap](guides/auth-broker-neon-bootstrap.md)
 - [Create a new extension](guides/create-extension.md)
+- [Control-plane SDK](sdk.md)
+
+## Quick diagnostics
+
+- `hack help`
+- `hack status`
+- `hack usage`
+- `hack usage --watch`
+- `hack doctor`
diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..2919d0fe9 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -3,6 +3,14 @@
 This reference mirrors the CLI spec in `src/cli/spec.ts`.
 Run `hack help` or `hack help <command>` for interactive help.
 
+If you are new to Hack, scan the CLI in this order:
+
+1. `Global commands` for machine setup
+2. `Core workflows` for day-to-day local development
+3. `Collaboration & integrations` for env, sessions, tickets, Linear, and SSH access
+4. `Beta workflows` for remote control plane and multi-node execution
+5. `Extension commands` when you need the lower-level namespace surface
+
 ## Conventions
 
 - Commands that accept both `--path` and `--project` treat them as mutually exclusive.
@@ -18,31 +26,32 @@ Run `hack help` or `hack help <command>` for interactive help.
 | `hack projects` | Show all projects (registry + running docker compose) | Global |
 | `hack status` | Show project status (shortcut for `hack projects --details`) | Global |
 | `hack usage` | Show resource usage across running projects | Global |
-| `hack init` | Initialize a repo (generate .hack/ with compose + config) | Project |
-| `hack up` | Start project services (docker compose up) | Project |
-| `hack down` | Stop project services (docker compose down) | Project |
-| `hack restart` | Restart project services (down then up) | Project |
-| `hack ps` | Show project status (docker compose ps) | Project |
-| `hack logs` | Tail logs (compose by default; Loki for queries/history via --loki/--query) | Project |
-| `hack run` | Run a one-off command in a service container (docker compose run --rm) | Project |
-| `hack open` | Open a URL for the project (default: https://<project>.hack) | Project |
-| `hack tui` | Open the project TUI (services + logs) | Project |
-| `hack branch` | Manage branch aliases for a project | Project |
-| `hack linear` | Linear account connection and ticket sync | Project |
-| `hack config` | Read/write hack.config.json values | Project |
-| `hack env` | Manage project environment variables and secrets | Project |
-| `hack session` | Manage terminal sessions for hack projects | Project |
-| `hack ssh` | Show SSH connection info for remote access | Project |
-| `hack tickets` | Git-backed ticket management | Project |
+| `hack init` | Initialize a repo (generate .hack/ with compose + config) | Core workflows |
+| `hack up` | Start project services (docker compose up) | Core workflows |
+| `hack down` | Stop project services (docker compose down) | Core workflows |
+| `hack restart` | Restart project services (down then up) | Core workflows |
+| `hack ps` | Show project status (docker compose ps) | Core workflows |
+| `hack logs` | Tail logs (compose by default; Loki for queries/history via --loki/--query) | Core workflows |
+| `hack run` | Run a one-off command in a service container (docker compose run --rm) | Core workflows |
+| `hack open` | Open a URL for the project (default: https://<project>.hack) | Core workflows |
+| `hack tui` | Open the project TUI (services + logs) | Core workflows |
+| `hack branch` | Manage branch aliases for a project | Core workflows |
+| `hack config` | Read/write hack.config.json values | Core workflows |
+| `hack auth` | Manage Hack account sign-in | Collaboration & integrations |
+| `hack linear` | Connect Linear and sync selected work into the repo | Collaboration & integrations |
+| `hack env` | Share project env contracts and store local secrets | Collaboration & integrations |
+| `hack session` | Keep persistent work sessions for projects and agents | Collaboration & integrations |
+| `hack ssh` | Show SSH details for reaching this machine and its sessions | Collaboration & integrations |
+| `hack tickets` | Track repo-local work in git-backed tickets | Collaboration & integrations |
 | `hack internal` | Manage hack-managed internal overrides | Internal |
-| `hack gateway` | Manage gateway enablement | Extensions |
-| `hack node` | Manage remote execution nodes | Extensions |
-| `hack dispatch` | Dispatch branch-scoped jobs to remote nodes | Extensions |
-| `hack remote` | Remote workflow helpers | Extensions |
-| `hack x` | Run extension commands | Extensions |
-| `hack setup` | Install integrations for coding agents | Agents |
-| `hack agent` | Agent utilities | Agents |
-| `hack mcp` | Manage MCP server integrations for coding agents | Agents |
+| `hack gateway` | Beta: manage the remote control plane entrypoint | Beta workflows |
+| `hack node` | Beta: manage remote execution nodes | Beta workflows |
+| `hack dispatch` | Beta: run branch-scoped jobs on remote nodes | Beta workflows |
+| `hack remote` | Beta: guided remote access and gateway helpers | Beta workflows |
+| `hack x` | Run extension commands | Extension commands |
+| `hack setup` | Install integrations for coding agents | Agent integrations |
+| `hack agent` | Agent utilities | Agent integrations |
+| `hack mcp` | Manage MCP server integrations for coding agents | Agent integrations |
 | `hack doctor` | Validate local setup (docker, networks, DNS, global infra, project config) | Diagnostics |
 | `hack crash-capture` | Capture runtime crash diagnostics into `.tmp/` for triage | Diagnostics |
 | `hack daemon` | Manage the local hack daemon (hackd) | Diagnostics |
@@ -174,7 +183,7 @@ Options:
 | `--no-host` | boolean | false | Skip host process metrics |
 | `--json` | boolean | false | Output JSON (machine-readable); not supported with `--watch` |
 
-## Project commands
+## Core workflows
 
 ### hack init
 
@@ -472,6 +481,66 @@ Options:
 | `--project <name>` | string | - | Target a registered project by name |
 | `--global` | boolean | false | Write global `~/.hack/hack.config.json` |
 
+## Collaboration & integrations
+
+### hack auth
+
+Usage: `hack auth <subcommand>`
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `login` | Open a browser and sign in to Hack auth |
+| `logout` | Clear the locally stored Hack auth session |
+| `status` | Show whether Hack auth is configured locally |
+| `whoami` | Resolve the current Hack auth identity via the broker |
+
+#### hack auth login
+
+Usage: `hack auth login [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON |
+| `--no-open` | boolean | false | Print the browser URL instead of opening it automatically |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+| `--redirect <url>` | string | - | Return to this URL after browser sign-in finishes |
+
+#### hack auth logout
+
+Usage: `hack auth logout [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON |
+
+#### hack auth status
+
+Usage: `hack auth status [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+#### hack auth whoami
+
+Usage: `hack auth whoami [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
 ### hack env
 
 Usage: `hack env <subcommand>`
@@ -698,7 +767,7 @@ Usage: `hack internal extra-hosts unset <hostname> [options]`
 
 Usage: `hack internal extra-hosts list [options]`
 
-## Extension commands
+## Beta workflows
 
 ### hack gateway
 
@@ -1036,6 +1105,8 @@ Options:
 | `--ssh-port <port>` | number | - | SSH port for QR payload (omitted defaults to 22) |
 | `--yes` | boolean | false | Skip confirmation before printing sensitive QR payloads |
 
+## Extension commands
+
 ### hack x
 
 Usage: `hack x <namespace> <command> [args...]`
@@ -1051,7 +1122,7 @@ Notes:
 - `hack x list` lists available extensions.
 - `hack x <namespace> help` lists commands for a namespace.
 
-## Agent commands
+## Agent integrations
 
 ### hack setup
 
diff --git a/docs/extensions.md b/docs/extensions.md
index b4c8b0a81..fe2d10339 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -1,7 +1,9 @@
-# Extensions & SDK (v0.1)
+# Extensions & SDK Reference
 
-This doc defines the extension surface area for `hack` and how extension commands are authored,
-configured, and dispatched.
+This is the lower-level reference for extension commands, SDK surfaces, and extension dispatch.
+
+If you want the plain-language product overview first, read [integrations.md](integrations.md)
+before this page.
 
 ## Quick start (one command)
 
diff --git a/docs/gateway-api.md b/docs/gateway-api.md
index bbe4cd563..adca21122 100644
--- a/docs/gateway-api.md
+++ b/docs/gateway-api.md
@@ -1,9 +1,10 @@
-# Gateway API (hackd HTTP/WS)
+# Gateway API (Beta)
 
 The gateway exposes a small, authenticated HTTP/WS surface for remote orchestration. It is
 designed for structured workflows (jobs + log streaming + shells) and keeps write access
 opt-in with explicit guardrails.
 
+> Beta: this API belongs to the remote control plane, which is still beta.
 > ⚠️ Experimental: remote exposure steps are still being validated end-to-end.
 
 ## Security model (read this first)
diff --git a/docs/gateway.md b/docs/gateway.md
index 9a367e2a0..5a03311e5 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -1,9 +1,10 @@
-# Gateway (remote control plane)
+# Gateway (Beta remote control plane)
 
 The gateway exposes a small HTTP/WS surface on top of `hackd` so you can orchestrate jobs, stream
 logs, and open shells remotely. It is disabled by default and binds to `127.0.0.1` unless you
 explicitly expose it through SSH, Cloudflare, or Tailscale.
 
+> Beta: the remote control plane is not part of the core getting-started path yet.
 > ⚠️ Experimental: the remote exposure guides below are still being validated end-to-end.
 
 ## Concepts
diff --git a/docs/guides/remote-cloudflare.md b/docs/guides/remote-cloudflare.md
index 2f75279e0..a265c1d29 100644
--- a/docs/guides/remote-cloudflare.md
+++ b/docs/guides/remote-cloudflare.md
@@ -1,5 +1,6 @@
-# Expose the gateway with Cloudflare
+# Expose the gateway with Cloudflare (Beta)
 
+> Beta: Cloudflare gateway exposure is part of the remote control plane beta.
 > ⚠️ Experimental: this guide has not been validated end-to-end yet. Use with caution and report issues.
 
 Cloudflare Tunnel is ideal for HTTP/WS gateway access from a phone or browser when you are off-network.
diff --git a/docs/guides/remote-node-container.md b/docs/guides/remote-node-container.md
index 88d5df282..27648bd58 100644
--- a/docs/guides/remote-node-container.md
+++ b/docs/guides/remote-node-container.md
@@ -1,7 +1,9 @@
-# Remote Node Runtime Container
+# Remote Node Runtime Container (Beta)
 
 Use the published node-runtime container to spin up a remote node with minimal host setup.
 
+> Beta: multi-node execution is still being validated and is not part of the core local-dev path.
+
 Recommended public image:
 - `hackdance/hack:latest`
 
diff --git a/docs/guides/remote-node-laptop-e2e.md b/docs/guides/remote-node-laptop-e2e.md
index 0ff9c3864..dafd4afff 100644
--- a/docs/guides/remote-node-laptop-e2e.md
+++ b/docs/guides/remote-node-laptop-e2e.md
@@ -1,9 +1,11 @@
-# Run laptop-to-laptop node pairing e2e
+# Run laptop-to-laptop node pairing e2e (Beta)
 
 This guide is the full validation run for two Macs:
 1. Controller Mac (host mode)
 2. Remote MacBook node
 
+> Beta: laptop-to-laptop multi-node flows are still being validated and are not part of the core local-dev path.
+
 It validates pairing, remote routing, workspace mapping, mutagen sync, and dispatch execution.
 
 If you only need initial setup, use [Remote node quickstart](remote-node-quickstart.md) first.
diff --git a/docs/guides/remote-node-quickstart.md b/docs/guides/remote-node-quickstart.md
index d4af4bc71..ad6653814 100644
--- a/docs/guides/remote-node-quickstart.md
+++ b/docs/guides/remote-node-quickstart.md
@@ -1,7 +1,9 @@
-# Remote Node Quickstart
+# Remote Node Quickstart (Beta)
 
 Use this guide to connect one remote machine as a `hack` execution node and run a project on it.
 
+> Beta: multi-node execution is still being validated and is not part of the core local-dev path.
+
 ## What you need
 
 1. A host machine (controller) with `hack` installed.
diff --git a/docs/guides/remote-node-railway.md b/docs/guides/remote-node-railway.md
index 1fd58775f..2dafc7046 100644
--- a/docs/guides/remote-node-railway.md
+++ b/docs/guides/remote-node-railway.md
@@ -1,7 +1,9 @@
-# Railway Node Bootstrap Guide
+# Railway Node Bootstrap Guide (Beta)
 
 Use this guide to register a Railway-hosted runtime as a `hack` remote node.
 
+> Beta: provider-backed remote nodes are still being validated and are not part of the core local-dev path.
+
 If this is your first remote node, start with [Remote node quickstart](remote-node-quickstart.md) for core concepts.
 
 ## Quick Start
diff --git a/docs/guides/remote-ssh.md b/docs/guides/remote-ssh.md
index ed86f599d..75fc10b7a 100644
--- a/docs/guides/remote-ssh.md
+++ b/docs/guides/remote-ssh.md
@@ -1,5 +1,6 @@
-# Expose the gateway over SSH
+# Expose the gateway over SSH (Beta)
 
+> Beta: SSH gateway exposure is part of the remote control plane beta.
 > ⚠️ Experimental: this guide has not been validated end-to-end yet. Use with caution and report issues.
 
 Use SSH port-forwarding when you want quick, ad-hoc access without extra tooling.
diff --git a/docs/guides/remote-supervisor.md b/docs/guides/remote-supervisor.md
index b529cdebb..a6d43233f 100644
--- a/docs/guides/remote-supervisor.md
+++ b/docs/guides/remote-supervisor.md
@@ -1,7 +1,9 @@
-# Run remote supervisor jobs
+# Run remote supervisor jobs (Beta)
 
 Use the gateway API to run commands and stream logs remotely.
 
+> Beta: remote supervisor workflows are part of the remote control plane beta.
+
 ## Prereqs
 
 - Gateway enabled (`hack gateway setup`)
diff --git a/docs/guides/remote-tailscale.md b/docs/guides/remote-tailscale.md
index 3a9525765..3dcbbfc01 100644
--- a/docs/guides/remote-tailscale.md
+++ b/docs/guides/remote-tailscale.md
@@ -1,7 +1,9 @@
-# Expose the gateway with Tailscale
+# Expose the gateway with Tailscale (Beta)
 
 Use this guide when you want private tailnet-only access to `hack` gateway endpoints.
 
+> Beta: Tailscale gateway exposure is part of the remote control plane beta.
+
 Tailscale is recommended for:
 1. SSH from mobile/desktop clients.
 2. Private remote-node endpoints without public ingress.
diff --git a/docs/integrations.md b/docs/integrations.md
new file mode 100644
index 000000000..6edaede17
--- /dev/null
+++ b/docs/integrations.md
@@ -0,0 +1,126 @@
+# Integrations Overview
+
+Hack keeps the core local-dev path small, then layers supporting workflows around it.
+
+The easiest way to think about these integrations is:
+
+- GitHub and Linear connect Hack to systems that already exist outside your repo
+- Tickets, sessions, and env keep your daily workflow close to the repo itself
+- None of these are required to get started with `hack init`, `hack up`, and `hack open`
+
+## GitHub
+
+GitHub integration is for repo auth and pull-request workflows.
+
+Use it when you want Hack to:
+
+- authenticate private repo or automation flows
+- create or update a PR as part of a run or release workflow
+- keep more than one GitHub profile available on the same machine
+
+Main surface:
+
+- `hack x github connect`
+- `hack x github status`
+- `hack x github pr-upsert`
+
+Reference:
+
+- [Extensions & SDK reference](extensions.md)
+
+## Linear
+
+Linear integration is for syncing selected planning work into the repo, not for replacing your
+whole Linear setup.
+
+Use it when you want Hack to:
+
+- connect a local Linear profile
+- bind a Hack project to a Linear project
+- sync a specific issue or project into repo-local workflow state
+
+Main surface:
+
+- `hack linear status`
+- `hack linear connect`
+- `hack linear sync-issue`
+- `hack linear sync-project`
+
+Reference:
+
+- [Linear integration architecture](guides/linear-integration-architecture.md)
+- [Extensions & SDK reference](extensions.md)
+
+## Tickets
+
+Tickets are a lightweight, git-backed work log that lives with the repo instead of in a separate
+hosted tracker.
+
+Use them when you want to:
+
+- capture follow-up work during implementation
+- keep agent-created tasks next to the code
+- sync issue state through git refs instead of another service
+
+Main surface:
+
+- `hack tickets create`
+- `hack tickets list`
+- `hack tickets show`
+- `hack tickets status`
+- `hack tickets sync`
+
+Reference:
+
+- [Tickets guide](guides/tickets.md)
+
+## Sessions
+
+Sessions are durable terminal workspaces for humans and agents.
+
+Use them when you want to:
+
+- keep a project shell alive between reconnects
+- give an agent its own long-lived workspace
+- reattach to an existing terminal workflow instead of starting from scratch
+
+Main surface:
+
+- `hack session`
+- `hack session start`
+- `hack session attach`
+- `hack session exec`
+
+Reference:
+
+- [Sessions](sessions.md)
+
+## Env
+
+Env support gives the repo a clear contract for configuration without committing the actual secret
+values.
+
+Use it when you want to:
+
+- declare what variables a project needs
+- keep plain values in `.hack/.env`
+- keep sensitive values in a secret backend
+
+Main surface:
+
+- `hack env list`
+- `hack env set`
+- `hack env unset`
+- `hack env backend status`
+
+Reference:
+
+- [Env & secrets](env.md)
+
+## Choosing the right surface
+
+- Start with the core path if you just need a project running locally
+- Add env when a repo needs repeatable configuration
+- Add sessions when you want durable terminal workflows
+- Add tickets when follow-up work should stay in git
+- Add GitHub or Linear only when you need those external systems connected
diff --git a/docs/supervisor.md b/docs/supervisor.md
index 559ba4db0..768cbcfad 100644
--- a/docs/supervisor.md
+++ b/docs/supervisor.md
@@ -1,9 +1,11 @@
-# Supervisor (jobs + shells)
+# Supervisor (Beta)
 
 The supervisor is the execution engine behind remote workflows. It can run commands as jobs,
 stream logs/events, and host PTY-backed shells. The CLI exposes it locally via `hack x supervisor`
 and remotely through the gateway API.
 
+> Beta: supervisor is part of Hack's remote workflow surface, not the core getting-started path.
+
 ## Local usage
 
 ```bash
diff --git a/src/cli/command.ts b/src/cli/command.ts
index ee10fdbc4..b9f4ad16f 100644
--- a/src/cli/command.ts
+++ b/src/cli/command.ts
@@ -8,6 +8,8 @@ const SHORT_OPTION_PREFIX_REGEX = /^-/;
 export type CliGroup =
   | "Global"
   | "Project"
+  | "Integrations"
+  | "Beta"
   | "Extensions"
   | "Agents"
   | "Diagnostics"
@@ -111,6 +113,7 @@ export interface CliSpec {
   readonly name: string;
   readonly version: string;
   readonly summary: string;
+  readonly highlights?: readonly string[];
   readonly commands: readonly AnyCommandSpec[];
   readonly globalOptions: readonly OptionSpec[];
 }
diff --git a/src/cli/help.ts b/src/cli/help.ts
index f58e64353..09bd2834b 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -80,6 +80,14 @@ function renderRootHelp(cli: CliSpec): string {
   lines.push(`  ${cli.name} <command> [options]`);
   lines.push("");
 
+  if (cli.highlights && cli.highlights.length > 0) {
+    lines.push("Core promises:");
+    for (const [index, highlight] of cli.highlights.entries()) {
+      lines.push(`  ${index + 1}. ${highlight}`);
+    }
+    lines.push("");
+  }
+
   const grouped = groupRootEntries(cli);
   for (const group of groupsInOrder()) {
     const entries = grouped.get(group);
@@ -121,6 +129,15 @@ function renderRootHelpMarkdown(cli: CliSpec): string {
   lines.push("```");
   lines.push("");
 
+  if (cli.highlights && cli.highlights.length > 0) {
+    lines.push("### Core promises");
+    lines.push("");
+    for (const highlight of cli.highlights) {
+      lines.push(`1. ${mdEscape(highlight)}`);
+    }
+    lines.push("");
+  }
+
   const grouped = groupRootEntries(cli);
   for (const group of groupsInOrder()) {
     const entries = grouped.get(group);
@@ -393,6 +410,8 @@ function groupsInOrder(): readonly CliGroup[] {
   return [
     "Global",
     "Project",
+    "Integrations",
+    "Beta",
     "Extensions",
     "Agents",
     "Diagnostics",
@@ -405,8 +424,10 @@ function groupLabel(group: CliGroup): string {
   return (
     {
       Global: "Global commands",
-      Project: "Project commands",
-      Extensions: "Extensions",
+      Project: "Core workflows",
+      Integrations: "Collaboration & integrations",
+      Beta: "Beta workflows",
+      Extensions: "Extension commands",
       Agents: "Agent integrations",
       Diagnostics: "Diagnostics",
       Secrets: "Secrets",
diff --git a/src/cli/spec.ts b/src/cli/spec.ts
index 079084d87..ae589344a 100644
--- a/src/cli/spec.ts
+++ b/src/cli/spec.ts
@@ -50,8 +50,12 @@ const packageJson = pkg as unknown as PackageJsonType;
 export const CLI_SPEC = defineCli({
   name: "hack",
   version: packageJson.version,
-  summary:
-    "run multiple local projects concurrently (network isolation + https://*.hack)",
+  summary: "Local development without the port-collision tax",
+  highlights: [
+    "Run multiple repos or branches at the same time without port conflicts.",
+    "Give every project a stable HTTPS URL like https://myapp.hack.",
+    "Keep env, sessions, tickets, and integrations close to the repo.",
+  ] as const,
   globalOptions: [],
   commands: [
     globalCommand,
diff --git a/src/commands/auth.ts b/src/commands/auth.ts
index 243db4f65..8271491c4 100644
--- a/src/commands/auth.ts
+++ b/src/commands/auth.ts
@@ -41,7 +41,7 @@ const optRedirect = defineOption({
 const loginSpec = defineCommand({
   name: "login",
   summary: "Open a browser and sign in to Hack auth",
-  group: "Global",
+  group: "Integrations",
   options: [optJson, optNoOpen, optBrokerUrl, optRedirect] as const,
   positionals: [] as const,
   subcommands: [] as const,
@@ -50,7 +50,7 @@ const loginSpec = defineCommand({
 const logoutSpec = defineCommand({
   name: "logout",
   summary: "Clear the locally stored Hack auth session",
-  group: "Global",
+  group: "Integrations",
   options: [optJson] as const,
   positionals: [] as const,
   subcommands: [] as const,
@@ -59,7 +59,7 @@ const logoutSpec = defineCommand({
 const statusSpec = defineCommand({
   name: "status",
   summary: "Show whether Hack auth is configured locally",
-  group: "Global",
+  group: "Integrations",
   options: [optJson, optBrokerUrl] as const,
   positionals: [] as const,
   subcommands: [] as const,
@@ -68,7 +68,7 @@ const statusSpec = defineCommand({
 const whoamiSpec = defineCommand({
   name: "whoami",
   summary: "Resolve the current Hack auth identity via the broker",
-  group: "Global",
+  group: "Integrations",
   options: [optJson, optBrokerUrl] as const,
   positionals: [] as const,
   subcommands: [] as const,
@@ -76,9 +76,9 @@ const whoamiSpec = defineCommand({
 
 export const authCommand = defineCommand({
   name: "auth",
-  summary: "Manage Hack auth sessions",
-  group: "Global",
-  expandInRootHelp: true,
+  summary: "Manage Hack account sign-in",
+  group: "Integrations",
+  expandInRootHelp: false,
   options: [] as const,
   positionals: [] as const,
   subcommands: [
diff --git a/src/commands/dispatch.ts b/src/commands/dispatch.ts
index daf3877e5..5bda50bf6 100644
--- a/src/commands/dispatch.ts
+++ b/src/commands/dispatch.ts
@@ -211,8 +211,8 @@ const logsPositionals = [{ name: "runId", required: true }] as const;
 
 const dispatchSpec = defineCommand({
   name: "dispatch",
-  summary: "Dispatch branch-scoped jobs to remote nodes",
-  group: "Extensions",
+  summary: "Beta: run branch-scoped jobs on remote nodes",
+  group: "Beta",
   options: [],
   positionals: [],
   subcommands: [],
@@ -221,7 +221,7 @@ const dispatchSpec = defineCommand({
 const runSpec = defineCommand({
   name: "run",
   summary: "Dispatch a command to a node workspace",
-  group: "Extensions",
+  group: "Beta",
   options: runOptions,
   positionals: runPositionals,
   subcommands: [],
@@ -230,7 +230,7 @@ const runSpec = defineCommand({
 const statusSpec = defineCommand({
   name: "status",
   summary: "Show dispatched run status",
-  group: "Extensions",
+  group: "Beta",
   options: statusOptions,
   positionals: statusPositionals,
   subcommands: [],
@@ -239,7 +239,7 @@ const statusSpec = defineCommand({
 const logsSpec = defineCommand({
   name: "logs",
   summary: "Show or follow persisted/remote run logs",
-  group: "Extensions",
+  group: "Beta",
   options: logsOptions,
   positionals: logsPositionals,
   subcommands: [],
diff --git a/src/commands/env.ts b/src/commands/env.ts
index 844d0f8da..c6c10cb42 100644
--- a/src/commands/env.ts
+++ b/src/commands/env.ts
@@ -620,8 +620,8 @@ async function resolveEnvValue(opts: {
 
 export const envCommand = defineCommand({
   name: "env",
-  summary: "Manage project environment variables and secrets",
-  group: "Project",
+  summary: "Share project env contracts and store local secrets",
+  group: "Integrations",
   expandInRootHelp: true,
   options: [],
   positionals: [],
diff --git a/src/commands/gateway.ts b/src/commands/gateway.ts
index 41e89a12e..8fc5d60b2 100644
--- a/src/commands/gateway.ts
+++ b/src/commands/gateway.ts
@@ -49,8 +49,8 @@ import { isTty } from "../ui/terminal.ts";
 
 const gatewaySpec = defineCommand({
   name: "gateway",
-  summary: "Manage gateway enablement",
-  group: "Extensions",
+  summary: "Beta: manage the remote control plane entrypoint",
+  group: "Beta",
   options: [],
   positionals: [],
   subcommands: [],
@@ -61,7 +61,7 @@ const toggleOptions = [optPath, optProject] as const;
 const enableSpec = defineCommand({
   name: "enable",
   summary: "Enable the gateway and start hackd",
-  group: "Extensions",
+  group: "Beta",
   options: toggleOptions,
   positionals: [],
   subcommands: [],
@@ -93,7 +93,7 @@ const setupOptions = [optPath, optProject, optQr, optNoQr, optYes] as const;
 const setupSpec = defineCommand({
   name: "setup",
   summary: "Guided gateway setup (enable + token)",
-  group: "Extensions",
+  group: "Beta",
   options: setupOptions,
   positionals: [],
   subcommands: [],
@@ -102,7 +102,7 @@ const setupSpec = defineCommand({
 const disableSpec = defineCommand({
   name: "disable",
   summary: "Disable the gateway (does not stop hackd)",
-  group: "Extensions",
+  group: "Beta",
   options: toggleOptions,
   positionals: [],
   subcommands: [],
diff --git a/src/commands/linear.ts b/src/commands/linear.ts
index 7c3426f9c..a68922b34 100644
--- a/src/commands/linear.ts
+++ b/src/commands/linear.ts
@@ -13,7 +13,7 @@ import { logger } from "../ui/logger.ts";
  */
 const linearSpec = defineCommand({
   name: "linear",
-  summary: "Linear account connection and ticket sync",
+  summary: "Connect Linear and sync selected work into the repo",
   description: [
     "Usage:",
     "  hack linear status",
@@ -27,7 +27,7 @@ const linearSpec = defineCommand({
     "",
     "Alias for `hack x linear <command>`. Requires extension enabled.",
   ].join("\n"),
-  group: "Project",
+  group: "Integrations",
   options: [],
   positionals: [{ name: "args", required: false, multiple: true }],
   subcommands: [],
diff --git a/src/commands/node.ts b/src/commands/node.ts
index 61fa2d1aa..9fb268242 100644
--- a/src/commands/node.ts
+++ b/src/commands/node.ts
@@ -406,8 +406,8 @@ const optTailscaleTags = defineOption({
 
 const nodeSpec = defineCommand({
   name: "node",
-  summary: "Manage remote execution nodes",
-  group: "Extensions",
+  summary: "Beta: manage remote execution nodes",
+  group: "Beta",
   options: [],
   positionals: [],
   subcommands: [],
diff --git a/src/commands/remote.ts b/src/commands/remote.ts
index d00ac6b86..f37219bf6 100644
--- a/src/commands/remote.ts
+++ b/src/commands/remote.ts
@@ -146,8 +146,8 @@ const setupOptions = [optPath, optProject, optQr, optNoQr, optYes] as const;
 
 const remoteSpec = defineCommand({
   name: "remote",
-  summary: "Remote workflow helpers",
-  group: "Extensions",
+  summary: "Beta: guided remote access and gateway helpers",
+  group: "Beta",
   options: remoteOptions,
   positionals: [],
   subcommands: [],
@@ -156,7 +156,7 @@ const remoteSpec = defineCommand({
 const setupSpec = defineCommand({
   name: "setup",
   summary: "Run the guided gateway setup",
-  group: "Extensions",
+  group: "Beta",
   options: setupOptions,
   positionals: [],
   subcommands: [],
@@ -165,7 +165,7 @@ const setupSpec = defineCommand({
 const statusSpec = defineCommand({
   name: "status",
   summary: "Show remote/gateway status",
-  group: "Extensions",
+  group: "Beta",
   options: remoteOptions,
   positionals: [],
   subcommands: [],
@@ -174,7 +174,7 @@ const statusSpec = defineCommand({
 const monitorSpec = defineCommand({
   name: "monitor",
   summary: "Open a remote status TUI",
-  group: "Extensions",
+  group: "Beta",
   options: remoteOptions,
   positionals: [],
   subcommands: [],
@@ -183,7 +183,7 @@ const monitorSpec = defineCommand({
 const qrSpec = defineCommand({
   name: "qr",
   summary: "Print a QR payload for remote access",
-  group: "Extensions",
+  group: "Beta",
   options: qrOptions,
   positionals: [],
   subcommands: [],
diff --git a/src/commands/session.ts b/src/commands/session.ts
index 5d1a7a717..496084e9b 100644
--- a/src/commands/session.ts
+++ b/src/commands/session.ts
@@ -793,8 +793,8 @@ const handleTail = async ({
 
 export const sessionCommand = defineCommand({
   name: "session",
-  summary: "Manage tmux sessions for hack projects",
-  group: "Project",
+  summary: "Keep persistent work sessions for projects and agents",
+  group: "Integrations",
   options: [],
   positionals: [],
   handler: handleSessionPicker,
diff --git a/src/commands/ssh.ts b/src/commands/ssh.ts
index 83dcb64d8..76ac116ed 100644
--- a/src/commands/ssh.ts
+++ b/src/commands/ssh.ts
@@ -65,8 +65,8 @@ const optPort = defineOption({
 
 const sshSpec = defineCommand({
   name: "ssh",
-  summary: "Show SSH connection info for remote access to this machine",
-  group: "Project",
+  summary: "Show SSH details for reaching this machine and its sessions",
+  group: "Integrations",
   options: [optHost, optUser, optTailscale, optDirect, optPort],
   positionals: [
     { name: "session", description: "Session to connect to", required: false },
diff --git a/src/commands/tickets.ts b/src/commands/tickets.ts
index 8e0d691fc..fbcfe0663 100644
--- a/src/commands/tickets.ts
+++ b/src/commands/tickets.ts
@@ -14,7 +14,7 @@ import { logger } from "../ui/logger.ts";
  */
 const ticketsSpec = defineCommand({
   name: "tickets",
-  summary: "Git-backed ticket management",
+  summary: "Track repo-local work in git-backed tickets",
   description: [
     "Usage:",
     "  hack tickets list",
@@ -28,7 +28,7 @@ const ticketsSpec = defineCommand({
     "",
     "Alias for `hack x tickets <command>`. Requires extension enabled.",
   ].join("\n"),
-  group: "Project",
+  group: "Integrations",
   options: [],
   positionals: [{ name: "args", required: false, multiple: true }],
   subcommands: [],
diff --git a/tests/cli-help.test.ts b/tests/cli-help.test.ts
new file mode 100644
index 000000000..c0f3af68b
--- /dev/null
+++ b/tests/cli-help.test.ts
@@ -0,0 +1,52 @@
+import { expect, test } from "bun:test";
+import {
+  renderHelpForPath,
+  renderHelpMarkdownForPath,
+} from "../src/cli/help.ts";
+import { CLI_SPEC } from "../src/cli/spec.ts";
+
+test("root help leads with core promises and separates core from beta surfaces", () => {
+  const help = renderHelpForPath(CLI_SPEC, []);
+
+  expect(help).toContain("Local development without the port-collision tax");
+  expect(help).toContain("Core promises:");
+  expect(help).toContain(
+    "1. Run multiple repos or branches at the same time without port conflicts."
+  );
+  expect(help).toContain("Core workflows:");
+  expect(help).toContain("Collaboration & integrations:");
+  expect(help).toContain("Beta workflows:");
+  expect(help).toContain("Extension commands:");
+  expect(help).toMatch(
+    /hack remote\s+Beta: guided remote access and gateway helpers/
+  );
+  expect(help).toMatch(
+    /hack tickets(?: \[args\.\.\.\])?\s+Track repo-local work in git-backed tickets/
+  );
+
+  expect(help.indexOf("Core workflows:")).toBeLessThan(
+    help.indexOf("Beta workflows:")
+  );
+  expect(help).toMatch(/hack auth\s+Manage Hack account sign-in/);
+  expect(help.indexOf("Collaboration & integrations:")).toBeLessThan(
+    help.indexOf("hack auth")
+  );
+  expect(help.indexOf("hack auth")).toBeLessThan(
+    help.indexOf("Beta workflows:")
+  );
+  expect(help).not.toContain("hack auth login");
+});
+
+test("markdown help preserves the core offer and command grouping", () => {
+  const help = renderHelpMarkdownForPath(CLI_SPEC, []);
+
+  expect(help).toContain("### Core promises");
+  expect(help).toContain(
+    "1. Run multiple repos or branches at the same time without port conflicts."
+  );
+  expect(help).toContain("### Core workflows");
+  expect(help).toContain("### Collaboration & integrations");
+  expect(help).toContain("### Beta workflows");
+  expect(help).toContain("### Extension commands");
+  expect(help).toContain("`hack auth`");
+});

From 2613f35ef6dc616ea992d213c2b6a7e3ae1a74f9 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 16:48:11 +0000
Subject: [PATCH 086/134] fix: keep root help aligned with docs ia

---
 README.md              | 4 ++--
 src/cli/help.ts        | 5 +++++
 tests/cli-help.test.ts | 8 ++++++++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 3c134f4f4..40bd39448 100644
--- a/README.md
+++ b/README.md
@@ -101,7 +101,7 @@ instead of treating Linear as a separate universe.
 
 - Main surface: `hack linear ...`
 - Common use: connect a profile, bind a project, sync issues or project state
-- Reference: [docs/integrations.md](docs/integrations.md)
+- Reference: [docs/guides/linear-integration-architecture.md](docs/guides/linear-integration-architecture.md)
 
 ### Tickets
 
@@ -146,7 +146,7 @@ Beta surfaces are intentionally separate:
 Reference surfaces:
 
 - Extensions and SDK: [docs/extensions.md](docs/extensions.md)
-- Gateway API: [docs/gateway-api.md](docs/gateway-api.md)
+- Gateway API (Beta): [docs/gateway-api.md](docs/gateway-api.md)
 - Architecture: [docs/architecture.md](docs/architecture.md)
 
 ## `hack help` guide
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 09bd2834b..b943062ca 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -185,6 +185,11 @@ function groupRootEntries(cli: CliSpec): Map<CliGroup, RootEntry[]> {
 
   for (const cmd of cli.commands) {
     if (cmd.expandInRootHelp && cmd.subcommands.length > 0) {
+      push(cmd.group, {
+        group: cmd.group,
+        invocation: buildInvocation(cli.name, [cmd.name], cmd),
+        summary: cmd.summary,
+      });
       for (const sub of cmd.subcommands) {
         const invocation = buildInvocation(cli.name, [cmd.name, sub.name], sub);
         push(cmd.group, { group: cmd.group, invocation, summary: sub.summary });
diff --git a/tests/cli-help.test.ts b/tests/cli-help.test.ts
index c0f3af68b..4a614b9d1 100644
--- a/tests/cli-help.test.ts
+++ b/tests/cli-help.test.ts
@@ -23,6 +23,12 @@ test("root help leads with core promises and separates core from beta surfaces",
   expect(help).toMatch(
     /hack tickets(?: \[args\.\.\.\])?\s+Track repo-local work in git-backed tickets/
   );
+  expect(help).toMatch(
+    /hack projects\s+Show all projects \(registry \+ running docker compose\)/
+  );
+  expect(help).toMatch(
+    /hack projects prune\s+Remove missing registry entries and stop orphaned containers/
+  );
 
   expect(help.indexOf("Core workflows:")).toBeLessThan(
     help.indexOf("Beta workflows:")
@@ -49,4 +55,6 @@ test("markdown help preserves the core offer and command grouping", () => {
   expect(help).toContain("### Beta workflows");
   expect(help).toContain("### Extension commands");
   expect(help).toContain("`hack auth`");
+  expect(help).toContain("`hack projects`");
+  expect(help).toContain("`hack projects prune`");
 });

From 17d01f4fd724281f0aa0c315e415f0354645118e Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:06:07 +0000
Subject: [PATCH 087/134] HACK-428: checkpoint merge prep

---
 src/cli/help.ts        | 10 ++++++++++
 tests/cli-help.test.ts |  9 +++++++++
 2 files changed, 19 insertions(+)

diff --git a/src/cli/help.ts b/src/cli/help.ts
index b943062ca..4fc15e443 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -225,6 +225,11 @@ function renderCommandHelp(
   lines.push(`  ${invocation} [options]`);
   lines.push("");
 
+  if (command.group === "Beta") {
+    lines.push("Status: Beta workflow");
+    lines.push("");
+  }
+
   if (command.description) {
     lines.push(command.description);
     lines.push("");
@@ -275,6 +280,11 @@ function renderCommandHelpMarkdown(
   lines.push("```");
   lines.push("");
 
+  if (command.group === "Beta") {
+    lines.push("> Status: Beta workflow.");
+    lines.push("");
+  }
+
   if (command.description) {
     lines.push(mdEscape(command.description));
     lines.push("");
diff --git a/tests/cli-help.test.ts b/tests/cli-help.test.ts
index 4a614b9d1..6ce4fa30f 100644
--- a/tests/cli-help.test.ts
+++ b/tests/cli-help.test.ts
@@ -58,3 +58,12 @@ test("markdown help preserves the core offer and command grouping", () => {
   expect(help).toContain("`hack projects`");
   expect(help).toContain("`hack projects prune`");
 });
+
+test("beta subcommand help stays visibly labeled beta", () => {
+  const help = renderHelpForPath(CLI_SPEC, ["remote", "setup"]);
+  const markdown = renderHelpMarkdownForPath(CLI_SPEC, ["remote", "setup"]);
+
+  expect(help).toContain("hack remote setup");
+  expect(help).toContain("Status: Beta workflow");
+  expect(markdown).toContain("> Status: Beta workflow.");
+});

From 49ce93cc4659db94dc8817ad6cedc625c836eb8e Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Fri, 13 Mar 2026 22:30:38 +0000
Subject: [PATCH 088/134] docs: define first-class github workflows

---
 docs/cli.md                                   |   6 +
 docs/extensions.md                            |  64 ++++
 ...-13-github-first-class-workflows-design.md | 237 ++++++++++++++
 ...03-13-github-first-class-workflows-plan.md | 299 ++++++++++++++++++
 4 files changed, 606 insertions(+)
 create mode 100644 docs/plans/2026-03-13-github-first-class-workflows-design.md
 create mode 100644 docs/plans/2026-03-13-github-first-class-workflows-plan.md

diff --git a/docs/cli.md b/docs/cli.md
index 2919d0fe9..83ab9a58b 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1028,6 +1028,12 @@ GitHub profile precedence for `--pr`:
 2. Project `controlPlane.routing.overrides.github.profile`.
 3. Global `controlPlane.extensions["dance.hack.github"].config.defaultProfile`.
 
+Scope note for `--pr`:
+
+- `hack dispatch run --pr` currently covers the PR update workflow only: push the branch, then create or update the PR.
+- It does not imply broader GitHub workflow support such as review submission, standalone PR comments, merge actions, or repo-admin actions.
+- The broader first-class GitHub workflow model lives in the GitHub extension docs and `docs/plans/2026-03-13-github-first-class-workflows-design.md`, and is intentionally sequenced beyond the current `--pr` path.
+
 #### hack dispatch status
 
 Usage: `hack dispatch status <run-id> [--json]`
diff --git a/docs/extensions.md b/docs/extensions.md
index fe2d10339..0416ef7c5 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -275,6 +275,70 @@ Notes:
 - macOS desktop shows read-only system Git identity (host-level inherited Git/gh context) separately from remote OAuth/App accounts to keep local gateway identity and remote auth routing boundaries explicit.
 - `auth.hack` and `auth.hack.gy` are routed by global Caddy to the daemon auth listener (`127.0.0.1:7790` by default), so this endpoint can also host future provider callbacks/hooks.
 
+Workflow scope:
+
+- Current shipped GitHub workflow support is intentionally narrow:
+  - auth/profile connection and selection
+  - PR create/update via `hack x github pr-upsert`
+- The first-class GitHub workflow model for the current milestone is bounded to:
+  - review intake and review decision
+  - PR update and readiness management
+  - PR-level conversation comments
+  - PR-adjacent repo handoff actions
+- The initial set is outcome-based rather than command-based so CLI, desktop, and agent surfaces can share the same product boundary.
+- Until those additional flows land, this section should not be read as claiming those commands already exist.
+
+Initial supported set for this milestone:
+
+1. Review intake for a relevant PR
+2. Review decision submission with a summary body
+3. PR creation/update plus draft-ready state changes
+4. Top-level PR comments
+5. Read-only repo-context handoff actions tied to a PR
+
+Initial workflow definitions:
+
+- Review intake and review decision
+  - Outcome: identify a PR needing action, inspect summary state, and submit `approve`, `comment`, or `request_changes`.
+- PR update and readiness management
+  - Outcome: create or update a PR, keep title/body/base accurate, and move between draft and ready states.
+- Conversation comments
+  - Outcome: leave top-level PR discussion comments without doing a full review submission.
+- PR-adjacent repo handoff actions
+  - Outcome: move from PR context to local repo/branch context without manually reconstructing refs.
+
+Explicitly out of the initial GitHub scope:
+
+- inline diff review comments and thread resolution
+- labels, assignees, milestones, and project edits
+- merge, merge queue, auto-merge, and rebase controls
+- rerunning GitHub Actions jobs
+- GitHub Issues, Projects, Discussions, releases, or repo admin surfaces
+
+Success criteria by workflow class:
+
+- Review intake and review decision
+  - A reviewer can identify a PR that needs action and submit `approve`, `comment`, or `request_changes` from Hack.
+- PR update and readiness management
+  - An author can create or correct a PR state, including draft and ready transitions, from Hack.
+- Conversation comments
+  - A user can leave a contextual PR comment without switching to GitHub web.
+- PR-adjacent repo handoff actions
+  - A user can move from PR context to local repo context without manual copy-paste of refs.
+
+Recommended implementation order:
+
+1. shared PR/review read models
+2. review decision submission
+3. PR metadata update plus draft/ready transitions
+4. standalone PR comment creation
+5. repo-context handoff actions
+
+Detailed design and sequencing live in:
+
+- `docs/plans/2026-03-13-github-first-class-workflows-design.md`
+- `docs/plans/2026-03-13-github-first-class-workflows-plan.md`
+
 ### Linear extension (`hack x linear`)
 
 Linear integration supports multiple auth profiles, project-level binding, and manual sync in both
diff --git a/docs/plans/2026-03-13-github-first-class-workflows-design.md b/docs/plans/2026-03-13-github-first-class-workflows-design.md
new file mode 100644
index 000000000..7fab9c98f
--- /dev/null
+++ b/docs/plans/2026-03-13-github-first-class-workflows-design.md
@@ -0,0 +1,237 @@
+# GitHub First-Class Workflows Design
+
+## Context
+
+Hack already has a GitHub extension, but its current surface is mostly auth/profile plumbing plus a narrow `pr-upsert` write path. That is enough to prove connectivity, but not enough to define what "GitHub support" means as a product capability. Without an explicit workflow set, future work risks growing as disconnected commands and one-off UI affordances.
+
+This ticket defines the first-class GitHub workflow boundary for the current milestone so implementation can sequence intentionally around user outcomes instead of command accumulation.
+
+## Goals
+
+- Define a prioritized, bounded initial GitHub workflow set.
+- Make the supported user outcomes explicit for reviews, PR updates, comments, and adjacent repo actions.
+- Separate the initial release scope from later expansion so product and engineering can say no clearly.
+- Provide enough sequencing guidance that implementation can proceed in phases.
+
+## Non-Goals
+
+- Defining every future GitHub action Hack may ever support.
+- Matching the full GitHub web UI.
+- Covering GitHub Issues, Projects, Discussions, releases, or repo administration in the initial set.
+- Designing the final CLI verbs or macOS UI in detail.
+
+## Approaches Considered
+
+### 1. Command-inventory definition
+
+Define scope around concrete commands such as `pr-upsert`, `review-submit`, and `comment-create`.
+
+Pros:
+
+- Easy to tie directly to implementation
+- Low ambiguity for CLI work
+
+Cons:
+
+- Locks product language to current transport details
+- Makes cross-surface planning harder for macOS, CLI, and agents
+
+### 2. Workflow-class definition (recommended)
+
+Define scope around user jobs such as "review a PR" or "update my PR", then map commands and UI to those jobs.
+
+Pros:
+
+- Keeps the capability user-outcome focused
+- Gives implementation freedom across CLI, desktop, and agents
+- Makes later expansion easier to reason about
+
+Cons:
+
+- Requires a little more up-front definition work
+
+### 3. Broad GitHub workbench
+
+Treat GitHub as a general remote workbench and include most adjacent actions now.
+
+Pros:
+
+- Ambitious and flexible
+
+Cons:
+
+- Too large for the current milestone
+- Makes "first-class" indistinguishable from "everything"
+- Weakens implementation sequencing
+
+## Recommendation
+
+Adopt the workflow-class model. The first-class GitHub surface should be defined by a small number of high-value jobs that users can complete end-to-end inside Hack. Commands, desktop affordances, and agent tools should then map onto those workflows.
+
+## Proposed First-Class Workflow Set
+
+### Priority 1: Review Intake and Review Decision
+
+**User outcome:** A user can see which PR needs their attention, inspect the decision context, and submit a review outcome without falling back to GitHub web for the common case.
+
+**Initial support**
+
+- List relevant PRs for the current user or current repo context.
+- Open a PR summary with:
+  - title, author, branch/base
+  - review state
+  - mergeability/check status summary
+  - changed file summary
+  - unresolved conversation/thread counts
+- Submit a review decision:
+  - `approve`
+  - `comment`
+  - `request_changes`
+- Include one summary review body with the decision.
+
+**Explicitly out of initial scope**
+
+- Inline diff comment authoring
+- Multi-comment review drafts
+- Thread resolution management
+- Batch review across many repositories
+
+**Success criteria**
+
+- A reviewer can identify a PR requiring action in one entry flow.
+- A reviewer can make an approve/comment/request-changes decision from Hack.
+- The review action returns the resulting GitHub review state and PR URL/id so downstream tooling can continue.
+
+### Priority 2: PR Update and Readiness Management
+
+**User outcome:** An author can create or keep a PR accurate and move it between draft and ready states without using the GitHub web UI.
+
+**Initial support**
+
+- Create or update a PR for the current branch/repo context.
+- Update title, body, and base branch.
+- Transition draft <-> ready for review.
+- Read current PR metadata before mutating it.
+- Optionally add a single top-level comment when performing a PR update.
+
+**Explicitly out of initial scope**
+
+- Label, assignee, milestone, or project edits
+- Auto-generated release notes
+- Merge queue controls
+- Auto-rebase, auto-merge, or branch protection bypass
+
+**Success criteria**
+
+- A branch with an existing or missing PR can be brought to a correct GitHub PR state from Hack.
+- An author can mark a PR ready or return it to draft.
+- The update flow is idempotent enough to support agent-driven use.
+
+### Priority 3: Conversation Comments
+
+**User outcome:** A user can leave PR-level discussion comments when they do not need a full review submission.
+
+**Initial support**
+
+- Create a top-level PR comment.
+- Reply to an existing discussion target only if GitHub exposes a clear non-inline comment target already represented in Hack state.
+- Show enough surrounding PR metadata so comments are not sent blind.
+
+**Explicitly out of initial scope**
+
+- Full threaded review comment authoring on diffs
+- Comment editing and deletion
+- Emoji reactions
+- Issue-wide/general GitHub social surface
+
+**Success criteria**
+
+- A user can post a contextual PR comment without switching tools.
+- Comment creation can be attached to either standalone discussion or a PR update flow.
+- The result includes a durable remote identifier for later correlation.
+
+### Priority 4: Adjacent Repo Actions
+
+**User outcome:** A user can move cleanly between GitHub PR context and local repo work without re-entering context manually.
+
+**Initial support**
+
+- Resolve the current branch to its PR, or a PR to its repo/branch refs.
+- Open or hand off to the local repo/branch context:
+  - checkout or branch/worktree handoff target
+  - canonical PR URL
+  - head/base refs
+  - changed file list summary
+- Show CI/check status summary as read-only context when acting on a PR.
+
+**Explicitly out of initial scope**
+
+- Merging a PR
+- Rebasing or updating branches on GitHub
+- Rerunning GitHub Actions jobs
+- Repo settings, secrets, releases, tags, or admin actions
+
+**Success criteria**
+
+- A user can pivot from PR context to local repo context with no manual copy-paste of branch/ref data.
+- Review and PR update workflows can reuse the same repo-context resolution primitives.
+- Repo actions remain supportive, not a second unbounded GitHub product surface.
+
+## Initial Supported Set
+
+The initial GitHub capability set is explicitly limited to:
+
+1. Review intake for a relevant PR
+2. Review decision submission with a summary body
+3. PR creation/update plus draft-ready state changes
+4. Top-level PR comments
+5. Read-only repo-context handoff actions tied to a PR
+
+Everything else is out unless it is necessary to make one of those five workflows function end-to-end.
+
+## Later Expansion
+
+Later GitHub phases may add:
+
+- Inline diff comments and thread resolution
+- PR metadata enrichment such as labels, assignees, milestones, and linked issues
+- Merge and queue actions
+- CI control actions such as rerun/retry
+- Issue-centric workflows
+- Repo maintenance/admin workflows
+- Multi-repo inbox and batch review surfaces
+
+These should remain separate expansion decisions, not implicit additions to the initial milestone.
+
+## Sequencing Guidance
+
+Implementation should land in this order:
+
+1. Shared PR/review read models
+2. Review decision submission
+3. PR metadata update and draft/ready transitions
+4. Standalone comment creation
+5. Repo-context handoff affordances
+
+That order keeps the highest-value workflows intact while forcing a shared read layer before write surfaces multiply.
+
+## Product Boundary Rules
+
+- Every new GitHub action must map to one of the workflow classes above or be deferred.
+- If an action does not complete a clear user outcome, it is not first-class.
+- Repo actions stay subordinate to PR/review workflows unless a separate milestone expands them.
+- Initial support favors summary-level actions over fine-grained GitHub UI parity.
+
+## Acceptance Mapping
+
+### The initial GitHub capability set is explicit and bounded
+
+Yes. The initial set is limited to review intake/decision, PR updates, PR comments, and PR-adjacent repo handoff actions.
+
+### Each workflow has a clear user outcome
+
+Yes. Each workflow class above includes a single primary outcome and explicit success criteria.
+
+### The scope is concrete enough to drive implementation sequencing
+
+Yes. The workflow set is prioritized, split into initial vs later, and ordered for phased implementation.
diff --git a/docs/plans/2026-03-13-github-first-class-workflows-plan.md b/docs/plans/2026-03-13-github-first-class-workflows-plan.md
new file mode 100644
index 000000000..18b337dd1
--- /dev/null
+++ b/docs/plans/2026-03-13-github-first-class-workflows-plan.md
@@ -0,0 +1,299 @@
+# GitHub First-Class Workflows Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Implement the initial first-class GitHub workflow set for reviews, PR updates, comments, and PR-adjacent repo actions in a phased, testable way.
+
+**Architecture:** Build a shared GitHub PR/review domain layer first, then layer workflow-specific command/UI entry points on top. Keep write operations narrowly aligned to the defined workflow classes so the product surface stays bounded.
+
+**Tech Stack:** Bun, TypeScript, Hack CLI extension framework, Bun test, markdown docs
+
+---
+
+### Task 1: Document the product boundary in public docs
+
+**Files:**
+
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+- Test: `docs/plans/2026-03-13-github-first-class-workflows-design.md`
+
+**Step 1: Write the failing documentation expectation**
+
+Add a short checklist to the task branch notes describing the public-doc gap:
+
+- GitHub docs only describe auth/profile management plus `pr-upsert`
+- There is no explicit workflow taxonomy for reviews, comments, or repo handoff
+
+**Step 2: Verify the gap exists**
+
+Run: `grep -n "GitHub extension" -n docs/extensions.md && grep -n "review" docs/extensions.md` Expected: GitHub auth/pr-upsert docs exist, but workflow taxonomy is missing or incomplete.
+
+**Step 3: Add minimal public-facing scope language**
+
+Document:
+
+- supported initial workflow classes
+- explicit non-goals for the first milestone
+- pointer from command docs to the workflow model
+
+**Step 4: Verify the docs render cleanly**
+
+Run: `git diff --check` Expected: no whitespace or patch-format errors.
+
+**Step 5: Commit**
+
+```bash
+git add docs/extensions.md docs/cli.md docs/plans/2026-03-13-github-first-class-workflows-design.md
+git commit -m "docs: define first-class github workflow scope"
+```
+
+### Task 2: Add shared PR/review read primitives
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Test: `tests/github-client.test.ts`
+- Test: `tests/github-commands.test.ts`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+
+- fetching a PR summary by repo + number or branch
+- listing relevant PRs for a repo/user context
+- normalizing review/check/thread summary payloads
+
+**Step 2: Run targeted tests to verify failure**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: FAIL because review/summary read APIs do not exist yet.
+
+**Step 3: Implement the minimal shared read layer**
+
+Add client helpers and command plumbing for:
+
+- PR summary fetch
+- relevant PR listing
+- review/check/thread summary normalization
+
+**Step 4: Re-run tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: PASS for the new read-path coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts tests/github-client.test.ts tests/github-commands.test.ts
+git commit -m "feat(github): add shared pr review read primitives"
+```
+
+### Task 3: Implement review decision submission
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Test: `tests/github-client.test.ts`
+- Test: `tests/github-commands.test.ts`
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+
+- `approve`, `comment`, and `request_changes` review submission
+- required summary body validation
+- stable success payload formatting
+
+**Step 2: Run targeted tests to verify failure**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: FAIL because review submission endpoints and command parsing are missing.
+
+**Step 3: Implement the minimal review submission flow**
+
+Add:
+
+- client call for GitHub review submission
+- command parsing and output formatting
+- docs for the new supported review workflow
+
+**Step 4: Re-run tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: PASS for review submission coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts tests/github-client.test.ts tests/github-commands.test.ts docs/extensions.md docs/cli.md
+git commit -m "feat(github): add review decision workflow"
+```
+
+### Task 4: Expand PR update flow beyond upsert
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Test: `tests/github-client.test.ts`
+- Test: `tests/github-commands.test.ts`
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+
+- PR metadata read-before-write behavior
+- title/body/base updates
+- draft -> ready and ready -> draft transitions
+- optional comment attach-on-update behavior
+
+**Step 2: Run targeted tests to verify failure**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: FAIL because the state-transition surface is incomplete.
+
+**Step 3: Implement the minimal PR update workflow**
+
+Extend the current `pr-upsert` path or split it into clearer commands, but keep support limited to:
+
+- create/update
+- draft/ready transitions
+- optional top-level comment
+
+**Step 4: Re-run tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: PASS for the expanded PR update coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts tests/github-client.test.ts tests/github-commands.test.ts docs/extensions.md docs/cli.md
+git commit -m "feat(github): expand pr update workflow"
+```
+
+### Task 5: Add standalone PR comment workflow
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Test: `tests/github-client.test.ts`
+- Test: `tests/github-commands.test.ts`
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+
+- creating a top-level PR comment
+- validating repo/pr target resolution
+- emitting durable remote identifiers in output
+
+**Step 2: Run targeted tests to verify failure**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: FAIL because standalone comment workflow is not yet exposed.
+
+**Step 3: Implement the minimal standalone comment flow**
+
+Support only top-level PR comments in this task. Do not add full inline diff-thread comment support.
+
+**Step 4: Re-run tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts` Expected: PASS for standalone comment coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts tests/github-client.test.ts tests/github-commands.test.ts docs/extensions.md docs/cli.md
+git commit -m "feat(github): add standalone pr comments"
+```
+
+### Task 6: Add PR-adjacent repo handoff actions
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Modify: `src/lib/project.ts`
+- Test: `tests/github-client.test.ts`
+- Test: `tests/github-commands.test.ts`
+- Test: `tests/project-execution-routing.test.ts`
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+
+- resolving PR head/base refs from GitHub state
+- mapping a PR to a local branch/worktree handoff target
+- presenting changed-file and checks summary as read-only repo context
+
+**Step 2: Run targeted tests to verify failure**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts tests/project-execution-routing.test.ts` Expected: FAIL because PR-to-local handoff actions are not implemented.
+
+**Step 3: Implement the minimal repo handoff flow**
+
+Support:
+
+- PR/ref resolution
+- local branch/worktree handoff target generation
+- PR URL and changed-file/check summary output
+
+Do not add merge, rebase, rerun, or admin actions.
+
+**Step 4: Re-run tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts tests/project-execution-routing.test.ts` Expected: PASS for the handoff coverage.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts src/lib/project.ts tests/github-client.test.ts tests/github-commands.test.ts tests/project-execution-routing.test.ts docs/extensions.md docs/cli.md
+git commit -m "feat(github): add pr repo handoff actions"
+```
+
+### Task 7: Run full quality gates for the GitHub workflow milestone
+
+**Files:**
+
+- Modify: `docs/extensions.md`
+- Modify: `docs/cli.md`
+- Modify: `src/control-plane/extensions/github/client.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Modify: `tests/github-client.test.ts`
+- Modify: `tests/github-commands.test.ts`
+
+**Step 1: Run formatter/linter**
+
+Run: `bun x ultracite fix` Expected: formatting and autofix pass cleanly.
+
+**Step 2: Run focused tests**
+
+Run: `bun test tests/github-client.test.ts tests/github-commands.test.ts tests/project-execution-routing.test.ts` Expected: PASS.
+
+**Step 3: Run broader repository validation**
+
+Run: `bun x ultracite check` Expected: PASS with no new lint or formatting regressions.
+
+**Step 4: Review scope against the design doc**
+
+Verify each implemented action still maps to:
+
+- review intake/decision
+- PR update
+- PR comments
+- PR-adjacent repo handoff
+
+Expected: no extra GitHub surface added beyond the design boundary.
+
+**Step 5: Commit**
+
+```bash
+git add docs/extensions.md docs/cli.md src/control-plane/extensions/github/client.ts src/control-plane/extensions/github/commands.ts tests/github-client.test.ts tests/github-commands.test.ts tests/project-execution-routing.test.ts
+git commit -m "feat(github): deliver first-class workflow milestone"
+```

From d9f697367233be989acf45693548904061156eed Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 18:46:11 +0000
Subject: [PATCH 089/134] docs: format github workflow scope docs

---
 docs/cli.md        | 832 ++++++++++++++++++++++-----------------------
 docs/extensions.md | 215 ++++++------
 2 files changed, 519 insertions(+), 528 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 83ab9a58b..bf561b525 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,7 +1,6 @@
 # CLI Reference
 
-This reference mirrors the CLI spec in `src/cli/spec.ts`.
-Run `hack help` or `hack help <command>` for interactive help.
+This reference mirrors the CLI spec in `src/cli/spec.ts`. Run `hack help` or `hack help <command>` for interactive help.
 
 If you are new to Hack, scan the CLI in this order:
 
@@ -70,17 +69,17 @@ Usage: `hack global <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `install` | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy |
-| `up` | Start global infra containers |
-| `down` | Stop global infra containers |
-| `status` | Show status for global infra (containers + networks) |
-| `logs` | Tail global infra logs (caddy|grafana|loki|alloy) |
-| `ca` | Export Caddy Local CA cert (print path or PEM) |
-| `cert` | Generate local TLS certs via mkcert (for non-Caddy services) |
-| `trust` | Trust Caddy Local CA (macOS) so https://*.hack is trusted |
-| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards) |
+| Subcommand   | Summary                                                      |
+| ------------ | ------------------------------------------------------------ | ------- | ---- | ------ |
+| `install`    | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy     |
+| `up`         | Start global infra containers                                |
+| `down`       | Stop global infra containers                                 |
+| `status`     | Show status for global infra (containers + networks)         |
+| `logs`       | Tail global infra logs (caddy                                | grafana | loki | alloy) |
+| `ca`         | Export Caddy Local CA cert (print path or PEM)               |
+| `cert`       | Generate local TLS certs via mkcert (for non-Caddy services) |
+| `trust`      | Trust Caddy Local CA (macOS) so https://\*.hack is trusted   |
+| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards)          |
 
 #### hack global logs
 
@@ -88,18 +87,18 @@ Usage: `hack global logs [service] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | no | Filter to one global service (caddy, grafana, loki, alloy) |
+| Name      | Type   | Required | Description                                                |
+| --------- | ------ | -------- | ---------------------------------------------------------- |
+| `service` | string | no       | Filter to one global service (caddy, grafana, loki, alloy) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-f`, `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--tail <n>` | number | 200 | Tail last N log lines |
-| `--pretty` | boolean | false | Pretty-print logs (best-effort JSON parsing + formatting) |
+| Flag             | Type    | Default | Description                                               |
+| ---------------- | ------- | ------- | --------------------------------------------------------- |
+| `-f`, `--follow` | boolean | true    | Follow logs (default)                                     |
+| `--no-follow`    | boolean | false   | Print logs and exit                                       |
+| `--tail <n>`     | number  | 200     | Tail last N log lines                                     |
+| `--pretty`       | boolean | false   | Pretty-print logs (best-effort JSON parsing + formatting) |
 
 #### hack global ca
 
@@ -107,9 +106,9 @@ Usage: `hack global ca [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--print` | boolean | false | Print the CA cert PEM to stdout (instead of printing its path) |
+| Flag      | Type    | Default | Description                                                    |
+| --------- | ------- | ------- | -------------------------------------------------------------- |
+| `--print` | boolean | false   | Print the CA cert PEM to stdout (instead of printing its path) |
 
 #### hack global cert
 
@@ -117,16 +116,16 @@ Usage: `hack global cert <hosts...> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `hosts` | string[] | yes | One or more hostnames to generate certs for |
+| Name    | Type     | Required | Description                                 |
+| ------- | -------- | -------- | ------------------------------------------- |
+| `hosts` | string[] | yes      | One or more hostnames to generate certs for |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--install` | boolean | false | Run mkcert -install before generating certs |
-| `--out <dir>` | string | `~/.hack/certs` | Directory for generated cert/key |
+| Flag          | Type    | Default         | Description                                 |
+| ------------- | ------- | --------------- | ------------------------------------------- |
+| `--install`   | boolean | false           | Run mkcert -install before generating certs |
+| `--out <dir>` | string  | `~/.hack/certs` | Directory for generated cert/key            |
 
 ### hack projects
 
@@ -151,9 +150,9 @@ Usage: `hack projects prune [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
+| Flag               | Type    | Default | Description                                   |
+| ------------------ | ------- | ------- | --------------------------------------------- |
+| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
 
 ### hack status
 
@@ -161,12 +160,12 @@ Usage: `hack status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Filter to a registered project name |
-| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
-| `--all` | boolean | false | Include unregistered docker compose projects |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag               | Type    | Default | Description                                   |
+| ------------------ | ------- | ------- | --------------------------------------------- |
+| `--project <name>` | string  | -       | Filter to a registered project name           |
+| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
+| `--all`            | boolean | false   | Include unregistered docker compose projects  |
+| `--json`           | boolean | false   | Output JSON (machine-readable)                |
 
 ### hack usage
 
@@ -209,13 +208,13 @@ Usage: `hack up [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `-d`, `--detach` | boolean | false | Run in background (docker compose up -d) |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack down
 
@@ -224,12 +223,12 @@ Usage: `hack down [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack restart
 
@@ -238,12 +237,12 @@ Usage: `hack restart [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack ps
 
@@ -265,9 +264,9 @@ Usage: `hack logs [service] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | no | Filter logs by service (shortcut for `--services`) |
+| Name      | Type   | Required | Description                                        |
+| --------- | ------ | -------- | -------------------------------------------------- |
+| `service` | string | no       | Filter logs by service (shortcut for `--services`) |
 
 Options:
 
@@ -301,10 +300,10 @@ Usage: `hack run <service> [-- <cmd...>] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | yes | Compose service name |
-| `cmd` | string[] | no | Command to run (defaults to service entrypoint) |
+| Name      | Type     | Required | Description                                     |
+| --------- | -------- | -------- | ----------------------------------------------- |
+| `service` | string   | yes      | Compose service name                            |
+| `cmd`     | string[] | no       | Command to run (defaults to service entrypoint) |
 
 Options:
 
@@ -322,18 +321,18 @@ Usage: `hack open [target] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `target` | string | no | `www` (default), `logs`, a subdomain, or a full URL |
+| Name     | Type   | Required | Description                                         |
+| -------- | ------ | -------- | --------------------------------------------------- |
+| `target` | string | no       | `www` (default), `logs`, a subdomain, or a full URL |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--branch <name>` | string | - | Run against a branch-specific instance |
-| `--json` | boolean | false | Output JSON with `{ "url": "..." }` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--branch <name>`    | string  | -       | Run against a branch-specific instance         |
+| `--json`             | boolean | false   | Output JSON with `{ "url": "..." }`            |
 
 Notes:
 
@@ -348,10 +347,10 @@ Usage: `hack tui [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 Notes:
 
@@ -363,12 +362,12 @@ Usage: `hack branch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `add` | Register a branch alias for this project |
-| `list` | List registered branch aliases |
-| `remove` | Remove a branch alias |
-| `open` | Open the branch host in a browser |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `add`      | Register a branch alias for this project |
+| `list`     | List registered branch aliases           |
+| `remove`   | Remove a branch alias                    |
+| `open`     | Open the branch host in a browser        |
 
 #### hack branch add
 
@@ -376,17 +375,17 @@ Usage: `hack branch add <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--note <text>` | string | - | Optional note for the branch entry |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
+| `--note <text>`      | string | -       | Optional note for the branch entry             |
 
 #### hack branch list
 
@@ -394,10 +393,10 @@ Usage: `hack branch list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack branch remove
 
@@ -405,16 +404,16 @@ Usage: `hack branch remove <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack branch open
 
@@ -422,16 +421,16 @@ Usage: `hack branch open <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 ### hack config
 
@@ -439,10 +438,10 @@ Usage: `hack config <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `get` | Read a value from hack.config.json |
-| `set` | Update a value in hack.config.json |
+| Subcommand | Summary                            |
+| ---------- | ---------------------------------- |
+| `get`      | Read a value from hack.config.json |
+| `set`      | Update a value in hack.config.json |
 
 #### hack config get
 
@@ -450,17 +449,17 @@ Usage: `hack config get <key> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
+| Name  | Type   | Required | Description                             |
+| ----- | ------ | -------- | --------------------------------------- |
+| `key` | string | yes      | Dot path (e.g. `logs.snapshot_backend`) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--global` | boolean | false | Read global `~/.hack/hack.config.json` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--global`           | boolean | false   | Read global `~/.hack/hack.config.json`         |
 
 #### hack config set
 
@@ -468,18 +467,18 @@ Usage: `hack config set <key> <value> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
-| `value` | string | yes | JSON value or raw string (parsed as JSON when valid) |
+| Name    | Type   | Required | Description                                          |
+| ------- | ------ | -------- | ---------------------------------------------------- |
+| `key`   | string | yes      | Dot path (e.g. `logs.snapshot_backend`)              |
+| `value` | string | yes      | JSON value or raw string (parsed as JSON when valid) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--global` | boolean | false | Write global `~/.hack/hack.config.json` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--global`           | boolean | false   | Write global `~/.hack/hack.config.json`        |
 
 ## Collaboration & integrations
 
@@ -547,12 +546,12 @@ Usage: `hack env <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List env contract vars and resolution state |
-| `set` | Set an env value (.hack/.env or secret backend) |
-| `unset` | Unset an env value (.hack/.env and secret backend) |
-| `backend` | Manage env/secret backend strategy |
+| Subcommand | Summary                                            |
+| ---------- | -------------------------------------------------- |
+| `list`     | List env contract vars and resolution state        |
+| `set`      | Set an env value (.hack/.env or secret backend)    |
+| `unset`    | Unset an env value (.hack/.env and secret backend) |
+| `backend`  | Manage env/secret backend strategy                 |
 
 #### hack env list
 
@@ -560,12 +559,12 @@ Usage: `hack env list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--json` | boolean | false | Output JSON (machine-readable) |
-| `--show-secrets` | boolean | false | Print secret values (secret backend) in plaintext |
+| Flag                 | Type    | Default | Description                                       |
+| -------------------- | ------- | ------- | ------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)    |
+| `--project <name>`   | string  | -       | Target a registered project by name               |
+| `--json`             | boolean | false   | Output JSON (machine-readable)                    |
+| `--show-secrets`     | boolean | false   | Print secret values (secret backend) in plaintext |
 
 #### hack env set
 
@@ -587,10 +586,10 @@ Usage: `hack env unset [key] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack env backend
 
@@ -598,10 +597,10 @@ Usage: `hack env backend <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `status` | Show configured env/secret backend strategy |
-| `use` | Select env/secret backend strategy |
+| Subcommand | Summary                                     |
+| ---------- | ------------------------------------------- |
+| `status`   | Show configured env/secret backend strategy |
+| `use`      | Select env/secret backend strategy          |
 
 #### hack env backend status
 
@@ -609,9 +608,9 @@ Usage: `hack env backend status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag     | Type    | Default | Description                    |
+| -------- | ------- | ------- | ------------------------------ |
+| `--json` | boolean | false   | Output JSON (machine-readable) |
 
 #### hack env backend use
 
@@ -620,8 +619,8 @@ Usage: `hack env backend use <keychain|encrypted_file|cloud> [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--provider <aws|gcp|azure|vault>` | string | - | Cloud provider when backend is `cloud` |
+| --- | --- | --- | --- | --- | --- | --- |
+| `--provider <aws | gcp | azure | vault>` | string | - | Cloud provider when backend is `cloud` |
 | `--store-path <path>` | string | - | Encrypted file path when backend is `encrypted_file` |
 | `--secret-project <id>` | string | - | Optional cloud account/project identifier |
 | `--secret-prefix <prefix>` | string | - | Optional cloud secret name prefix |
@@ -635,16 +634,16 @@ With no subcommand, opens an interactive picker of active sessions and available
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List active sessions |
-| `start` | Start or attach to a session for a project |
-| `stop` | Stop (kill) a session |
-| `attach` | Attach to an existing session |
-| `exec` | Execute a command in a session |
-| `panes` | List panes in a tmux session |
-| `capture` | Capture recent output from a tmux session |
-| `tail` | Tail output from a tmux session |
+| Subcommand | Summary                                    |
+| ---------- | ------------------------------------------ |
+| `list`     | List active sessions                       |
+| `start`    | Start or attach to a session for a project |
+| `stop`     | Stop (kill) a session                      |
+| `attach`   | Attach to an existing session              |
+| `exec`     | Execute a command in a session             |
+| `panes`    | List panes in a tmux session               |
+| `capture`  | Capture recent output from a tmux session  |
+| `tail`     | Tail output from a tmux session            |
 
 #### hack session start
 
@@ -652,11 +651,11 @@ Usage: `hack session start [project] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--up` | boolean | false | Run hack up -d before attaching |
-| `--new` | boolean | false | Force create new session even if one exists |
-| `--name <suffix>` | string | - | Custom suffix for new session (e.g., agent-1) |
+| Flag              | Type    | Default | Description                                   |
+| ----------------- | ------- | ------- | --------------------------------------------- |
+| `--up`            | boolean | false   | Run hack up -d before attaching               |
+| `--new`           | boolean | false   | Force create new session even if one exists   |
+| `--name <suffix>` | string  | -       | Custom suffix for new session (e.g., agent-1) |
 
 #### hack session panes
 
@@ -664,10 +663,10 @@ Usage: `hack session panes <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag       | Type    | Default | Description                          |
+| ---------- | ------- | ------- | ------------------------------------ |
+| `--json`   | boolean | false   | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false   | Output human-friendly text           |
 
 #### hack session capture
 
@@ -675,12 +674,12 @@ Usage: `hack session capture <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--target <target>` | string | - | Tmux pane target (default: active pane) |
-| `--lines <n>` | number | 200 | Number of lines to capture |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag                | Type    | Default | Description                             |
+| ------------------- | ------- | ------- | --------------------------------------- |
+| `--target <target>` | string  | -       | Tmux pane target (default: active pane) |
+| `--lines <n>`       | number  | 200     | Number of lines to capture              |
+| `--json`            | boolean | false   | Output NDJSON stream (start/log/end)    |
+| `--pretty`          | boolean | false   | Output human-friendly text              |
 
 #### hack session tail
 
@@ -688,14 +687,14 @@ Usage: `hack session tail <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--target <target>` | string | - | Tmux pane target (default: active pane) |
-| `--lines <n>` | number | 200 | Number of lines to capture |
-| `--interval-ms <ms>` | number | 500 | Polling interval in milliseconds |
-| `--max-ms <ms>` | number | 5000 | Stop tailing after N milliseconds |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag                 | Type    | Default | Description                             |
+| -------------------- | ------- | ------- | --------------------------------------- |
+| `--target <target>`  | string  | -       | Tmux pane target (default: active pane) |
+| `--lines <n>`        | number  | 200     | Number of lines to capture              |
+| `--interval-ms <ms>` | number  | 500     | Polling interval in milliseconds        |
+| `--max-ms <ms>`      | number  | 5000    | Stop tailing after N milliseconds       |
+| `--json`             | boolean | false   | Output NDJSON stream (start/log/end)    |
+| `--pretty`           | boolean | false   | Output human-friendly text              |
 
 ### hack ssh
 
@@ -703,27 +702,25 @@ Usage: `hack ssh [session] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-H`, `--host <host>` | string | - | SSH host (hostname or IP) |
-| `-u`, `--user <user>` | string | - | SSH username |
-| `-t`, `--tailscale` | boolean | false | Use Tailscale SSH |
-| `-d`, `--direct` | boolean | false | Use direct SSH (requires --host) |
-| `-p`, `--port <port>` | string | - | SSH port for direct connection (default: 22) |
+| Flag                  | Type    | Default | Description                                  |
+| --------------------- | ------- | ------- | -------------------------------------------- |
+| `-H`, `--host <host>` | string  | -       | SSH host (hostname or IP)                    |
+| `-u`, `--user <user>` | string  | -       | SSH username                                 |
+| `-t`, `--tailscale`   | boolean | false   | Use Tailscale SSH                            |
+| `-d`, `--direct`      | boolean | false   | Use direct SSH (requires --host)             |
+| `-p`, `--port <port>` | string  | -       | SSH port for direct connection (default: 22) |
 
 ### hack tickets
 
 Usage: `hack tickets <args...>`
 
-`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`).
-Run `hack tickets` with no args to see available subcommands.
+`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`). Run `hack tickets` with no args to see available subcommands.
 
 ### hack linear
 
 Usage: `hack linear <args...>`
 
-`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`).
-Run `hack linear` with no args to see available subcommands.
+`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`). Run `hack linear` with no args to see available subcommands.
 
 ## Internal commands
 
@@ -733,8 +730,8 @@ Usage: `hack internal <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
+| Subcommand    | Summary                             |
+| ------------- | ----------------------------------- |
 | `extra-hosts` | Manage internal Compose extra_hosts |
 
 #### hack internal extra-hosts
@@ -743,17 +740,17 @@ Usage: `hack internal extra-hosts <subcommand> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <path>` | string | - | Start directory (defaults to cwd) |
+| Flag                  | Type   | Default | Description                       |
+| --------------------- | ------ | ------- | --------------------------------- |
+| `-p`, `--path <path>` | string | -       | Start directory (defaults to cwd) |
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `set` | Set an internal extra_hosts entry |
-| `unset` | Remove an internal extra_hosts entry |
-| `list` | List internal extra_hosts entries |
+| Subcommand | Summary                              |
+| ---------- | ------------------------------------ |
+| `set`      | Set an internal extra_hosts entry    |
+| `unset`    | Remove an internal extra_hosts entry |
+| `list`     | List internal extra_hosts entries    |
 
 #### hack internal extra-hosts set
 
@@ -775,11 +772,11 @@ Usage: `hack gateway <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `enable` | Enable the gateway and start hackd |
-| `setup` | Guided gateway setup (enable + token) |
-| `disable` | Disable the gateway (does not stop hackd) |
+| Subcommand | Summary                                   |
+| ---------- | ----------------------------------------- |
+| `enable`   | Enable the gateway and start hackd        |
+| `setup`    | Guided gateway setup (enable + token)     |
+| `disable`  | Disable the gateway (does not stop hackd) |
 
 #### hack gateway enable
 
@@ -787,10 +784,10 @@ Usage: `hack gateway enable [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack gateway setup
 
@@ -798,13 +795,13 @@ Usage: `hack gateway setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--qr` | boolean | true | Force QR output after setup (default) |
-| `--no-qr` | boolean | false | Skip QR output after setup |
-| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
+| Flag                 | Type    | Default | Description                                         |
+| -------------------- | ------- | ------- | --------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
+| `--project <name>`   | string  | -       | Target a registered project by name                 |
+| `--qr`               | boolean | true    | Force QR output after setup (default)               |
+| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
+| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
 
 #### hack gateway disable
 
@@ -812,10 +809,10 @@ Usage: `hack gateway disable [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 ### hack node
 
@@ -823,20 +820,20 @@ Usage: `hack node <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `init` | Initialize this host as a node and emit enrollment bundle |
-| `pair` | Pair node with one-command or expiring verification-code flow |
-| `ssh` | Manage SSH bootstrap for node pairing and remote runs |
-| `add` | Add a node from an enrollment bundle |
-| `list` | List registered nodes |
-| `status` | Probe node health and report live status |
-| `use` | Set default node |
-| `remove` | Remove node registration |
-| `workspace` | Inspect and repair node workspace map entries |
-| `routes` | Inspect and repair controller-side remote route bridge |
-| `provider` | Manage provider-specific node bootstrap workflows |
-| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints |
+| Subcommand     | Summary                                                       |
+| -------------- | ------------------------------------------------------------- |
+| `init`         | Initialize this host as a node and emit enrollment bundle     |
+| `pair`         | Pair node with one-command or expiring verification-code flow |
+| `ssh`          | Manage SSH bootstrap for node pairing and remote runs         |
+| `add`          | Add a node from an enrollment bundle                          |
+| `list`         | List registered nodes                                         |
+| `status`       | Probe node health and report live status                      |
+| `use`          | Set default node                                              |
+| `remove`       | Remove node registration                                      |
+| `workspace`    | Inspect and repair node workspace map entries                 |
+| `routes`       | Inspect and repair controller-side remote route bridge        |
+| `provider`     | Manage provider-specific node bootstrap workflows             |
+| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints    |
 
 Examples:
 
@@ -941,12 +938,12 @@ Usage: `hack node workspace <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List node-local workspace map entries |
-| `resolve` | Resolve a map entry by controller project selector |
-| `attach` | Attach an existing local workspace to project selector |
-| `remove` | Remove a map entry by project selector |
+| Subcommand | Summary                                                |
+| ---------- | ------------------------------------------------------ |
+| `list`     | List node-local workspace map entries                  |
+| `resolve`  | Resolve a map entry by controller project selector     |
+| `attach`   | Attach an existing local workspace to project selector |
+| `remove`   | Remove a map entry by project selector                 |
 
 Examples:
 
@@ -963,10 +960,10 @@ Usage: `hack node routes <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `status` | Show controller-side remote route bridge state |
-| `repair` | Re-render and re-apply persisted route bridge stack |
+| Subcommand | Summary                                             |
+| ---------- | --------------------------------------------------- |
+| `status`   | Show controller-side remote route bridge state      |
+| `repair`   | Re-render and re-apply persisted route bridge stack |
 
 Examples:
 
@@ -982,11 +979,11 @@ Usage: `hack dispatch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `run` | Dispatch a command to a node workspace |
-| `status` | Show dispatched run status |
-| `logs` | Show or follow persisted/remote run logs |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `run`      | Dispatch a command to a node workspace   |
+| `status`   | Show dispatched run status               |
+| `logs`     | Show or follow persisted/remote run logs |
 
 #### hack dispatch run
 
@@ -995,15 +992,15 @@ Usage: `hack dispatch run --project <name|id> [options] -- <command...>`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name|id>` | string | - | Project name or id |
-| `--node <id|default|auto>` | string | auto | Target node id, or use default/auto |
+| --- | --- | --- | --- | --- | --- | --- |
+| `--project <name | id>` | string | - | Project name or id |
+| `--node <id | default | auto>` | string | auto | Target node id, or use default/auto |
 | `--provider <provider>` | string | - | Provider route override used when resolving profile/bootstrap intent |
 | `--profile <profile-id>` | string | - | Provider profile route override |
 | `--bootstrap-if-needed` | boolean | false | Allow guarded provider bootstrap handoff when no reachable node is found |
 | `--branch <branch>` | string | current | Target branch on selected node |
 | `--ticket <ticket-id>` | string | - | Ticket id to associate with run metadata |
-| `--runner <generic|codex|claude|cursor>` | string | `generic` | Runner identity for policy and audit |
+| `--runner <generic | codex | claude | cursor>` | string | `generic` | Runner identity for policy and audit |
 | `--approve` | boolean | false | Approve high/critical risk commands non-interactively |
 | `--pr` | boolean | false | Push branch + create/update GitHub PR on successful run |
 | `--pr-base <branch>` | string | `main` | Base branch used with `--pr` |
@@ -1050,12 +1047,12 @@ If you run `hack remote` with no subcommand, it prints status and offers to run
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `setup` | Run the guided gateway setup |
-| `status` | Show remote/gateway status |
-| `monitor` | Open a remote status TUI |
-| `qr` | Print a QR payload for remote access |
+| Subcommand | Summary                              |
+| ---------- | ------------------------------------ |
+| `setup`    | Run the guided gateway setup         |
+| `status`   | Show remote/gateway status           |
+| `monitor`  | Open a remote status TUI             |
+| `qr`       | Print a QR payload for remote access |
 
 #### hack remote setup
 
@@ -1063,13 +1060,13 @@ Usage: `hack remote setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--qr` | boolean | true | Force QR output after setup (default) |
-| `--no-qr` | boolean | false | Skip QR output after setup |
-| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
+| Flag                 | Type    | Default | Description                                         |
+| -------------------- | ------- | ------- | --------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
+| `--project <name>`   | string  | -       | Target a registered project by name                 |
+| `--qr`               | boolean | true    | Force QR output after setup (default)               |
+| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
+| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
 
 #### hack remote status
 
@@ -1077,10 +1074,10 @@ Usage: `hack remote status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack remote monitor
 
@@ -1088,10 +1085,10 @@ Usage: `hack remote monitor [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack remote qr
 
@@ -1119,9 +1116,9 @@ Usage: `hack x <namespace> <command> [args...]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `args` | string[] | no | Extension command args (passed through) |
+| Name   | Type     | Required | Description                             |
+| ------ | -------- | -------- | --------------------------------------- |
+| `args` | string[] | no       | Extension command args (passed through) |
 
 Notes:
 
@@ -1136,15 +1133,15 @@ Usage: `hack setup <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `cursor` | Install Cursor rules for hack CLI usage |
-| `claude` | Install Claude Code hooks for hack CLI usage |
-| `codex` | Install Codex skill for hack CLI usage |
-| `tickets` | Install Codex skill for hack tickets usage |
-| `agents` | Install AGENTS.md / CLAUDE.md snippets |
-| `sync` | Refresh agent docs, skills, and MCP configs |
-| `mcp` | Install MCP configs for hack CLI usage (no-shell only) |
+| Subcommand | Summary                                                |
+| ---------- | ------------------------------------------------------ |
+| `cursor`   | Install Cursor rules for hack CLI usage                |
+| `claude`   | Install Claude Code hooks for hack CLI usage           |
+| `codex`    | Install Codex skill for hack CLI usage                 |
+| `tickets`  | Install Codex skill for hack tickets usage             |
+| `agents`   | Install AGENTS.md / CLAUDE.md snippets                 |
+| `sync`     | Refresh agent docs, skills, and MCP configs            |
+| `mcp`      | Install MCP configs for hack CLI usage (no-shell only) |
 
 #### hack setup cursor
 
@@ -1152,12 +1149,12 @@ Usage: `hack setup cursor [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup claude
 
@@ -1165,12 +1162,12 @@ Usage: `hack setup claude [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup codex
 
@@ -1178,12 +1175,12 @@ Usage: `hack setup codex [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup agents
 
@@ -1191,14 +1188,14 @@ Usage: `hack setup agents [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported docs |
-| `--agents-md` | boolean | false | Target AGENTS.md |
-| `--claude-md` | boolean | false | Target CLAUDE.md |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean | false   | Target all supported docs                      |
+| `--agents-md`        | boolean | false   | Target AGENTS.md                               |
+| `--claude-md`        | boolean | false   | Target CLAUDE.md                               |
+| `--check`            | boolean | false   | Check whether integration is installed         |
+| `--remove`           | boolean | false   | Remove integration files/config                |
 
 #### hack setup sync
 
@@ -1206,13 +1203,13 @@ Usage: `hack setup sync [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Target global (user) scope only |
-| `--all-scopes` | boolean | false | Target both project and global (user) scopes |
-| `--check` | boolean | false | Check whether integrations are installed |
-| `--remove` | boolean | false | Remove generated integration files/config |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--global`           | boolean | false   | Target global (user) scope only                |
+| `--all-scopes`       | boolean | false   | Target both project and global (user) scopes   |
+| `--check`            | boolean | false   | Check whether integrations are installed       |
+| `--remove`           | boolean | false   | Remove generated integration files/config      |
 
 Automatic guardrail:
 
@@ -1225,16 +1222,16 @@ Usage: `hack setup mcp [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor integration |
-| `--claude` | boolean | false | Target Claude integration |
-| `--codex` | boolean | false | Target Codex integration |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--all`              | boolean | false   | Target all supported clients                     |
+| `--cursor`           | boolean | false   | Target Cursor integration                        |
+| `--claude`           | boolean | false   | Target Claude integration                        |
+| `--codex`            | boolean | false   | Target Codex integration                         |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 ### hack agent
 
@@ -1242,11 +1239,11 @@ Usage: `hack agent <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `prime` | Print agent primer text |
+| Subcommand | Summary                         |
+| ---------- | ------------------------------- |
+| `prime`    | Print agent primer text         |
 | `patterns` | Print agent init patterns guide |
-| `init` | Print agent init prompt |
+| `init`     | Print agent init prompt         |
 
 #### hack agent init
 
@@ -1254,10 +1251,10 @@ Usage: `hack agent init [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `-c`, `--client <cursor|claude|codex|print>` | string | - | Open init prompt in an agent client (or print) |
+| Flag                    | Type   | Default | Description                                    |
+| ----------------------- | ------ | ------- | ---------------------------------------------- | ------ | --- | ---------------------------------------------- |
+| `-p`, `--path <dir>`    | string | -       | Run against a repo path (overrides cwd search) |
+| `-c`, `--client <cursor | claude | codex   | print>`                                        | string | -   | Open init prompt in an agent client (or print) |
 
 ### hack mcp
 
@@ -1265,11 +1262,11 @@ Usage: `hack mcp <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `serve` | Run the MCP server over stdio |
-| `install` | Install MCP config for supported clients |
-| `print` | Print MCP config snippets |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `serve`    | Run the MCP server over stdio            |
+| `install`  | Install MCP config for supported clients |
+| `print`    | Print MCP config snippets                |
 
 #### hack mcp install
 
@@ -1277,17 +1274,17 @@ Usage: `hack mcp install [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <user|project>` | string | `user` | Write MCP config to user or project scope |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor MCP config |
-| `--claude` | boolean | false | Target Claude CLI MCP config |
-| `--codex` | boolean | false | Target Codex MCP config |
-| `--docs` | boolean | false | Update AGENTS.md and CLAUDE.md with hack usage |
-| `--agents-md` | boolean | false | Update AGENTS.md with hack usage |
-| `--claude-md` | boolean | false | Update CLAUDE.md with hack usage |
+| Flag                 | Type      | Default | Description                                    |
+| -------------------- | --------- | ------- | ---------------------------------------------- | ----------------------------------------- |
+| `--scope <user       | project>` | string  | `user`                                         | Write MCP config to user or project scope |
+| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean   | false   | Target all supported clients                   |
+| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
+| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
+| `--codex`            | boolean   | false   | Target Codex MCP config                        |
+| `--docs`             | boolean   | false   | Update AGENTS.md and CLAUDE.md with hack usage |
+| `--agents-md`        | boolean   | false   | Update AGENTS.md with hack usage               |
+| `--claude-md`        | boolean   | false   | Update CLAUDE.md with hack usage               |
 
 Notes:
 
@@ -1300,14 +1297,14 @@ Usage: `hack mcp print [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <user|project>` | string | `user` | Print MCP config for user or project scope |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor MCP config |
-| `--claude` | boolean | false | Target Claude CLI MCP config |
-| `--codex` | boolean | false | Target Codex MCP config |
+| Flag                 | Type      | Default | Description                                    |
+| -------------------- | --------- | ------- | ---------------------------------------------- | ------------------------------------------ |
+| `--scope <user       | project>` | string  | `user`                                         | Print MCP config for user or project scope |
+| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean   | false   | Target all supported clients                   |
+| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
+| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
+| `--codex`            | boolean   | false   | Target Codex MCP config                        |
 
 ## Diagnostics commands
 
@@ -1346,17 +1343,17 @@ Usage: `hack daemon <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `start` | Start hackd (local daemon) |
-| `stop` | Stop hackd |
-| `restart` | Restart hackd |
-| `status` | Show hackd status |
-| `metrics` | Show hackd metrics |
-| `logs` | Show hackd logs |
-| `clear` | Clear stale hackd pid/socket files |
-| `install` | Install hackd as a launchd service (macOS) |
-| `uninstall` | Uninstall hackd launchd service (macOS) |
+| Subcommand  | Summary                                    |
+| ----------- | ------------------------------------------ |
+| `start`     | Start hackd (local daemon)                 |
+| `stop`      | Stop hackd                                 |
+| `restart`   | Restart hackd                              |
+| `status`    | Show hackd status                          |
+| `metrics`   | Show hackd metrics                         |
+| `logs`      | Show hackd logs                            |
+| `clear`     | Clear stale hackd pid/socket files         |
+| `install`   | Install hackd as a launchd service (macOS) |
+| `uninstall` | Uninstall hackd launchd service (macOS)    |
 
 Autostart + self-heal behavior:
 
@@ -1373,9 +1370,9 @@ Usage: `hack daemon start [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--foreground` | boolean | false | Run hackd in the foreground (debug) |
+| Flag           | Type    | Default | Description                         |
+| -------------- | ------- | ------- | ----------------------------------- |
+| `--foreground` | boolean | false   | Run hackd in the foreground (debug) |
 
 #### hack daemon status
 
@@ -1383,9 +1380,9 @@ Usage: `hack daemon status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output JSON (machine-readable, includes launchd info on macOS) |
+| Flag     | Type    | Default | Description                                                    |
+| -------- | ------- | ------- | -------------------------------------------------------------- |
+| `--json` | boolean | false   | Output JSON (machine-readable, includes launchd info on macOS) |
 
 #### hack daemon logs
 
@@ -1393,35 +1390,32 @@ Usage: `hack daemon logs [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--tail <n>` | number | 200 | Tail last N log lines |
+| Flag         | Type   | Default | Description           |
+| ------------ | ------ | ------- | --------------------- |
+| `--tail <n>` | number | 200     | Tail last N log lines |
 
 #### hack daemon install
 
 Usage: `hack daemon install [options]`
 
-Installs hackd as a launchd service on macOS. The daemon will be managed by launchd
-and can optionally start automatically on login.
+Installs hackd as a launchd service on macOS. The daemon will be managed by launchd and can optionally start automatically on login.
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--run-at-load` | boolean | true | Start hackd automatically on login |
-| `--no-run-at-load` | boolean | - | Do not start hackd automatically on login |
-| `--gui-only` | boolean | true | Only run in GUI sessions (Aqua) |
-| `--no-gui-only` | boolean | - | Run in all session types (including SSH) |
+| Flag               | Type    | Default | Description                               |
+| ------------------ | ------- | ------- | ----------------------------------------- |
+| `--run-at-load`    | boolean | true    | Start hackd automatically on login        |
+| `--no-run-at-load` | boolean | -       | Do not start hackd automatically on login |
+| `--gui-only`       | boolean | true    | Only run in GUI sessions (Aqua)           |
+| `--no-gui-only`    | boolean | -       | Run in all session types (including SSH)  |
 
-The service uses the label `dance.hack.hackd` and writes its plist to
-`~/Library/LaunchAgents/dance.hack.hackd.plist`.
+The service uses the label `dance.hack.hackd` and writes its plist to `~/Library/LaunchAgents/dance.hack.hackd.plist`.
 
 #### hack daemon uninstall
 
 Usage: `hack daemon uninstall`
 
-Uninstalls the hackd launchd service on macOS. Removes the plist and unloads
-the service from launchd.
+Uninstalls the hackd launchd service on macOS. Removes the plist and unloads the service from launchd.
 
 ### hack log-pipe
 
@@ -1429,10 +1423,10 @@ Usage: `hack log-pipe [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--format <auto|docker-compose|plain>` | string | `auto` | How to parse incoming lines from stdin |
-| `--stream <stdout|stderr>` | string | `stdout` | Treat stdin as stdout or stderr |
+| Flag              | Type           | Default | Description |
+| ----------------- | -------------- | ------- | ----------- | ------------------------------- | -------------------------------------- |
+| `--format <auto   | docker-compose | plain>` | string      | `auto`                          | How to parse incoming lines from stdin |
+| `--stream <stdout | stderr>`       | string  | `stdout`    | Treat stdin as stdout or stderr |
 
 ### hack help
 
@@ -1440,9 +1434,9 @@ Usage: `hack help [path...]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `path` | string[] | no | Command path to show help for (e.g. `global logs`) |
+| Name   | Type     | Required | Description                                        |
+| ------ | -------- | -------- | -------------------------------------------------- |
+| `path` | string[] | no       | Command path to show help for (e.g. `global logs`) |
 
 ### hack update
 
@@ -1450,12 +1444,12 @@ Usage: `hack update [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--check` | boolean | false | Check for updates (do not install) |
-| `--yes` | boolean | false | Apply update without prompting |
-| `--tag <tag>` | string | - | Update to a specific release tag (e.g. v1.4.0) |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag          | Type    | Default | Description                                    |
+| ------------- | ------- | ------- | ---------------------------------------------- |
+| `--check`     | boolean | false   | Check for updates (do not install)             |
+| `--yes`       | boolean | false   | Apply update without prompting                 |
+| `--tag <tag>` | string  | -       | Update to a specific release tag (e.g. v1.4.0) |
+| `--json`      | boolean | false   | Output JSON (machine-readable)                 |
 
 ### hack version
 
@@ -1469,23 +1463,23 @@ Usage: `hack secrets <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `set` | Store a secret |
-| `get` | Print a secret (exit 1 if missing) |
-| `delete` | Delete a stored secret |
+| Subcommand | Summary                            |
+| ---------- | ---------------------------------- |
+| `set`      | Store a secret                     |
+| `get`      | Print a secret (exit 1 if missing) |
+| `delete`   | Delete a stored secret             |
 
 Options (all subcommands):
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| Flag                  | Type   | Default    | Description                       |
+| --------------------- | ------ | ---------- | --------------------------------- |
 | `--service <service>` | string | `hack-cli` | Override Bun.secrets service name |
 
 Arguments (set/get/delete):
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | no | Secret name (prompted if omitted) |
+| Name   | Type   | Required | Description                       |
+| ------ | ------ | -------- | --------------------------------- |
+| `name` | string | no       | Secret name (prompted if omitted) |
 
 ## Fun
 
@@ -1495,7 +1489,7 @@ Usage: `hack the planet [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--variant <cut|mash|cycle|random>` | string | `cycle` | Animation variant |
-| `--loop` | boolean | true | Loop until Ctrl+C |
+| Flag            | Type    | Default | Description       |
+| --------------- | ------- | ------- | ----------------- | ------ | ------- | ----------------- |
+| `--variant <cut | mash    | cycle   | random>`          | string | `cycle` | Animation variant |
+| `--loop`        | boolean | true    | Loop until Ctrl+C |
diff --git a/docs/extensions.md b/docs/extensions.md
index 0416ef7c5..de9cf86b7 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -13,8 +13,7 @@ If you just want remote access working, start here:
 hack remote setup
 ```
 
-The wizard enables the gateway for the current project, creates a token + QR, and can configure
-Cloudflare/Tailscale/SSH exposure in one flow.
+The wizard enables the gateway for the current project, creates a token + QR, and can configure Cloudflare/Tailscale/SSH exposure in one flow.
 
 ## Behavior
 
@@ -22,8 +21,7 @@ Cloudflare/Tailscale/SSH exposure in one flow.
 - Each extension provides a manifest + commands (`ExtensionDefinition`).
 - The CLI dispatches extension commands via `hack x <namespace> <command>`.
 - Global enablement lives in `~/.hack/hack.config.json` (`hack config set --global ...`).
-- Per-project overrides live in `.hack/hack.config.json` and typically win over global values
-  (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
+- Per-project overrides live in `.hack/hack.config.json` and typically win over global values (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
 - Built-in Gateway enablement is project-scoped: `controlPlane.gateway.enabled` opts a project into routing.
 
 ## Extension definition (API surface)
@@ -49,14 +47,14 @@ export type ExtensionCommand = {
 ```
 
 The `ExtensionCommandContext` includes:
+
 - `controlPlaneConfig` (parsed config)
 - `projectId` and `projectName` (when available)
 - `logger` and `cwd`
 
 ## Config + enablement
 
-Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by
-`src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
+Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by `src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
 
 Enable a global extension by id:
 
@@ -80,10 +78,10 @@ Shortcut for gateway (project-scoped):
 }
 ```
 
-Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config.
-Project overrides for these are ignored.
+Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config. Project overrides for these are ignored.
 
 CLI helpers:
+
 - `hack gateway enable` (sets both gateway + extension flags)
 - `hack gateway setup` (guided enable + optional writes + token creation + QR by default)
 - `hack config set --global 'controlPlane.extensions[\"dance.hack.gateway\"].enabled' true`
@@ -108,10 +106,10 @@ Use `hack x <namespace> help` to list commands.
 - GitHub: `hack x github connect|oauth-connect|disconnect|profiles|use|status|pr-upsert`
 - Linear: `hack x linear setup|connect|oauth-connect|disconnect|status|profiles|use|projects|project-bind|sync-issue|sync-project`
 
-Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also
-requires global `controlPlane.gateway.allowWrites = true`).
+Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also requires global `controlPlane.gateway.allowWrites = true`).
 
 Current gateway API surface (HTTP/WS):
+
 - `GET /v1/status`, `GET /v1/metrics`, `GET /v1/projects`, `GET /v1/ps`
 - `GET/POST /control-plane/projects/:id/jobs`
 - `GET /control-plane/projects/:id/jobs/:jobId`
@@ -122,6 +120,7 @@ Current gateway API surface (HTTP/WS):
 - `WS /control-plane/projects/:id/shells/:shellId/stream` (requires write token + allowWrites)
 
 Local auth service surface (daemon + global Caddy route):
+
 - `GET /health`
 - `GET /v1/auth/providers`
 - `GET /gh/start` (GitHub browser OAuth entrypoint)
@@ -130,15 +129,14 @@ Local auth service surface (daemon + global Caddy route):
 - `GET /v1/auth/github/start`
 - `GET /v1/auth/github/flows/:id`
 
-Interactive shell/TTY is available via the shell stream endpoints; use
-`hack x supervisor shell` or see protocol below.
+Interactive shell/TTY is available via the shell stream endpoints; use `hack x supervisor shell` or see protocol below.
 
 For full usage guidance and structured workflow patterns, see `gateway-api.md`.
 
 For exposure helpers, see the guides:
+
 - `guides/remote-cloudflare.md`
-- `guides/remote-tailscale.md`
-DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
+- `guides/remote-tailscale.md` DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
 
 ## Command reference
 
@@ -150,13 +148,14 @@ Usage: `hack x gateway token-create [options] [label]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <read|write>` | string | `read` | Token scope |
-| `--write` | boolean | false | Shortcut for `--scope write` |
-| `--label <label>` | string | - | Optional label |
+| Flag              | Type    | Default | Description                  |
+| ----------------- | ------- | ------- | ---------------------------- | ----------- |
+| `--scope <read    | write>` | string  | `read`                       | Token scope |
+| `--write`         | boolean | false   | Shortcut for `--scope write` |
+| `--label <label>` | string  | -       | Optional label               |
 
 Notes:
+
 - The first non-flag argument is treated as the label if `--label` is not used.
 
 #### token-list
@@ -177,11 +176,11 @@ Usage: `hack x supervisor job-list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-create
 
@@ -189,14 +188,14 @@ Usage: `hack x supervisor job-create [options] -- <command...>`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--runner <name>` | string | `generic` | Runner name |
-| `--cwd <path>` | string | - | Working directory (relative to project root) |
-| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
-| `--json` | boolean | false | Output JSON |
+| Flag                | Type    | Default   | Description                                  |
+| ------------------- | ------- | --------- | -------------------------------------------- |
+| `--project <name>`  | string  | -         | Target a registered project                  |
+| `--path <dir>`      | string  | -         | Target a repo path                           |
+| `--runner <name>`   | string  | `generic` | Runner name                                  |
+| `--cwd <path>`      | string  | -         | Working directory (relative to project root) |
+| `--env <KEY=VALUE>` | string  | -         | Environment override (repeatable)            |
+| `--json`            | boolean | false     | Output JSON                                  |
 
 ### GitHub extension (`hack x github`)
 
@@ -259,10 +258,9 @@ hack x github pr-upsert \
 ```
 
 Notes:
-- Profile config lives at:
-  `controlPlane.extensions["dance.hack.github"].config.profiles`.
-- Profile selection precedence is:
-  `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
+
+- Profile config lives at: `controlPlane.extensions["dance.hack.github"].config.profiles`.
+- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
 - Keychain storage uses profile-specific `authRef` + `service`.
 - Token resolution order is keychain first, then environment fallback (`tokenEnv`).
 - If token metadata includes `expiresAt`, auth resolution attempts automatic GitHub App refresh using profile `appId`, `installationId`, and private key source.
@@ -341,8 +339,7 @@ Detailed design and sequencing live in:
 
 ### Linear extension (`hack x linear`)
 
-Linear integration supports multiple auth profiles, project-level binding, and manual sync in both
-directions between Linear issues and hack tickets.
+Linear integration supports multiple auth profiles, project-level binding, and manual sync in both directions between Linear issues and hack tickets.
 
 Quick start:
 
@@ -365,11 +362,9 @@ hack x linear sync-project --from hack --owner both
 ```
 
 Notes:
-- Profile selection precedence is:
-  `--profile` -> `controlPlane.routing.overrides.linear.profile` ->
-  `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
-- Project mapping is stored in project config:
-  `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
+
+- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.linear.profile` -> `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
+- Project mapping is stored in project config: `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
 - Sync is manual by default (`sync-issue` / `sync-project`); there is no background autosync yet.
 - Ticket provenance is preserved during sync via `owner`, `source`, `tags`, and `external*` linkage fields.
 - `hack x linear connect` uses token mode when `--token`/`--stdin`/`$HACK_LINEAR_API_TOKEN` is present, and otherwise falls back to browser OAuth.
@@ -382,8 +377,7 @@ Notes:
 - Auth-broker Linear endpoints:
   - OAuth callback page: `/linear/callback`
   - Webhook ingest: `/linear/webhooks` (legacy alias: `/v1/integrations/linear/webhook`)
-- Sync toggles are configurable at
-  `controlPlane.extensions["dance.hack.linear"].config.sync`:
+- Sync toggles are configurable at `controlPlane.extensions["dance.hack.linear"].config.sync`:
   - `labels` (default `false`)
   - `statuses` (default `true`)
   - `dependencies` (default `true`)
@@ -396,11 +390,11 @@ Usage: `hack x supervisor job-show <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-cancel
 
@@ -408,10 +402,10 @@ Usage: `hack x supervisor job-cancel <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
+| Flag               | Type   | Default | Description                 |
+| ------------------ | ------ | ------- | --------------------------- |
+| `--project <name>` | string | -       | Target a registered project |
+| `--path <dir>`     | string | -       | Target a repo path          |
 
 #### job-tail
 
@@ -419,15 +413,15 @@ Usage: `hack x supervisor job-tail <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--logs-from <n>` | number | 0 | Resume from log offset |
-| `--from <n>` | number | 0 | Alias for `--logs-from` |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--follow`         | boolean | true    | Follow logs (default)       |
+| `--no-follow`      | boolean | false   | Print logs and exit         |
+| `--logs-from <n>`  | number  | 0       | Resume from log offset      |
+| `--from <n>`       | number  | 0       | Alias for `--logs-from`     |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-attach
 
@@ -435,16 +429,16 @@ Usage: `hack x supervisor job-attach <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--logs-from <n>` | number | 0 | Resume from log offset |
-| `--from <n>` | number | 0 | Alias for `--logs-from` |
-| `--events-from <n>` | number | 0 | Resume from event sequence |
-| `--json` | boolean | false | Output JSON |
+| Flag                | Type    | Default | Description                 |
+| ------------------- | ------- | ------- | --------------------------- |
+| `--project <name>`  | string  | -       | Target a registered project |
+| `--path <dir>`      | string  | -       | Target a repo path          |
+| `--follow`          | boolean | true    | Follow logs (default)       |
+| `--no-follow`       | boolean | false   | Print logs and exit         |
+| `--logs-from <n>`   | number  | 0       | Resume from log offset      |
+| `--from <n>`        | number  | 0       | Alias for `--logs-from`     |
+| `--events-from <n>` | number  | 0       | Resume from event sequence  |
+| `--json`            | boolean | false   | Output JSON                 |
 
 #### shell
 
@@ -452,20 +446,21 @@ Usage: `hack x supervisor shell [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--project-id <id>` | string | - | Target by project id (gateway) |
-| `--path <dir>` | string | - | Target a repo path |
-| `--gateway <url>` | string | `http://127.0.0.1:7788` | Gateway URL |
-| `--token <token>` | string | - | Gateway write token |
-| `--shell <path>` | string | - | Shell path |
-| `--cwd <path>` | string | - | Working directory |
-| `--cols <n>` | number | - | Terminal columns |
-| `--rows <n>` | number | - | Terminal rows |
-| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
+| Flag                | Type   | Default                 | Description                       |
+| ------------------- | ------ | ----------------------- | --------------------------------- |
+| `--project <name>`  | string | -                       | Target a registered project       |
+| `--project-id <id>` | string | -                       | Target by project id (gateway)    |
+| `--path <dir>`      | string | -                       | Target a repo path                |
+| `--gateway <url>`   | string | `http://127.0.0.1:7788` | Gateway URL                       |
+| `--token <token>`   | string | -                       | Gateway write token               |
+| `--shell <path>`    | string | -                       | Shell path                        |
+| `--cwd <path>`      | string | -                       | Working directory                 |
+| `--cols <n>`        | number | -                       | Terminal columns                  |
+| `--rows <n>`        | number | -                       | Terminal rows                     |
+| `--env <KEY=VALUE>` | string | -                       | Environment override (repeatable) |
 
 Notes:
+
 - `--project` and `--project-id` are mutually exclusive.
 
 ### Cloudflare extension (`hack x cloudflare`)
@@ -476,15 +471,15 @@ Usage: `hack x cloudflare tunnel-print [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--hostname <host>` | string | - | Gateway hostname |
-| `--tunnel <name>` | string | `hack-gateway` | Tunnel name |
-| `--origin <url>` | string | `http://127.0.0.1:7788` | Gateway origin |
-| `--ssh-hostname <host>` | string | - | SSH hostname (optional) |
-| `--ssh-origin <url>` | string | `ssh://127.0.0.1:22` | SSH origin |
-| `--credentials-file <path>` | string | - | Cloudflared credentials file |
-| `--out <path>` | string | - | Write config to a file |
+| Flag                        | Type   | Default                 | Description                  |
+| --------------------------- | ------ | ----------------------- | ---------------------------- |
+| `--hostname <host>`         | string | -                       | Gateway hostname             |
+| `--tunnel <name>`           | string | `hack-gateway`          | Tunnel name                  |
+| `--origin <url>`            | string | `http://127.0.0.1:7788` | Gateway origin               |
+| `--ssh-hostname <host>`     | string | -                       | SSH hostname (optional)      |
+| `--ssh-origin <url>`        | string | `ssh://127.0.0.1:22`    | SSH origin                   |
+| `--credentials-file <path>` | string | -                       | Cloudflared credentials file |
+| `--out <path>`              | string | -                       | Write config to a file       |
 
 #### tunnel-setup
 
@@ -511,11 +506,11 @@ Usage: `hack x cloudflare tunnel-start [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path |
-| `--out <path>` | string | - | Alias for `--config` |
-| `--tunnel <name>` | string | - | Override tunnel name |
+| Flag              | Type   | Default                     | Description          |
+| ----------------- | ------ | --------------------------- | -------------------- |
+| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path          |
+| `--out <path>`    | string | -                           | Alias for `--config` |
+| `--tunnel <name>` | string | -                           | Override tunnel name |
 
 #### tunnel-stop
 
@@ -527,10 +522,10 @@ Usage: `hack x cloudflare access-setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--ssh-hostname <host>` | string | - | SSH hostname |
-| `--user <user>` | string | - | SSH username |
+| Flag                    | Type   | Default | Description  |
+| ----------------------- | ------ | ------- | ------------ |
+| `--ssh-hostname <host>` | string | -       | SSH hostname |
+| `--user <user>`         | string | -       | SSH username |
 
 ### Tailscale extension (`hack x tailscale`)
 
@@ -563,6 +558,7 @@ Usage: `hack x tailscale oauth-disconnect [--auth-ref <ref>] [--json]`
 Usage: `hack x tailscale ip [args...]`
 
 Notes:
+
 - `status` and `ip` forward extra args directly to `tailscale`.
 - `ip` defaults to `-4` when no args are provided.
 
@@ -611,17 +607,18 @@ The gateway binds to `127.0.0.1` by default. Expose it through one of:
 - SSH tunnel (ad‑hoc): `ssh -L 7788:127.0.0.1:7788 <host>`
 - Zero Trust/VPN (persistent): Tailscale, Cloudflare, etc. targeting the gateway port
 - Optional Caddy route for local convenience (`https://gateway.hack`):
-  - Add a small labeled container in the global Caddy compose that proxies to
-    `host.docker.internal:7788` (or `host-gateway` on Linux).
+  - Add a small labeled container in the global Caddy compose that proxies to `host.docker.internal:7788` (or `host-gateway` on Linux).
 
 Keep tokens read-only unless you explicitly need writes.
 
 Recommended order:
-1) Start with SSH tunneling for quick remote access.
-2) Move to a private Zero Trust/VPN network once you want persistent access.
-3) Add the Caddy route only for nicer local URLs (not required for remote access).
+
+1. Start with SSH tunneling for quick remote access.
+2. Move to a private Zero Trust/VPN network once you want persistent access.
+3. Add the Caddy route only for nicer local URLs (not required for remote access).
 
 Remote helper commands:
+
 - `hack remote status` shows gateway + exposure status.
 - `hack remote qr` emits QR payloads for SSH or gateway clients.
 
@@ -655,7 +652,7 @@ Server → client:
 
 ```
 {"type":"ready","shellId":"...","cols":120,"rows":30,"cwd":"/repo","shell":"/bin/zsh","status":"running"}
-{"type":"output","data":"..."} 
+{"type":"output","data":"..."}
 {"type":"exit","exitCode":0,"signal":null}
 ```
 

From 9b0940838c4d022b1ff1fcbc6d5c07e378155b56 Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 18:50:40 +0000
Subject: [PATCH 090/134] docs: restore markdown table formatting

---
 docs/cli.md        | 832 +++++++++++++++++++++++----------------------
 docs/extensions.md | 213 ++++++------
 2 files changed, 527 insertions(+), 518 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index bf561b525..83ab9a58b 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,6 +1,7 @@
 # CLI Reference
 
-This reference mirrors the CLI spec in `src/cli/spec.ts`. Run `hack help` or `hack help <command>` for interactive help.
+This reference mirrors the CLI spec in `src/cli/spec.ts`.
+Run `hack help` or `hack help <command>` for interactive help.
 
 If you are new to Hack, scan the CLI in this order:
 
@@ -69,17 +70,17 @@ Usage: `hack global <subcommand>`
 
 Subcommands:
 
-| Subcommand   | Summary                                                      |
-| ------------ | ------------------------------------------------------------ | ------- | ---- | ------ |
-| `install`    | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy     |
-| `up`         | Start global infra containers                                |
-| `down`       | Stop global infra containers                                 |
-| `status`     | Show status for global infra (containers + networks)         |
-| `logs`       | Tail global infra logs (caddy                                | grafana | loki | alloy) |
-| `ca`         | Export Caddy Local CA cert (print path or PEM)               |
-| `cert`       | Generate local TLS certs via mkcert (for non-Caddy services) |
-| `trust`      | Trust Caddy Local CA (macOS) so https://\*.hack is trusted   |
-| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards)          |
+| Subcommand | Summary |
+| --- | --- |
+| `install` | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy |
+| `up` | Start global infra containers |
+| `down` | Stop global infra containers |
+| `status` | Show status for global infra (containers + networks) |
+| `logs` | Tail global infra logs (caddy|grafana|loki|alloy) |
+| `ca` | Export Caddy Local CA cert (print path or PEM) |
+| `cert` | Generate local TLS certs via mkcert (for non-Caddy services) |
+| `trust` | Trust Caddy Local CA (macOS) so https://*.hack is trusted |
+| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards) |
 
 #### hack global logs
 
@@ -87,18 +88,18 @@ Usage: `hack global logs [service] [options]`
 
 Arguments:
 
-| Name      | Type   | Required | Description                                                |
-| --------- | ------ | -------- | ---------------------------------------------------------- |
-| `service` | string | no       | Filter to one global service (caddy, grafana, loki, alloy) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `service` | string | no | Filter to one global service (caddy, grafana, loki, alloy) |
 
 Options:
 
-| Flag             | Type    | Default | Description                                               |
-| ---------------- | ------- | ------- | --------------------------------------------------------- |
-| `-f`, `--follow` | boolean | true    | Follow logs (default)                                     |
-| `--no-follow`    | boolean | false   | Print logs and exit                                       |
-| `--tail <n>`     | number  | 200     | Tail last N log lines                                     |
-| `--pretty`       | boolean | false   | Pretty-print logs (best-effort JSON parsing + formatting) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-f`, `--follow` | boolean | true | Follow logs (default) |
+| `--no-follow` | boolean | false | Print logs and exit |
+| `--tail <n>` | number | 200 | Tail last N log lines |
+| `--pretty` | boolean | false | Pretty-print logs (best-effort JSON parsing + formatting) |
 
 #### hack global ca
 
@@ -106,9 +107,9 @@ Usage: `hack global ca [options]`
 
 Options:
 
-| Flag      | Type    | Default | Description                                                    |
-| --------- | ------- | ------- | -------------------------------------------------------------- |
-| `--print` | boolean | false   | Print the CA cert PEM to stdout (instead of printing its path) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--print` | boolean | false | Print the CA cert PEM to stdout (instead of printing its path) |
 
 #### hack global cert
 
@@ -116,16 +117,16 @@ Usage: `hack global cert <hosts...> [options]`
 
 Arguments:
 
-| Name    | Type     | Required | Description                                 |
-| ------- | -------- | -------- | ------------------------------------------- |
-| `hosts` | string[] | yes      | One or more hostnames to generate certs for |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `hosts` | string[] | yes | One or more hostnames to generate certs for |
 
 Options:
 
-| Flag          | Type    | Default         | Description                                 |
-| ------------- | ------- | --------------- | ------------------------------------------- |
-| `--install`   | boolean | false           | Run mkcert -install before generating certs |
-| `--out <dir>` | string  | `~/.hack/certs` | Directory for generated cert/key            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--install` | boolean | false | Run mkcert -install before generating certs |
+| `--out <dir>` | string | `~/.hack/certs` | Directory for generated cert/key |
 
 ### hack projects
 
@@ -150,9 +151,9 @@ Usage: `hack projects prune [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                                   |
-| ------------------ | ------- | ------- | --------------------------------------------- |
-| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
 
 ### hack status
 
@@ -160,12 +161,12 @@ Usage: `hack status [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                                   |
-| ------------------ | ------- | ------- | --------------------------------------------- |
-| `--project <name>` | string  | -       | Filter to a registered project name           |
-| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
-| `--all`            | boolean | false   | Include unregistered docker compose projects  |
-| `--json`           | boolean | false   | Output JSON (machine-readable)                |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Filter to a registered project name |
+| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
+| `--all` | boolean | false | Include unregistered docker compose projects |
+| `--json` | boolean | false | Output JSON (machine-readable) |
 
 ### hack usage
 
@@ -208,13 +209,13 @@ Usage: `hack up [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `-d`, `--detach` | boolean | false | Run in background (docker compose up -d) |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack down
 
@@ -223,12 +224,12 @@ Usage: `hack down [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack restart
 
@@ -237,12 +238,12 @@ Usage: `hack restart [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack ps
 
@@ -264,9 +265,9 @@ Usage: `hack logs [service] [options]`
 
 Arguments:
 
-| Name      | Type   | Required | Description                                        |
-| --------- | ------ | -------- | -------------------------------------------------- |
-| `service` | string | no       | Filter logs by service (shortcut for `--services`) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `service` | string | no | Filter logs by service (shortcut for `--services`) |
 
 Options:
 
@@ -300,10 +301,10 @@ Usage: `hack run <service> [-- <cmd...>] [options]`
 
 Arguments:
 
-| Name      | Type     | Required | Description                                     |
-| --------- | -------- | -------- | ----------------------------------------------- |
-| `service` | string   | yes      | Compose service name                            |
-| `cmd`     | string[] | no       | Command to run (defaults to service entrypoint) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `service` | string | yes | Compose service name |
+| `cmd` | string[] | no | Command to run (defaults to service entrypoint) |
 
 Options:
 
@@ -321,18 +322,18 @@ Usage: `hack open [target] [options]`
 
 Arguments:
 
-| Name     | Type   | Required | Description                                         |
-| -------- | ------ | -------- | --------------------------------------------------- |
-| `target` | string | no       | `www` (default), `logs`, a subdomain, or a full URL |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `target` | string | no | `www` (default), `logs`, a subdomain, or a full URL |
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string  | -       | Target a registered project by name            |
-| `--branch <name>`    | string  | -       | Run against a branch-specific instance         |
-| `--json`             | boolean | false   | Output JSON with `{ "url": "..." }`            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--branch <name>` | string | - | Run against a branch-specific instance |
+| `--json` | boolean | false | Output JSON with `{ "url": "..." }` |
 
 Notes:
 
@@ -347,10 +348,10 @@ Usage: `hack tui [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 Notes:
 
@@ -362,12 +363,12 @@ Usage: `hack branch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                  |
-| ---------- | ---------------------------------------- |
-| `add`      | Register a branch alias for this project |
-| `list`     | List registered branch aliases           |
-| `remove`   | Remove a branch alias                    |
-| `open`     | Open the branch host in a browser        |
+| Subcommand | Summary |
+| --- | --- |
+| `add` | Register a branch alias for this project |
+| `list` | List registered branch aliases |
+| `remove` | Remove a branch alias |
+| `open` | Open the branch host in a browser |
 
 #### hack branch add
 
@@ -375,17 +376,17 @@ Usage: `hack branch add <name> [options]`
 
 Arguments:
 
-| Name   | Type   | Required | Description          |
-| ------ | ------ | -------- | -------------------- |
-| `name` | string | yes      | Branch name or alias |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | yes | Branch name or alias |
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
-| `--note <text>`      | string | -       | Optional note for the branch entry             |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--note <text>` | string | - | Optional note for the branch entry |
 
 #### hack branch list
 
@@ -393,10 +394,10 @@ Usage: `hack branch list [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack branch remove
 
@@ -404,16 +405,16 @@ Usage: `hack branch remove <name> [options]`
 
 Arguments:
 
-| Name   | Type   | Required | Description          |
-| ------ | ------ | -------- | -------------------- |
-| `name` | string | yes      | Branch name or alias |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | yes | Branch name or alias |
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack branch open
 
@@ -421,16 +422,16 @@ Usage: `hack branch open <name> [options]`
 
 Arguments:
 
-| Name   | Type   | Required | Description          |
-| ------ | ------ | -------- | -------------------- |
-| `name` | string | yes      | Branch name or alias |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | yes | Branch name or alias |
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 ### hack config
 
@@ -438,10 +439,10 @@ Usage: `hack config <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                            |
-| ---------- | ---------------------------------- |
-| `get`      | Read a value from hack.config.json |
-| `set`      | Update a value in hack.config.json |
+| Subcommand | Summary |
+| --- | --- |
+| `get` | Read a value from hack.config.json |
+| `set` | Update a value in hack.config.json |
 
 #### hack config get
 
@@ -449,17 +450,17 @@ Usage: `hack config get <key> [options]`
 
 Arguments:
 
-| Name  | Type   | Required | Description                             |
-| ----- | ------ | -------- | --------------------------------------- |
-| `key` | string | yes      | Dot path (e.g. `logs.snapshot_backend`) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string  | -       | Target a registered project by name            |
-| `--global`           | boolean | false   | Read global `~/.hack/hack.config.json`         |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--global` | boolean | false | Read global `~/.hack/hack.config.json` |
 
 #### hack config set
 
@@ -467,18 +468,18 @@ Usage: `hack config set <key> <value> [options]`
 
 Arguments:
 
-| Name    | Type   | Required | Description                                          |
-| ------- | ------ | -------- | ---------------------------------------------------- |
-| `key`   | string | yes      | Dot path (e.g. `logs.snapshot_backend`)              |
-| `value` | string | yes      | JSON value or raw string (parsed as JSON when valid) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
+| `value` | string | yes | JSON value or raw string (parsed as JSON when valid) |
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string  | -       | Target a registered project by name            |
-| `--global`           | boolean | false   | Write global `~/.hack/hack.config.json`        |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--global` | boolean | false | Write global `~/.hack/hack.config.json` |
 
 ## Collaboration & integrations
 
@@ -546,12 +547,12 @@ Usage: `hack env <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                            |
-| ---------- | -------------------------------------------------- |
-| `list`     | List env contract vars and resolution state        |
-| `set`      | Set an env value (.hack/.env or secret backend)    |
-| `unset`    | Unset an env value (.hack/.env and secret backend) |
-| `backend`  | Manage env/secret backend strategy                 |
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List env contract vars and resolution state |
+| `set` | Set an env value (.hack/.env or secret backend) |
+| `unset` | Unset an env value (.hack/.env and secret backend) |
+| `backend` | Manage env/secret backend strategy |
 
 #### hack env list
 
@@ -559,12 +560,12 @@ Usage: `hack env list [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                       |
-| -------------------- | ------- | ------- | ------------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)    |
-| `--project <name>`   | string  | -       | Target a registered project by name               |
-| `--json`             | boolean | false   | Output JSON (machine-readable)                    |
-| `--show-secrets`     | boolean | false   | Print secret values (secret backend) in plaintext |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--show-secrets` | boolean | false | Print secret values (secret backend) in plaintext |
 
 #### hack env set
 
@@ -586,10 +587,10 @@ Usage: `hack env unset [key] [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack env backend
 
@@ -597,10 +598,10 @@ Usage: `hack env backend <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                     |
-| ---------- | ------------------------------------------- |
-| `status`   | Show configured env/secret backend strategy |
-| `use`      | Select env/secret backend strategy          |
+| Subcommand | Summary |
+| --- | --- |
+| `status` | Show configured env/secret backend strategy |
+| `use` | Select env/secret backend strategy |
 
 #### hack env backend status
 
@@ -608,9 +609,9 @@ Usage: `hack env backend status [options]`
 
 Options:
 
-| Flag     | Type    | Default | Description                    |
-| -------- | ------- | ------- | ------------------------------ |
-| `--json` | boolean | false   | Output JSON (machine-readable) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
 
 #### hack env backend use
 
@@ -619,8 +620,8 @@ Usage: `hack env backend use <keychain|encrypted_file|cloud> [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- | --- |
-| `--provider <aws | gcp | azure | vault>` | string | - | Cloud provider when backend is `cloud` |
+| --- | --- | --- | --- |
+| `--provider <aws|gcp|azure|vault>` | string | - | Cloud provider when backend is `cloud` |
 | `--store-path <path>` | string | - | Encrypted file path when backend is `encrypted_file` |
 | `--secret-project <id>` | string | - | Optional cloud account/project identifier |
 | `--secret-prefix <prefix>` | string | - | Optional cloud secret name prefix |
@@ -634,16 +635,16 @@ With no subcommand, opens an interactive picker of active sessions and available
 
 Subcommands:
 
-| Subcommand | Summary                                    |
-| ---------- | ------------------------------------------ |
-| `list`     | List active sessions                       |
-| `start`    | Start or attach to a session for a project |
-| `stop`     | Stop (kill) a session                      |
-| `attach`   | Attach to an existing session              |
-| `exec`     | Execute a command in a session             |
-| `panes`    | List panes in a tmux session               |
-| `capture`  | Capture recent output from a tmux session  |
-| `tail`     | Tail output from a tmux session            |
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List active sessions |
+| `start` | Start or attach to a session for a project |
+| `stop` | Stop (kill) a session |
+| `attach` | Attach to an existing session |
+| `exec` | Execute a command in a session |
+| `panes` | List panes in a tmux session |
+| `capture` | Capture recent output from a tmux session |
+| `tail` | Tail output from a tmux session |
 
 #### hack session start
 
@@ -651,11 +652,11 @@ Usage: `hack session start [project] [options]`
 
 Options:
 
-| Flag              | Type    | Default | Description                                   |
-| ----------------- | ------- | ------- | --------------------------------------------- |
-| `--up`            | boolean | false   | Run hack up -d before attaching               |
-| `--new`           | boolean | false   | Force create new session even if one exists   |
-| `--name <suffix>` | string  | -       | Custom suffix for new session (e.g., agent-1) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--up` | boolean | false | Run hack up -d before attaching |
+| `--new` | boolean | false | Force create new session even if one exists |
+| `--name <suffix>` | string | - | Custom suffix for new session (e.g., agent-1) |
 
 #### hack session panes
 
@@ -663,10 +664,10 @@ Usage: `hack session panes <session> [options]`
 
 Options:
 
-| Flag       | Type    | Default | Description                          |
-| ---------- | ------- | ------- | ------------------------------------ |
-| `--json`   | boolean | false   | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false   | Output human-friendly text           |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false | Output human-friendly text |
 
 #### hack session capture
 
@@ -674,12 +675,12 @@ Usage: `hack session capture <session> [options]`
 
 Options:
 
-| Flag                | Type    | Default | Description                             |
-| ------------------- | ------- | ------- | --------------------------------------- |
-| `--target <target>` | string  | -       | Tmux pane target (default: active pane) |
-| `--lines <n>`       | number  | 200     | Number of lines to capture              |
-| `--json`            | boolean | false   | Output NDJSON stream (start/log/end)    |
-| `--pretty`          | boolean | false   | Output human-friendly text              |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--target <target>` | string | - | Tmux pane target (default: active pane) |
+| `--lines <n>` | number | 200 | Number of lines to capture |
+| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false | Output human-friendly text |
 
 #### hack session tail
 
@@ -687,14 +688,14 @@ Usage: `hack session tail <session> [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                             |
-| -------------------- | ------- | ------- | --------------------------------------- |
-| `--target <target>`  | string  | -       | Tmux pane target (default: active pane) |
-| `--lines <n>`        | number  | 200     | Number of lines to capture              |
-| `--interval-ms <ms>` | number  | 500     | Polling interval in milliseconds        |
-| `--max-ms <ms>`      | number  | 5000    | Stop tailing after N milliseconds       |
-| `--json`             | boolean | false   | Output NDJSON stream (start/log/end)    |
-| `--pretty`           | boolean | false   | Output human-friendly text              |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--target <target>` | string | - | Tmux pane target (default: active pane) |
+| `--lines <n>` | number | 200 | Number of lines to capture |
+| `--interval-ms <ms>` | number | 500 | Polling interval in milliseconds |
+| `--max-ms <ms>` | number | 5000 | Stop tailing after N milliseconds |
+| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false | Output human-friendly text |
 
 ### hack ssh
 
@@ -702,25 +703,27 @@ Usage: `hack ssh [session] [options]`
 
 Options:
 
-| Flag                  | Type    | Default | Description                                  |
-| --------------------- | ------- | ------- | -------------------------------------------- |
-| `-H`, `--host <host>` | string  | -       | SSH host (hostname or IP)                    |
-| `-u`, `--user <user>` | string  | -       | SSH username                                 |
-| `-t`, `--tailscale`   | boolean | false   | Use Tailscale SSH                            |
-| `-d`, `--direct`      | boolean | false   | Use direct SSH (requires --host)             |
-| `-p`, `--port <port>` | string  | -       | SSH port for direct connection (default: 22) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-H`, `--host <host>` | string | - | SSH host (hostname or IP) |
+| `-u`, `--user <user>` | string | - | SSH username |
+| `-t`, `--tailscale` | boolean | false | Use Tailscale SSH |
+| `-d`, `--direct` | boolean | false | Use direct SSH (requires --host) |
+| `-p`, `--port <port>` | string | - | SSH port for direct connection (default: 22) |
 
 ### hack tickets
 
 Usage: `hack tickets <args...>`
 
-`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`). Run `hack tickets` with no args to see available subcommands.
+`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`).
+Run `hack tickets` with no args to see available subcommands.
 
 ### hack linear
 
 Usage: `hack linear <args...>`
 
-`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`). Run `hack linear` with no args to see available subcommands.
+`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`).
+Run `hack linear` with no args to see available subcommands.
 
 ## Internal commands
 
@@ -730,8 +733,8 @@ Usage: `hack internal <subcommand>`
 
 Subcommands:
 
-| Subcommand    | Summary                             |
-| ------------- | ----------------------------------- |
+| Subcommand | Summary |
+| --- | --- |
 | `extra-hosts` | Manage internal Compose extra_hosts |
 
 #### hack internal extra-hosts
@@ -740,17 +743,17 @@ Usage: `hack internal extra-hosts <subcommand> [options]`
 
 Options:
 
-| Flag                  | Type   | Default | Description                       |
-| --------------------- | ------ | ------- | --------------------------------- |
-| `-p`, `--path <path>` | string | -       | Start directory (defaults to cwd) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <path>` | string | - | Start directory (defaults to cwd) |
 
 Subcommands:
 
-| Subcommand | Summary                              |
-| ---------- | ------------------------------------ |
-| `set`      | Set an internal extra_hosts entry    |
-| `unset`    | Remove an internal extra_hosts entry |
-| `list`     | List internal extra_hosts entries    |
+| Subcommand | Summary |
+| --- | --- |
+| `set` | Set an internal extra_hosts entry |
+| `unset` | Remove an internal extra_hosts entry |
+| `list` | List internal extra_hosts entries |
 
 #### hack internal extra-hosts set
 
@@ -772,11 +775,11 @@ Usage: `hack gateway <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                   |
-| ---------- | ----------------------------------------- |
-| `enable`   | Enable the gateway and start hackd        |
-| `setup`    | Guided gateway setup (enable + token)     |
-| `disable`  | Disable the gateway (does not stop hackd) |
+| Subcommand | Summary |
+| --- | --- |
+| `enable` | Enable the gateway and start hackd |
+| `setup` | Guided gateway setup (enable + token) |
+| `disable` | Disable the gateway (does not stop hackd) |
 
 #### hack gateway enable
 
@@ -784,10 +787,10 @@ Usage: `hack gateway enable [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack gateway setup
 
@@ -795,13 +798,13 @@ Usage: `hack gateway setup [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                         |
-| -------------------- | ------- | ------- | --------------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
-| `--project <name>`   | string  | -       | Target a registered project by name                 |
-| `--qr`               | boolean | true    | Force QR output after setup (default)               |
-| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
-| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--qr` | boolean | true | Force QR output after setup (default) |
+| `--no-qr` | boolean | false | Skip QR output after setup |
+| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
 
 #### hack gateway disable
 
@@ -809,10 +812,10 @@ Usage: `hack gateway disable [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 ### hack node
 
@@ -820,20 +823,20 @@ Usage: `hack node <subcommand>`
 
 Subcommands:
 
-| Subcommand     | Summary                                                       |
-| -------------- | ------------------------------------------------------------- |
-| `init`         | Initialize this host as a node and emit enrollment bundle     |
-| `pair`         | Pair node with one-command or expiring verification-code flow |
-| `ssh`          | Manage SSH bootstrap for node pairing and remote runs         |
-| `add`          | Add a node from an enrollment bundle                          |
-| `list`         | List registered nodes                                         |
-| `status`       | Probe node health and report live status                      |
-| `use`          | Set default node                                              |
-| `remove`       | Remove node registration                                      |
-| `workspace`    | Inspect and repair node workspace map entries                 |
-| `routes`       | Inspect and repair controller-side remote route bridge        |
-| `provider`     | Manage provider-specific node bootstrap workflows             |
-| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints    |
+| Subcommand | Summary |
+| --- | --- |
+| `init` | Initialize this host as a node and emit enrollment bundle |
+| `pair` | Pair node with one-command or expiring verification-code flow |
+| `ssh` | Manage SSH bootstrap for node pairing and remote runs |
+| `add` | Add a node from an enrollment bundle |
+| `list` | List registered nodes |
+| `status` | Probe node health and report live status |
+| `use` | Set default node |
+| `remove` | Remove node registration |
+| `workspace` | Inspect and repair node workspace map entries |
+| `routes` | Inspect and repair controller-side remote route bridge |
+| `provider` | Manage provider-specific node bootstrap workflows |
+| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints |
 
 Examples:
 
@@ -938,12 +941,12 @@ Usage: `hack node workspace <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                                |
-| ---------- | ------------------------------------------------------ |
-| `list`     | List node-local workspace map entries                  |
-| `resolve`  | Resolve a map entry by controller project selector     |
-| `attach`   | Attach an existing local workspace to project selector |
-| `remove`   | Remove a map entry by project selector                 |
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List node-local workspace map entries |
+| `resolve` | Resolve a map entry by controller project selector |
+| `attach` | Attach an existing local workspace to project selector |
+| `remove` | Remove a map entry by project selector |
 
 Examples:
 
@@ -960,10 +963,10 @@ Usage: `hack node routes <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                             |
-| ---------- | --------------------------------------------------- |
-| `status`   | Show controller-side remote route bridge state      |
-| `repair`   | Re-render and re-apply persisted route bridge stack |
+| Subcommand | Summary |
+| --- | --- |
+| `status` | Show controller-side remote route bridge state |
+| `repair` | Re-render and re-apply persisted route bridge stack |
 
 Examples:
 
@@ -979,11 +982,11 @@ Usage: `hack dispatch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                  |
-| ---------- | ---------------------------------------- |
-| `run`      | Dispatch a command to a node workspace   |
-| `status`   | Show dispatched run status               |
-| `logs`     | Show or follow persisted/remote run logs |
+| Subcommand | Summary |
+| --- | --- |
+| `run` | Dispatch a command to a node workspace |
+| `status` | Show dispatched run status |
+| `logs` | Show or follow persisted/remote run logs |
 
 #### hack dispatch run
 
@@ -992,15 +995,15 @@ Usage: `hack dispatch run --project <name|id> [options] -- <command...>`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- | --- |
-| `--project <name | id>` | string | - | Project name or id |
-| `--node <id | default | auto>` | string | auto | Target node id, or use default/auto |
+| --- | --- | --- | --- |
+| `--project <name|id>` | string | - | Project name or id |
+| `--node <id|default|auto>` | string | auto | Target node id, or use default/auto |
 | `--provider <provider>` | string | - | Provider route override used when resolving profile/bootstrap intent |
 | `--profile <profile-id>` | string | - | Provider profile route override |
 | `--bootstrap-if-needed` | boolean | false | Allow guarded provider bootstrap handoff when no reachable node is found |
 | `--branch <branch>` | string | current | Target branch on selected node |
 | `--ticket <ticket-id>` | string | - | Ticket id to associate with run metadata |
-| `--runner <generic | codex | claude | cursor>` | string | `generic` | Runner identity for policy and audit |
+| `--runner <generic|codex|claude|cursor>` | string | `generic` | Runner identity for policy and audit |
 | `--approve` | boolean | false | Approve high/critical risk commands non-interactively |
 | `--pr` | boolean | false | Push branch + create/update GitHub PR on successful run |
 | `--pr-base <branch>` | string | `main` | Base branch used with `--pr` |
@@ -1047,12 +1050,12 @@ If you run `hack remote` with no subcommand, it prints status and offers to run
 
 Subcommands:
 
-| Subcommand | Summary                              |
-| ---------- | ------------------------------------ |
-| `setup`    | Run the guided gateway setup         |
-| `status`   | Show remote/gateway status           |
-| `monitor`  | Open a remote status TUI             |
-| `qr`       | Print a QR payload for remote access |
+| Subcommand | Summary |
+| --- | --- |
+| `setup` | Run the guided gateway setup |
+| `status` | Show remote/gateway status |
+| `monitor` | Open a remote status TUI |
+| `qr` | Print a QR payload for remote access |
 
 #### hack remote setup
 
@@ -1060,13 +1063,13 @@ Usage: `hack remote setup [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                         |
-| -------------------- | ------- | ------- | --------------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
-| `--project <name>`   | string  | -       | Target a registered project by name                 |
-| `--qr`               | boolean | true    | Force QR output after setup (default)               |
-| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
-| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--qr` | boolean | true | Force QR output after setup (default) |
+| `--no-qr` | boolean | false | Skip QR output after setup |
+| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
 
 #### hack remote status
 
@@ -1074,10 +1077,10 @@ Usage: `hack remote status [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack remote monitor
 
@@ -1085,10 +1088,10 @@ Usage: `hack remote monitor [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack remote qr
 
@@ -1116,9 +1119,9 @@ Usage: `hack x <namespace> <command> [args...]`
 
 Arguments:
 
-| Name   | Type     | Required | Description                             |
-| ------ | -------- | -------- | --------------------------------------- |
-| `args` | string[] | no       | Extension command args (passed through) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `args` | string[] | no | Extension command args (passed through) |
 
 Notes:
 
@@ -1133,15 +1136,15 @@ Usage: `hack setup <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                                |
-| ---------- | ------------------------------------------------------ |
-| `cursor`   | Install Cursor rules for hack CLI usage                |
-| `claude`   | Install Claude Code hooks for hack CLI usage           |
-| `codex`    | Install Codex skill for hack CLI usage                 |
-| `tickets`  | Install Codex skill for hack tickets usage             |
-| `agents`   | Install AGENTS.md / CLAUDE.md snippets                 |
-| `sync`     | Refresh agent docs, skills, and MCP configs            |
-| `mcp`      | Install MCP configs for hack CLI usage (no-shell only) |
+| Subcommand | Summary |
+| --- | --- |
+| `cursor` | Install Cursor rules for hack CLI usage |
+| `claude` | Install Claude Code hooks for hack CLI usage |
+| `codex` | Install Codex skill for hack CLI usage |
+| `tickets` | Install Codex skill for hack tickets usage |
+| `agents` | Install AGENTS.md / CLAUDE.md snippets |
+| `sync` | Refresh agent docs, skills, and MCP configs |
+| `mcp` | Install MCP configs for hack CLI usage (no-shell only) |
 
 #### hack setup cursor
 
@@ -1149,12 +1152,12 @@ Usage: `hack setup cursor [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup claude
 
@@ -1162,12 +1165,12 @@ Usage: `hack setup claude [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup codex
 
@@ -1175,12 +1178,12 @@ Usage: `hack setup codex [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup agents
 
@@ -1188,14 +1191,14 @@ Usage: `hack setup agents [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--all`              | boolean | false   | Target all supported docs                      |
-| `--agents-md`        | boolean | false   | Target AGENTS.md                               |
-| `--claude-md`        | boolean | false   | Target CLAUDE.md                               |
-| `--check`            | boolean | false   | Check whether integration is installed         |
-| `--remove`           | boolean | false   | Remove integration files/config                |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--all` | boolean | false | Target all supported docs |
+| `--agents-md` | boolean | false | Target AGENTS.md |
+| `--claude-md` | boolean | false | Target CLAUDE.md |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup sync
 
@@ -1203,13 +1206,13 @@ Usage: `hack setup sync [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--global`           | boolean | false   | Target global (user) scope only                |
-| `--all-scopes`       | boolean | false   | Target both project and global (user) scopes   |
-| `--check`            | boolean | false   | Check whether integrations are installed       |
-| `--remove`           | boolean | false   | Remove generated integration files/config      |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Target global (user) scope only |
+| `--all-scopes` | boolean | false | Target both project and global (user) scopes |
+| `--check` | boolean | false | Check whether integrations are installed |
+| `--remove` | boolean | false | Remove generated integration files/config |
 
 Automatic guardrail:
 
@@ -1222,16 +1225,16 @@ Usage: `hack setup mcp [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--all`              | boolean | false   | Target all supported clients                     |
-| `--cursor`           | boolean | false   | Target Cursor integration                        |
-| `--claude`           | boolean | false   | Target Claude integration                        |
-| `--codex`            | boolean | false   | Target Codex integration                         |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--all` | boolean | false | Target all supported clients |
+| `--cursor` | boolean | false | Target Cursor integration |
+| `--claude` | boolean | false | Target Claude integration |
+| `--codex` | boolean | false | Target Codex integration |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 ### hack agent
 
@@ -1239,11 +1242,11 @@ Usage: `hack agent <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                         |
-| ---------- | ------------------------------- |
-| `prime`    | Print agent primer text         |
+| Subcommand | Summary |
+| --- | --- |
+| `prime` | Print agent primer text |
 | `patterns` | Print agent init patterns guide |
-| `init`     | Print agent init prompt         |
+| `init` | Print agent init prompt |
 
 #### hack agent init
 
@@ -1251,10 +1254,10 @@ Usage: `hack agent init [options]`
 
 Options:
 
-| Flag                    | Type   | Default | Description                                    |
-| ----------------------- | ------ | ------- | ---------------------------------------------- | ------ | --- | ---------------------------------------------- |
-| `-p`, `--path <dir>`    | string | -       | Run against a repo path (overrides cwd search) |
-| `-c`, `--client <cursor | claude | codex   | print>`                                        | string | -   | Open init prompt in an agent client (or print) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `-c`, `--client <cursor|claude|codex|print>` | string | - | Open init prompt in an agent client (or print) |
 
 ### hack mcp
 
@@ -1262,11 +1265,11 @@ Usage: `hack mcp <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                  |
-| ---------- | ---------------------------------------- |
-| `serve`    | Run the MCP server over stdio            |
-| `install`  | Install MCP config for supported clients |
-| `print`    | Print MCP config snippets                |
+| Subcommand | Summary |
+| --- | --- |
+| `serve` | Run the MCP server over stdio |
+| `install` | Install MCP config for supported clients |
+| `print` | Print MCP config snippets |
 
 #### hack mcp install
 
@@ -1274,17 +1277,17 @@ Usage: `hack mcp install [options]`
 
 Options:
 
-| Flag                 | Type      | Default | Description                                    |
-| -------------------- | --------- | ------- | ---------------------------------------------- | ----------------------------------------- |
-| `--scope <user       | project>` | string  | `user`                                         | Write MCP config to user or project scope |
-| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
-| `--all`              | boolean   | false   | Target all supported clients                   |
-| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
-| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
-| `--codex`            | boolean   | false   | Target Codex MCP config                        |
-| `--docs`             | boolean   | false   | Update AGENTS.md and CLAUDE.md with hack usage |
-| `--agents-md`        | boolean   | false   | Update AGENTS.md with hack usage               |
-| `--claude-md`        | boolean   | false   | Update CLAUDE.md with hack usage               |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--scope <user|project>` | string | `user` | Write MCP config to user or project scope |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--all` | boolean | false | Target all supported clients |
+| `--cursor` | boolean | false | Target Cursor MCP config |
+| `--claude` | boolean | false | Target Claude CLI MCP config |
+| `--codex` | boolean | false | Target Codex MCP config |
+| `--docs` | boolean | false | Update AGENTS.md and CLAUDE.md with hack usage |
+| `--agents-md` | boolean | false | Update AGENTS.md with hack usage |
+| `--claude-md` | boolean | false | Update CLAUDE.md with hack usage |
 
 Notes:
 
@@ -1297,14 +1300,14 @@ Usage: `hack mcp print [options]`
 
 Options:
 
-| Flag                 | Type      | Default | Description                                    |
-| -------------------- | --------- | ------- | ---------------------------------------------- | ------------------------------------------ |
-| `--scope <user       | project>` | string  | `user`                                         | Print MCP config for user or project scope |
-| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
-| `--all`              | boolean   | false   | Target all supported clients                   |
-| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
-| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
-| `--codex`            | boolean   | false   | Target Codex MCP config                        |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--scope <user|project>` | string | `user` | Print MCP config for user or project scope |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--all` | boolean | false | Target all supported clients |
+| `--cursor` | boolean | false | Target Cursor MCP config |
+| `--claude` | boolean | false | Target Claude CLI MCP config |
+| `--codex` | boolean | false | Target Codex MCP config |
 
 ## Diagnostics commands
 
@@ -1343,17 +1346,17 @@ Usage: `hack daemon <subcommand>`
 
 Subcommands:
 
-| Subcommand  | Summary                                    |
-| ----------- | ------------------------------------------ |
-| `start`     | Start hackd (local daemon)                 |
-| `stop`      | Stop hackd                                 |
-| `restart`   | Restart hackd                              |
-| `status`    | Show hackd status                          |
-| `metrics`   | Show hackd metrics                         |
-| `logs`      | Show hackd logs                            |
-| `clear`     | Clear stale hackd pid/socket files         |
-| `install`   | Install hackd as a launchd service (macOS) |
-| `uninstall` | Uninstall hackd launchd service (macOS)    |
+| Subcommand | Summary |
+| --- | --- |
+| `start` | Start hackd (local daemon) |
+| `stop` | Stop hackd |
+| `restart` | Restart hackd |
+| `status` | Show hackd status |
+| `metrics` | Show hackd metrics |
+| `logs` | Show hackd logs |
+| `clear` | Clear stale hackd pid/socket files |
+| `install` | Install hackd as a launchd service (macOS) |
+| `uninstall` | Uninstall hackd launchd service (macOS) |
 
 Autostart + self-heal behavior:
 
@@ -1370,9 +1373,9 @@ Usage: `hack daemon start [options]`
 
 Options:
 
-| Flag           | Type    | Default | Description                         |
-| -------------- | ------- | ------- | ----------------------------------- |
-| `--foreground` | boolean | false   | Run hackd in the foreground (debug) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--foreground` | boolean | false | Run hackd in the foreground (debug) |
 
 #### hack daemon status
 
@@ -1380,9 +1383,9 @@ Usage: `hack daemon status [options]`
 
 Options:
 
-| Flag     | Type    | Default | Description                                                    |
-| -------- | ------- | ------- | -------------------------------------------------------------- |
-| `--json` | boolean | false   | Output JSON (machine-readable, includes launchd info on macOS) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable, includes launchd info on macOS) |
 
 #### hack daemon logs
 
@@ -1390,32 +1393,35 @@ Usage: `hack daemon logs [options]`
 
 Options:
 
-| Flag         | Type   | Default | Description           |
-| ------------ | ------ | ------- | --------------------- |
-| `--tail <n>` | number | 200     | Tail last N log lines |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--tail <n>` | number | 200 | Tail last N log lines |
 
 #### hack daemon install
 
 Usage: `hack daemon install [options]`
 
-Installs hackd as a launchd service on macOS. The daemon will be managed by launchd and can optionally start automatically on login.
+Installs hackd as a launchd service on macOS. The daemon will be managed by launchd
+and can optionally start automatically on login.
 
 Options:
 
-| Flag               | Type    | Default | Description                               |
-| ------------------ | ------- | ------- | ----------------------------------------- |
-| `--run-at-load`    | boolean | true    | Start hackd automatically on login        |
-| `--no-run-at-load` | boolean | -       | Do not start hackd automatically on login |
-| `--gui-only`       | boolean | true    | Only run in GUI sessions (Aqua)           |
-| `--no-gui-only`    | boolean | -       | Run in all session types (including SSH)  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--run-at-load` | boolean | true | Start hackd automatically on login |
+| `--no-run-at-load` | boolean | - | Do not start hackd automatically on login |
+| `--gui-only` | boolean | true | Only run in GUI sessions (Aqua) |
+| `--no-gui-only` | boolean | - | Run in all session types (including SSH) |
 
-The service uses the label `dance.hack.hackd` and writes its plist to `~/Library/LaunchAgents/dance.hack.hackd.plist`.
+The service uses the label `dance.hack.hackd` and writes its plist to
+`~/Library/LaunchAgents/dance.hack.hackd.plist`.
 
 #### hack daemon uninstall
 
 Usage: `hack daemon uninstall`
 
-Uninstalls the hackd launchd service on macOS. Removes the plist and unloads the service from launchd.
+Uninstalls the hackd launchd service on macOS. Removes the plist and unloads
+the service from launchd.
 
 ### hack log-pipe
 
@@ -1423,10 +1429,10 @@ Usage: `hack log-pipe [options]`
 
 Options:
 
-| Flag              | Type           | Default | Description |
-| ----------------- | -------------- | ------- | ----------- | ------------------------------- | -------------------------------------- |
-| `--format <auto   | docker-compose | plain>` | string      | `auto`                          | How to parse incoming lines from stdin |
-| `--stream <stdout | stderr>`       | string  | `stdout`    | Treat stdin as stdout or stderr |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--format <auto|docker-compose|plain>` | string | `auto` | How to parse incoming lines from stdin |
+| `--stream <stdout|stderr>` | string | `stdout` | Treat stdin as stdout or stderr |
 
 ### hack help
 
@@ -1434,9 +1440,9 @@ Usage: `hack help [path...]`
 
 Arguments:
 
-| Name   | Type     | Required | Description                                        |
-| ------ | -------- | -------- | -------------------------------------------------- |
-| `path` | string[] | no       | Command path to show help for (e.g. `global logs`) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `path` | string[] | no | Command path to show help for (e.g. `global logs`) |
 
 ### hack update
 
@@ -1444,12 +1450,12 @@ Usage: `hack update [options]`
 
 Options:
 
-| Flag          | Type    | Default | Description                                    |
-| ------------- | ------- | ------- | ---------------------------------------------- |
-| `--check`     | boolean | false   | Check for updates (do not install)             |
-| `--yes`       | boolean | false   | Apply update without prompting                 |
-| `--tag <tag>` | string  | -       | Update to a specific release tag (e.g. v1.4.0) |
-| `--json`      | boolean | false   | Output JSON (machine-readable)                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--check` | boolean | false | Check for updates (do not install) |
+| `--yes` | boolean | false | Apply update without prompting |
+| `--tag <tag>` | string | - | Update to a specific release tag (e.g. v1.4.0) |
+| `--json` | boolean | false | Output JSON (machine-readable) |
 
 ### hack version
 
@@ -1463,23 +1469,23 @@ Usage: `hack secrets <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                            |
-| ---------- | ---------------------------------- |
-| `set`      | Store a secret                     |
-| `get`      | Print a secret (exit 1 if missing) |
-| `delete`   | Delete a stored secret             |
+| Subcommand | Summary |
+| --- | --- |
+| `set` | Store a secret |
+| `get` | Print a secret (exit 1 if missing) |
+| `delete` | Delete a stored secret |
 
 Options (all subcommands):
 
-| Flag                  | Type   | Default    | Description                       |
-| --------------------- | ------ | ---------- | --------------------------------- |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
 | `--service <service>` | string | `hack-cli` | Override Bun.secrets service name |
 
 Arguments (set/get/delete):
 
-| Name   | Type   | Required | Description                       |
-| ------ | ------ | -------- | --------------------------------- |
-| `name` | string | no       | Secret name (prompted if omitted) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | no | Secret name (prompted if omitted) |
 
 ## Fun
 
@@ -1489,7 +1495,7 @@ Usage: `hack the planet [options]`
 
 Options:
 
-| Flag            | Type    | Default | Description       |
-| --------------- | ------- | ------- | ----------------- | ------ | ------- | ----------------- |
-| `--variant <cut | mash    | cycle   | random>`          | string | `cycle` | Animation variant |
-| `--loop`        | boolean | true    | Loop until Ctrl+C |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--variant <cut|mash|cycle|random>` | string | `cycle` | Animation variant |
+| `--loop` | boolean | true | Loop until Ctrl+C |
diff --git a/docs/extensions.md b/docs/extensions.md
index de9cf86b7..a2ef0b51c 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -13,7 +13,8 @@ If you just want remote access working, start here:
 hack remote setup
 ```
 
-The wizard enables the gateway for the current project, creates a token + QR, and can configure Cloudflare/Tailscale/SSH exposure in one flow.
+The wizard enables the gateway for the current project, creates a token + QR, and can configure
+Cloudflare/Tailscale/SSH exposure in one flow.
 
 ## Behavior
 
@@ -21,7 +22,8 @@ The wizard enables the gateway for the current project, creates a token + QR, an
 - Each extension provides a manifest + commands (`ExtensionDefinition`).
 - The CLI dispatches extension commands via `hack x <namespace> <command>`.
 - Global enablement lives in `~/.hack/hack.config.json` (`hack config set --global ...`).
-- Per-project overrides live in `.hack/hack.config.json` and typically win over global values (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
+- Per-project overrides live in `.hack/hack.config.json` and typically win over global values
+  (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
 - Built-in Gateway enablement is project-scoped: `controlPlane.gateway.enabled` opts a project into routing.
 
 ## Extension definition (API surface)
@@ -47,14 +49,14 @@ export type ExtensionCommand = {
 ```
 
 The `ExtensionCommandContext` includes:
-
 - `controlPlaneConfig` (parsed config)
 - `projectId` and `projectName` (when available)
 - `logger` and `cwd`
 
 ## Config + enablement
 
-Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by `src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
+Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by
+`src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
 
 Enable a global extension by id:
 
@@ -78,10 +80,10 @@ Shortcut for gateway (project-scoped):
 }
 ```
 
-Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config. Project overrides for these are ignored.
+Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config.
+Project overrides for these are ignored.
 
 CLI helpers:
-
 - `hack gateway enable` (sets both gateway + extension flags)
 - `hack gateway setup` (guided enable + optional writes + token creation + QR by default)
 - `hack config set --global 'controlPlane.extensions[\"dance.hack.gateway\"].enabled' true`
@@ -106,10 +108,10 @@ Use `hack x <namespace> help` to list commands.
 - GitHub: `hack x github connect|oauth-connect|disconnect|profiles|use|status|pr-upsert`
 - Linear: `hack x linear setup|connect|oauth-connect|disconnect|status|profiles|use|projects|project-bind|sync-issue|sync-project`
 
-Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also requires global `controlPlane.gateway.allowWrites = true`).
+Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also
+requires global `controlPlane.gateway.allowWrites = true`).
 
 Current gateway API surface (HTTP/WS):
-
 - `GET /v1/status`, `GET /v1/metrics`, `GET /v1/projects`, `GET /v1/ps`
 - `GET/POST /control-plane/projects/:id/jobs`
 - `GET /control-plane/projects/:id/jobs/:jobId`
@@ -120,7 +122,6 @@ Current gateway API surface (HTTP/WS):
 - `WS /control-plane/projects/:id/shells/:shellId/stream` (requires write token + allowWrites)
 
 Local auth service surface (daemon + global Caddy route):
-
 - `GET /health`
 - `GET /v1/auth/providers`
 - `GET /gh/start` (GitHub browser OAuth entrypoint)
@@ -129,14 +130,15 @@ Local auth service surface (daemon + global Caddy route):
 - `GET /v1/auth/github/start`
 - `GET /v1/auth/github/flows/:id`
 
-Interactive shell/TTY is available via the shell stream endpoints; use `hack x supervisor shell` or see protocol below.
+Interactive shell/TTY is available via the shell stream endpoints; use
+`hack x supervisor shell` or see protocol below.
 
 For full usage guidance and structured workflow patterns, see `gateway-api.md`.
 
 For exposure helpers, see the guides:
-
 - `guides/remote-cloudflare.md`
-- `guides/remote-tailscale.md` DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
+- `guides/remote-tailscale.md`
+DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
 
 ## Command reference
 
@@ -148,14 +150,13 @@ Usage: `hack x gateway token-create [options] [label]`
 
 Options:
 
-| Flag              | Type    | Default | Description                  |
-| ----------------- | ------- | ------- | ---------------------------- | ----------- |
-| `--scope <read    | write>` | string  | `read`                       | Token scope |
-| `--write`         | boolean | false   | Shortcut for `--scope write` |
-| `--label <label>` | string  | -       | Optional label               |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--scope <read|write>` | string | `read` | Token scope |
+| `--write` | boolean | false | Shortcut for `--scope write` |
+| `--label <label>` | string | - | Optional label |
 
 Notes:
-
 - The first non-flag argument is treated as the label if `--label` is not used.
 
 #### token-list
@@ -176,11 +177,11 @@ Usage: `hack x supervisor job-list [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                 |
-| ------------------ | ------- | ------- | --------------------------- |
-| `--project <name>` | string  | -       | Target a registered project |
-| `--path <dir>`     | string  | -       | Target a repo path          |
-| `--json`           | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--json` | boolean | false | Output JSON |
 
 #### job-create
 
@@ -188,14 +189,14 @@ Usage: `hack x supervisor job-create [options] -- <command...>`
 
 Options:
 
-| Flag                | Type    | Default   | Description                                  |
-| ------------------- | ------- | --------- | -------------------------------------------- |
-| `--project <name>`  | string  | -         | Target a registered project                  |
-| `--path <dir>`      | string  | -         | Target a repo path                           |
-| `--runner <name>`   | string  | `generic` | Runner name                                  |
-| `--cwd <path>`      | string  | -         | Working directory (relative to project root) |
-| `--env <KEY=VALUE>` | string  | -         | Environment override (repeatable)            |
-| `--json`            | boolean | false     | Output JSON                                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--runner <name>` | string | `generic` | Runner name |
+| `--cwd <path>` | string | - | Working directory (relative to project root) |
+| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
+| `--json` | boolean | false | Output JSON |
 
 ### GitHub extension (`hack x github`)
 
@@ -258,9 +259,10 @@ hack x github pr-upsert \
 ```
 
 Notes:
-
-- Profile config lives at: `controlPlane.extensions["dance.hack.github"].config.profiles`.
-- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
+- Profile config lives at:
+  `controlPlane.extensions["dance.hack.github"].config.profiles`.
+- Profile selection precedence is:
+  `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
 - Keychain storage uses profile-specific `authRef` + `service`.
 - Token resolution order is keychain first, then environment fallback (`tokenEnv`).
 - If token metadata includes `expiresAt`, auth resolution attempts automatic GitHub App refresh using profile `appId`, `installationId`, and private key source.
@@ -339,7 +341,8 @@ Detailed design and sequencing live in:
 
 ### Linear extension (`hack x linear`)
 
-Linear integration supports multiple auth profiles, project-level binding, and manual sync in both directions between Linear issues and hack tickets.
+Linear integration supports multiple auth profiles, project-level binding, and manual sync in both
+directions between Linear issues and hack tickets.
 
 Quick start:
 
@@ -362,9 +365,11 @@ hack x linear sync-project --from hack --owner both
 ```
 
 Notes:
-
-- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.linear.profile` -> `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
-- Project mapping is stored in project config: `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
+- Profile selection precedence is:
+  `--profile` -> `controlPlane.routing.overrides.linear.profile` ->
+  `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
+- Project mapping is stored in project config:
+  `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
 - Sync is manual by default (`sync-issue` / `sync-project`); there is no background autosync yet.
 - Ticket provenance is preserved during sync via `owner`, `source`, `tags`, and `external*` linkage fields.
 - `hack x linear connect` uses token mode when `--token`/`--stdin`/`$HACK_LINEAR_API_TOKEN` is present, and otherwise falls back to browser OAuth.
@@ -377,7 +382,8 @@ Notes:
 - Auth-broker Linear endpoints:
   - OAuth callback page: `/linear/callback`
   - Webhook ingest: `/linear/webhooks` (legacy alias: `/v1/integrations/linear/webhook`)
-- Sync toggles are configurable at `controlPlane.extensions["dance.hack.linear"].config.sync`:
+- Sync toggles are configurable at
+  `controlPlane.extensions["dance.hack.linear"].config.sync`:
   - `labels` (default `false`)
   - `statuses` (default `true`)
   - `dependencies` (default `true`)
@@ -390,11 +396,11 @@ Usage: `hack x supervisor job-show <job-id> [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                 |
-| ------------------ | ------- | ------- | --------------------------- |
-| `--project <name>` | string  | -       | Target a registered project |
-| `--path <dir>`     | string  | -       | Target a repo path          |
-| `--json`           | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--json` | boolean | false | Output JSON |
 
 #### job-cancel
 
@@ -402,10 +408,10 @@ Usage: `hack x supervisor job-cancel <job-id> [options]`
 
 Options:
 
-| Flag               | Type   | Default | Description                 |
-| ------------------ | ------ | ------- | --------------------------- |
-| `--project <name>` | string | -       | Target a registered project |
-| `--path <dir>`     | string | -       | Target a repo path          |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
 
 #### job-tail
 
@@ -413,15 +419,15 @@ Usage: `hack x supervisor job-tail <job-id> [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                 |
-| ------------------ | ------- | ------- | --------------------------- |
-| `--project <name>` | string  | -       | Target a registered project |
-| `--path <dir>`     | string  | -       | Target a repo path          |
-| `--follow`         | boolean | true    | Follow logs (default)       |
-| `--no-follow`      | boolean | false   | Print logs and exit         |
-| `--logs-from <n>`  | number  | 0       | Resume from log offset      |
-| `--from <n>`       | number  | 0       | Alias for `--logs-from`     |
-| `--json`           | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--follow` | boolean | true | Follow logs (default) |
+| `--no-follow` | boolean | false | Print logs and exit |
+| `--logs-from <n>` | number | 0 | Resume from log offset |
+| `--from <n>` | number | 0 | Alias for `--logs-from` |
+| `--json` | boolean | false | Output JSON |
 
 #### job-attach
 
@@ -429,16 +435,16 @@ Usage: `hack x supervisor job-attach <job-id> [options]`
 
 Options:
 
-| Flag                | Type    | Default | Description                 |
-| ------------------- | ------- | ------- | --------------------------- |
-| `--project <name>`  | string  | -       | Target a registered project |
-| `--path <dir>`      | string  | -       | Target a repo path          |
-| `--follow`          | boolean | true    | Follow logs (default)       |
-| `--no-follow`       | boolean | false   | Print logs and exit         |
-| `--logs-from <n>`   | number  | 0       | Resume from log offset      |
-| `--from <n>`        | number  | 0       | Alias for `--logs-from`     |
-| `--events-from <n>` | number  | 0       | Resume from event sequence  |
-| `--json`            | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--follow` | boolean | true | Follow logs (default) |
+| `--no-follow` | boolean | false | Print logs and exit |
+| `--logs-from <n>` | number | 0 | Resume from log offset |
+| `--from <n>` | number | 0 | Alias for `--logs-from` |
+| `--events-from <n>` | number | 0 | Resume from event sequence |
+| `--json` | boolean | false | Output JSON |
 
 #### shell
 
@@ -446,21 +452,20 @@ Usage: `hack x supervisor shell [options]`
 
 Options:
 
-| Flag                | Type   | Default                 | Description                       |
-| ------------------- | ------ | ----------------------- | --------------------------------- |
-| `--project <name>`  | string | -                       | Target a registered project       |
-| `--project-id <id>` | string | -                       | Target by project id (gateway)    |
-| `--path <dir>`      | string | -                       | Target a repo path                |
-| `--gateway <url>`   | string | `http://127.0.0.1:7788` | Gateway URL                       |
-| `--token <token>`   | string | -                       | Gateway write token               |
-| `--shell <path>`    | string | -                       | Shell path                        |
-| `--cwd <path>`      | string | -                       | Working directory                 |
-| `--cols <n>`        | number | -                       | Terminal columns                  |
-| `--rows <n>`        | number | -                       | Terminal rows                     |
-| `--env <KEY=VALUE>` | string | -                       | Environment override (repeatable) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--project-id <id>` | string | - | Target by project id (gateway) |
+| `--path <dir>` | string | - | Target a repo path |
+| `--gateway <url>` | string | `http://127.0.0.1:7788` | Gateway URL |
+| `--token <token>` | string | - | Gateway write token |
+| `--shell <path>` | string | - | Shell path |
+| `--cwd <path>` | string | - | Working directory |
+| `--cols <n>` | number | - | Terminal columns |
+| `--rows <n>` | number | - | Terminal rows |
+| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
 
 Notes:
-
 - `--project` and `--project-id` are mutually exclusive.
 
 ### Cloudflare extension (`hack x cloudflare`)
@@ -471,15 +476,15 @@ Usage: `hack x cloudflare tunnel-print [options]`
 
 Options:
 
-| Flag                        | Type   | Default                 | Description                  |
-| --------------------------- | ------ | ----------------------- | ---------------------------- |
-| `--hostname <host>`         | string | -                       | Gateway hostname             |
-| `--tunnel <name>`           | string | `hack-gateway`          | Tunnel name                  |
-| `--origin <url>`            | string | `http://127.0.0.1:7788` | Gateway origin               |
-| `--ssh-hostname <host>`     | string | -                       | SSH hostname (optional)      |
-| `--ssh-origin <url>`        | string | `ssh://127.0.0.1:22`    | SSH origin                   |
-| `--credentials-file <path>` | string | -                       | Cloudflared credentials file |
-| `--out <path>`              | string | -                       | Write config to a file       |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--hostname <host>` | string | - | Gateway hostname |
+| `--tunnel <name>` | string | `hack-gateway` | Tunnel name |
+| `--origin <url>` | string | `http://127.0.0.1:7788` | Gateway origin |
+| `--ssh-hostname <host>` | string | - | SSH hostname (optional) |
+| `--ssh-origin <url>` | string | `ssh://127.0.0.1:22` | SSH origin |
+| `--credentials-file <path>` | string | - | Cloudflared credentials file |
+| `--out <path>` | string | - | Write config to a file |
 
 #### tunnel-setup
 
@@ -506,11 +511,11 @@ Usage: `hack x cloudflare tunnel-start [options]`
 
 Options:
 
-| Flag              | Type   | Default                     | Description          |
-| ----------------- | ------ | --------------------------- | -------------------- |
-| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path          |
-| `--out <path>`    | string | -                           | Alias for `--config` |
-| `--tunnel <name>` | string | -                           | Override tunnel name |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path |
+| `--out <path>` | string | - | Alias for `--config` |
+| `--tunnel <name>` | string | - | Override tunnel name |
 
 #### tunnel-stop
 
@@ -522,10 +527,10 @@ Usage: `hack x cloudflare access-setup [options]`
 
 Options:
 
-| Flag                    | Type   | Default | Description  |
-| ----------------------- | ------ | ------- | ------------ |
-| `--ssh-hostname <host>` | string | -       | SSH hostname |
-| `--user <user>`         | string | -       | SSH username |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--ssh-hostname <host>` | string | - | SSH hostname |
+| `--user <user>` | string | - | SSH username |
 
 ### Tailscale extension (`hack x tailscale`)
 
@@ -558,7 +563,6 @@ Usage: `hack x tailscale oauth-disconnect [--auth-ref <ref>] [--json]`
 Usage: `hack x tailscale ip [args...]`
 
 Notes:
-
 - `status` and `ip` forward extra args directly to `tailscale`.
 - `ip` defaults to `-4` when no args are provided.
 
@@ -607,18 +611,17 @@ The gateway binds to `127.0.0.1` by default. Expose it through one of:
 - SSH tunnel (ad‑hoc): `ssh -L 7788:127.0.0.1:7788 <host>`
 - Zero Trust/VPN (persistent): Tailscale, Cloudflare, etc. targeting the gateway port
 - Optional Caddy route for local convenience (`https://gateway.hack`):
-  - Add a small labeled container in the global Caddy compose that proxies to `host.docker.internal:7788` (or `host-gateway` on Linux).
+  - Add a small labeled container in the global Caddy compose that proxies to
+    `host.docker.internal:7788` (or `host-gateway` on Linux).
 
 Keep tokens read-only unless you explicitly need writes.
 
 Recommended order:
-
-1. Start with SSH tunneling for quick remote access.
-2. Move to a private Zero Trust/VPN network once you want persistent access.
-3. Add the Caddy route only for nicer local URLs (not required for remote access).
+1) Start with SSH tunneling for quick remote access.
+2) Move to a private Zero Trust/VPN network once you want persistent access.
+3) Add the Caddy route only for nicer local URLs (not required for remote access).
 
 Remote helper commands:
-
 - `hack remote status` shows gateway + exposure status.
 - `hack remote qr` emits QR payloads for SSH or gateway clients.
 

From 4f1251dff1c67d8312de3eba39c64508f7d28cef Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:57:59 +0000
Subject: [PATCH 091/134] docs: narrow github workflow scope diff

---
 docs/cli.md        | 814 +++++++++++++++++++++++----------------------
 docs/extensions.md | 243 +++++++-------
 2 files changed, 527 insertions(+), 530 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 53c3e3234..247f0f85c 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,6 +1,7 @@
 # CLI Reference
 
-This reference mirrors the CLI spec in `src/cli/spec.ts`. Run `hack help` or `hack help <command>` for interactive help.
+This reference mirrors the CLI spec in `src/cli/spec.ts`.
+Run `hack help` or `hack help <command>` for interactive help.
 
 ## Conventions
 
@@ -60,17 +61,17 @@ Usage: `hack global <subcommand>`
 
 Subcommands:
 
-| Subcommand   | Summary                                                      |
-| ------------ | ------------------------------------------------------------ |
-| `install`    | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy     |
-| `up`         | Start global infra containers                                |
-| `down`       | Stop global infra containers                                 |
-| `status`     | Show status for global infra (containers + networks)         |
-| `logs`       | Tail global infra logs (`caddy`, `grafana`, `loki`, `alloy`) |
-| `ca`         | Export Caddy Local CA cert (print path or PEM)               |
-| `cert`       | Generate local TLS certs via mkcert (for non-Caddy services) |
-| `trust`      | Trust Caddy Local CA (macOS) so https://\*.hack is trusted   |
-| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards)          |
+| Subcommand | Summary |
+| --- | --- |
+| `install` | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy |
+| `up` | Start global infra containers |
+| `down` | Stop global infra containers |
+| `status` | Show status for global infra (containers + networks) |
+| `logs` | Tail global infra logs (caddy|grafana|loki|alloy) |
+| `ca` | Export Caddy Local CA cert (print path or PEM) |
+| `cert` | Generate local TLS certs via mkcert (for non-Caddy services) |
+| `trust` | Trust Caddy Local CA (macOS) so https://*.hack is trusted |
+| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards) |
 
 #### hack global logs
 
@@ -78,18 +79,18 @@ Usage: `hack global logs [service] [options]`
 
 Arguments:
 
-| Name      | Type   | Required | Description                                                |
-| --------- | ------ | -------- | ---------------------------------------------------------- |
-| `service` | string | no       | Filter to one global service (caddy, grafana, loki, alloy) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `service` | string | no | Filter to one global service (caddy, grafana, loki, alloy) |
 
 Options:
 
-| Flag             | Type    | Default | Description                                               |
-| ---------------- | ------- | ------- | --------------------------------------------------------- |
-| `-f`, `--follow` | boolean | true    | Follow logs (default)                                     |
-| `--no-follow`    | boolean | false   | Print logs and exit                                       |
-| `--tail <n>`     | number  | 200     | Tail last N log lines                                     |
-| `--pretty`       | boolean | false   | Pretty-print logs (best-effort JSON parsing + formatting) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-f`, `--follow` | boolean | true | Follow logs (default) |
+| `--no-follow` | boolean | false | Print logs and exit |
+| `--tail <n>` | number | 200 | Tail last N log lines |
+| `--pretty` | boolean | false | Pretty-print logs (best-effort JSON parsing + formatting) |
 
 #### hack global ca
 
@@ -97,9 +98,9 @@ Usage: `hack global ca [options]`
 
 Options:
 
-| Flag      | Type    | Default | Description                                                    |
-| --------- | ------- | ------- | -------------------------------------------------------------- |
-| `--print` | boolean | false   | Print the CA cert PEM to stdout (instead of printing its path) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--print` | boolean | false | Print the CA cert PEM to stdout (instead of printing its path) |
 
 #### hack global cert
 
@@ -107,16 +108,16 @@ Usage: `hack global cert <hosts...> [options]`
 
 Arguments:
 
-| Name    | Type     | Required | Description                                 |
-| ------- | -------- | -------- | ------------------------------------------- |
-| `hosts` | string[] | yes      | One or more hostnames to generate certs for |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `hosts` | string[] | yes | One or more hostnames to generate certs for |
 
 Options:
 
-| Flag          | Type    | Default         | Description                                 |
-| ------------- | ------- | --------------- | ------------------------------------------- |
-| `--install`   | boolean | false           | Run mkcert -install before generating certs |
-| `--out <dir>` | string  | `~/.hack/certs` | Directory for generated cert/key            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--install` | boolean | false | Run mkcert -install before generating certs |
+| `--out <dir>` | string | `~/.hack/certs` | Directory for generated cert/key |
 
 ### hack projects
 
@@ -141,9 +142,9 @@ Usage: `hack projects prune [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                                   |
-| ------------------ | ------- | ------- | --------------------------------------------- |
-| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
 
 ### hack status
 
@@ -151,12 +152,12 @@ Usage: `hack status [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                                   |
-| ------------------ | ------- | ------- | --------------------------------------------- |
-| `--project <name>` | string  | -       | Filter to a registered project name           |
-| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
-| `--all`            | boolean | false   | Include unregistered docker compose projects  |
-| `--json`           | boolean | false   | Output JSON (machine-readable)                |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Filter to a registered project name |
+| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
+| `--all` | boolean | false | Include unregistered docker compose projects |
+| `--json` | boolean | false | Output JSON (machine-readable) |
 
 ### hack usage
 
@@ -205,7 +206,7 @@ Options:
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `-d`, `--detach` | boolean | false | Run in background (docker compose up -d) |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto \| local \| remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack down
 
@@ -219,7 +220,7 @@ Options:
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto \| local \| remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack restart
 
@@ -233,7 +234,7 @@ Options:
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto \| local \| remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack ps
 
@@ -255,9 +256,9 @@ Usage: `hack logs [service] [options]`
 
 Arguments:
 
-| Name      | Type   | Required | Description                                        |
-| --------- | ------ | -------- | -------------------------------------------------- |
-| `service` | string | no       | Filter logs by service (shortcut for `--services`) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `service` | string | no | Filter logs by service (shortcut for `--services`) |
 
 Options:
 
@@ -291,10 +292,10 @@ Usage: `hack run <service> [-- <cmd...>] [options]`
 
 Arguments:
 
-| Name      | Type     | Required | Description                                     |
-| --------- | -------- | -------- | ----------------------------------------------- |
-| `service` | string   | yes      | Compose service name                            |
-| `cmd`     | string[] | no       | Command to run (defaults to service entrypoint) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `service` | string | yes | Compose service name |
+| `cmd` | string[] | no | Command to run (defaults to service entrypoint) |
 
 Options:
 
@@ -312,18 +313,18 @@ Usage: `hack open [target] [options]`
 
 Arguments:
 
-| Name     | Type   | Required | Description                                         |
-| -------- | ------ | -------- | --------------------------------------------------- |
-| `target` | string | no       | `www` (default), `logs`, a subdomain, or a full URL |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `target` | string | no | `www` (default), `logs`, a subdomain, or a full URL |
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string  | -       | Target a registered project by name            |
-| `--branch <name>`    | string  | -       | Run against a branch-specific instance         |
-| `--json`             | boolean | false   | Output JSON with `{ "url": "..." }`            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--branch <name>` | string | - | Run against a branch-specific instance |
+| `--json` | boolean | false | Output JSON with `{ "url": "..." }` |
 
 Notes:
 
@@ -338,10 +339,10 @@ Usage: `hack tui [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 Notes:
 
@@ -353,12 +354,12 @@ Usage: `hack branch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                  |
-| ---------- | ---------------------------------------- |
-| `add`      | Register a branch alias for this project |
-| `list`     | List registered branch aliases           |
-| `remove`   | Remove a branch alias                    |
-| `open`     | Open the branch host in a browser        |
+| Subcommand | Summary |
+| --- | --- |
+| `add` | Register a branch alias for this project |
+| `list` | List registered branch aliases |
+| `remove` | Remove a branch alias |
+| `open` | Open the branch host in a browser |
 
 #### hack branch add
 
@@ -366,17 +367,17 @@ Usage: `hack branch add <name> [options]`
 
 Arguments:
 
-| Name   | Type   | Required | Description          |
-| ------ | ------ | -------- | -------------------- |
-| `name` | string | yes      | Branch name or alias |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | yes | Branch name or alias |
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
-| `--note <text>`      | string | -       | Optional note for the branch entry             |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--note <text>` | string | - | Optional note for the branch entry |
 
 #### hack branch list
 
@@ -384,10 +385,10 @@ Usage: `hack branch list [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack branch remove
 
@@ -395,16 +396,16 @@ Usage: `hack branch remove <name> [options]`
 
 Arguments:
 
-| Name   | Type   | Required | Description          |
-| ------ | ------ | -------- | -------------------- |
-| `name` | string | yes      | Branch name or alias |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | yes | Branch name or alias |
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack branch open
 
@@ -412,16 +413,16 @@ Usage: `hack branch open <name> [options]`
 
 Arguments:
 
-| Name   | Type   | Required | Description          |
-| ------ | ------ | -------- | -------------------- |
-| `name` | string | yes      | Branch name or alias |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | yes | Branch name or alias |
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 ### hack config
 
@@ -429,10 +430,10 @@ Usage: `hack config <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                            |
-| ---------- | ---------------------------------- |
-| `get`      | Read a value from hack.config.json |
-| `set`      | Update a value in hack.config.json |
+| Subcommand | Summary |
+| --- | --- |
+| `get` | Read a value from hack.config.json |
+| `set` | Update a value in hack.config.json |
 
 #### hack config get
 
@@ -440,17 +441,17 @@ Usage: `hack config get <key> [options]`
 
 Arguments:
 
-| Name  | Type   | Required | Description                             |
-| ----- | ------ | -------- | --------------------------------------- |
-| `key` | string | yes      | Dot path (e.g. `logs.snapshot_backend`) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string  | -       | Target a registered project by name            |
-| `--global`           | boolean | false   | Read global `~/.hack/hack.config.json`         |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--global` | boolean | false | Read global `~/.hack/hack.config.json` |
 
 #### hack config set
 
@@ -458,18 +459,18 @@ Usage: `hack config set <key> <value> [options]`
 
 Arguments:
 
-| Name    | Type   | Required | Description                                          |
-| ------- | ------ | -------- | ---------------------------------------------------- |
-| `key`   | string | yes      | Dot path (e.g. `logs.snapshot_backend`)              |
-| `value` | string | yes      | JSON value or raw string (parsed as JSON when valid) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
+| `value` | string | yes | JSON value or raw string (parsed as JSON when valid) |
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string  | -       | Target a registered project by name            |
-| `--global`           | boolean | false   | Write global `~/.hack/hack.config.json`        |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--global` | boolean | false | Write global `~/.hack/hack.config.json` |
 
 ### hack env
 
@@ -477,12 +478,12 @@ Usage: `hack env <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                            |
-| ---------- | -------------------------------------------------- |
-| `list`     | List env contract vars and resolution state        |
-| `set`      | Set an env value (.hack/.env or secret backend)    |
-| `unset`    | Unset an env value (.hack/.env and secret backend) |
-| `backend`  | Manage env/secret backend strategy                 |
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List env contract vars and resolution state |
+| `set` | Set an env value (.hack/.env or secret backend) |
+| `unset` | Unset an env value (.hack/.env and secret backend) |
+| `backend` | Manage env/secret backend strategy |
 
 #### hack env list
 
@@ -490,12 +491,12 @@ Usage: `hack env list [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                       |
-| -------------------- | ------- | ------- | ------------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)    |
-| `--project <name>`   | string  | -       | Target a registered project by name               |
-| `--json`             | boolean | false   | Output JSON (machine-readable)                    |
-| `--show-secrets`     | boolean | false   | Print secret values (secret backend) in plaintext |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--show-secrets` | boolean | false | Print secret values (secret backend) in plaintext |
 
 #### hack env set
 
@@ -517,10 +518,10 @@ Usage: `hack env unset [key] [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack env backend
 
@@ -528,10 +529,10 @@ Usage: `hack env backend <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                     |
-| ---------- | ------------------------------------------- |
-| `status`   | Show configured env/secret backend strategy |
-| `use`      | Select env/secret backend strategy          |
+| Subcommand | Summary |
+| --- | --- |
+| `status` | Show configured env/secret backend strategy |
+| `use` | Select env/secret backend strategy |
 
 #### hack env backend status
 
@@ -539,9 +540,9 @@ Usage: `hack env backend status [options]`
 
 Options:
 
-| Flag     | Type    | Default | Description                    |
-| -------- | ------- | ------- | ------------------------------ |
-| `--json` | boolean | false   | Output JSON (machine-readable) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
 
 #### hack env backend use
 
@@ -551,7 +552,7 @@ Options:
 
 | Flag | Type | Default | Description |
 | --- | --- | --- | --- |
-| `--provider <aws \| gcp \| azure \| vault>` | string | - | Cloud provider when backend is `cloud` |
+| `--provider <aws|gcp|azure|vault>` | string | - | Cloud provider when backend is `cloud` |
 | `--store-path <path>` | string | - | Encrypted file path when backend is `encrypted_file` |
 | `--secret-project <id>` | string | - | Optional cloud account/project identifier |
 | `--secret-prefix <prefix>` | string | - | Optional cloud secret name prefix |
@@ -565,16 +566,16 @@ With no subcommand, opens an interactive picker of active sessions and available
 
 Subcommands:
 
-| Subcommand | Summary                                    |
-| ---------- | ------------------------------------------ |
-| `list`     | List active sessions                       |
-| `start`    | Start or attach to a session for a project |
-| `stop`     | Stop (kill) a session                      |
-| `attach`   | Attach to an existing session              |
-| `exec`     | Execute a command in a session             |
-| `panes`    | List panes in a tmux session               |
-| `capture`  | Capture recent output from a tmux session  |
-| `tail`     | Tail output from a tmux session            |
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List active sessions |
+| `start` | Start or attach to a session for a project |
+| `stop` | Stop (kill) a session |
+| `attach` | Attach to an existing session |
+| `exec` | Execute a command in a session |
+| `panes` | List panes in a tmux session |
+| `capture` | Capture recent output from a tmux session |
+| `tail` | Tail output from a tmux session |
 
 #### hack session start
 
@@ -582,11 +583,11 @@ Usage: `hack session start [project] [options]`
 
 Options:
 
-| Flag              | Type    | Default | Description                                   |
-| ----------------- | ------- | ------- | --------------------------------------------- |
-| `--up`            | boolean | false   | Run hack up -d before attaching               |
-| `--new`           | boolean | false   | Force create new session even if one exists   |
-| `--name <suffix>` | string  | -       | Custom suffix for new session (e.g., agent-1) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--up` | boolean | false | Run hack up -d before attaching |
+| `--new` | boolean | false | Force create new session even if one exists |
+| `--name <suffix>` | string | - | Custom suffix for new session (e.g., agent-1) |
 
 #### hack session panes
 
@@ -594,10 +595,10 @@ Usage: `hack session panes <session> [options]`
 
 Options:
 
-| Flag       | Type    | Default | Description                          |
-| ---------- | ------- | ------- | ------------------------------------ |
-| `--json`   | boolean | false   | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false   | Output human-friendly text           |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false | Output human-friendly text |
 
 #### hack session capture
 
@@ -605,12 +606,12 @@ Usage: `hack session capture <session> [options]`
 
 Options:
 
-| Flag                | Type    | Default | Description                             |
-| ------------------- | ------- | ------- | --------------------------------------- |
-| `--target <target>` | string  | -       | Tmux pane target (default: active pane) |
-| `--lines <n>`       | number  | 200     | Number of lines to capture              |
-| `--json`            | boolean | false   | Output NDJSON stream (start/log/end)    |
-| `--pretty`          | boolean | false   | Output human-friendly text              |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--target <target>` | string | - | Tmux pane target (default: active pane) |
+| `--lines <n>` | number | 200 | Number of lines to capture |
+| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false | Output human-friendly text |
 
 #### hack session tail
 
@@ -618,14 +619,14 @@ Usage: `hack session tail <session> [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                             |
-| -------------------- | ------- | ------- | --------------------------------------- |
-| `--target <target>`  | string  | -       | Tmux pane target (default: active pane) |
-| `--lines <n>`        | number  | 200     | Number of lines to capture              |
-| `--interval-ms <ms>` | number  | 500     | Polling interval in milliseconds        |
-| `--max-ms <ms>`      | number  | 5000    | Stop tailing after N milliseconds       |
-| `--json`             | boolean | false   | Output NDJSON stream (start/log/end)    |
-| `--pretty`           | boolean | false   | Output human-friendly text              |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--target <target>` | string | - | Tmux pane target (default: active pane) |
+| `--lines <n>` | number | 200 | Number of lines to capture |
+| `--interval-ms <ms>` | number | 500 | Polling interval in milliseconds |
+| `--max-ms <ms>` | number | 5000 | Stop tailing after N milliseconds |
+| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false | Output human-friendly text |
 
 ### hack ssh
 
@@ -633,25 +634,27 @@ Usage: `hack ssh [session] [options]`
 
 Options:
 
-| Flag                  | Type    | Default | Description                                  |
-| --------------------- | ------- | ------- | -------------------------------------------- |
-| `-H`, `--host <host>` | string  | -       | SSH host (hostname or IP)                    |
-| `-u`, `--user <user>` | string  | -       | SSH username                                 |
-| `-t`, `--tailscale`   | boolean | false   | Use Tailscale SSH                            |
-| `-d`, `--direct`      | boolean | false   | Use direct SSH (requires --host)             |
-| `-p`, `--port <port>` | string  | -       | SSH port for direct connection (default: 22) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-H`, `--host <host>` | string | - | SSH host (hostname or IP) |
+| `-u`, `--user <user>` | string | - | SSH username |
+| `-t`, `--tailscale` | boolean | false | Use Tailscale SSH |
+| `-d`, `--direct` | boolean | false | Use direct SSH (requires --host) |
+| `-p`, `--port <port>` | string | - | SSH port for direct connection (default: 22) |
 
 ### hack tickets
 
 Usage: `hack tickets <args...>`
 
-`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`). Run `hack tickets` with no args to see available subcommands.
+`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`).
+Run `hack tickets` with no args to see available subcommands.
 
 ### hack linear
 
 Usage: `hack linear <args...>`
 
-`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`). Run `hack linear` with no args to see available subcommands.
+`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`).
+Run `hack linear` with no args to see available subcommands.
 
 ## Internal commands
 
@@ -661,8 +664,8 @@ Usage: `hack internal <subcommand>`
 
 Subcommands:
 
-| Subcommand    | Summary                             |
-| ------------- | ----------------------------------- |
+| Subcommand | Summary |
+| --- | --- |
 | `extra-hosts` | Manage internal Compose extra_hosts |
 
 #### hack internal extra-hosts
@@ -671,17 +674,17 @@ Usage: `hack internal extra-hosts <subcommand> [options]`
 
 Options:
 
-| Flag                  | Type   | Default | Description                       |
-| --------------------- | ------ | ------- | --------------------------------- |
-| `-p`, `--path <path>` | string | -       | Start directory (defaults to cwd) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <path>` | string | - | Start directory (defaults to cwd) |
 
 Subcommands:
 
-| Subcommand | Summary                              |
-| ---------- | ------------------------------------ |
-| `set`      | Set an internal extra_hosts entry    |
-| `unset`    | Remove an internal extra_hosts entry |
-| `list`     | List internal extra_hosts entries    |
+| Subcommand | Summary |
+| --- | --- |
+| `set` | Set an internal extra_hosts entry |
+| `unset` | Remove an internal extra_hosts entry |
+| `list` | List internal extra_hosts entries |
 
 #### hack internal extra-hosts set
 
@@ -703,11 +706,11 @@ Usage: `hack gateway <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                   |
-| ---------- | ----------------------------------------- |
-| `enable`   | Enable the gateway and start hackd        |
-| `setup`    | Guided gateway setup (enable + token)     |
-| `disable`  | Disable the gateway (does not stop hackd) |
+| Subcommand | Summary |
+| --- | --- |
+| `enable` | Enable the gateway and start hackd |
+| `setup` | Guided gateway setup (enable + token) |
+| `disable` | Disable the gateway (does not stop hackd) |
 
 #### hack gateway enable
 
@@ -715,10 +718,10 @@ Usage: `hack gateway enable [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack gateway setup
 
@@ -726,13 +729,13 @@ Usage: `hack gateway setup [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                         |
-| -------------------- | ------- | ------- | --------------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
-| `--project <name>`   | string  | -       | Target a registered project by name                 |
-| `--qr`               | boolean | true    | Force QR output after setup (default)               |
-| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
-| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--qr` | boolean | true | Force QR output after setup (default) |
+| `--no-qr` | boolean | false | Skip QR output after setup |
+| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
 
 #### hack gateway disable
 
@@ -740,10 +743,10 @@ Usage: `hack gateway disable [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 ### hack node
 
@@ -751,20 +754,20 @@ Usage: `hack node <subcommand>`
 
 Subcommands:
 
-| Subcommand     | Summary                                                       |
-| -------------- | ------------------------------------------------------------- |
-| `init`         | Initialize this host as a node and emit enrollment bundle     |
-| `pair`         | Pair node with one-command or expiring verification-code flow |
-| `ssh`          | Manage SSH bootstrap for node pairing and remote runs         |
-| `add`          | Add a node from an enrollment bundle                          |
-| `list`         | List registered nodes                                         |
-| `status`       | Probe node health and report live status                      |
-| `use`          | Set default node                                              |
-| `remove`       | Remove node registration                                      |
-| `workspace`    | Inspect and repair node workspace map entries                 |
-| `routes`       | Inspect and repair controller-side remote route bridge        |
-| `provider`     | Manage provider-specific node bootstrap workflows             |
-| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints    |
+| Subcommand | Summary |
+| --- | --- |
+| `init` | Initialize this host as a node and emit enrollment bundle |
+| `pair` | Pair node with one-command or expiring verification-code flow |
+| `ssh` | Manage SSH bootstrap for node pairing and remote runs |
+| `add` | Add a node from an enrollment bundle |
+| `list` | List registered nodes |
+| `status` | Probe node health and report live status |
+| `use` | Set default node |
+| `remove` | Remove node registration |
+| `workspace` | Inspect and repair node workspace map entries |
+| `routes` | Inspect and repair controller-side remote route bridge |
+| `provider` | Manage provider-specific node bootstrap workflows |
+| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints |
 
 Examples:
 
@@ -869,12 +872,12 @@ Usage: `hack node workspace <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                                |
-| ---------- | ------------------------------------------------------ |
-| `list`     | List node-local workspace map entries                  |
-| `resolve`  | Resolve a map entry by controller project selector     |
-| `attach`   | Attach an existing local workspace to project selector |
-| `remove`   | Remove a map entry by project selector                 |
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List node-local workspace map entries |
+| `resolve` | Resolve a map entry by controller project selector |
+| `attach` | Attach an existing local workspace to project selector |
+| `remove` | Remove a map entry by project selector |
 
 Examples:
 
@@ -891,10 +894,10 @@ Usage: `hack node routes <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                             |
-| ---------- | --------------------------------------------------- |
-| `status`   | Show controller-side remote route bridge state      |
-| `repair`   | Re-render and re-apply persisted route bridge stack |
+| Subcommand | Summary |
+| --- | --- |
+| `status` | Show controller-side remote route bridge state |
+| `repair` | Re-render and re-apply persisted route bridge stack |
 
 Examples:
 
@@ -910,11 +913,11 @@ Usage: `hack dispatch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                  |
-| ---------- | ---------------------------------------- |
-| `run`      | Dispatch a command to a node workspace   |
-| `status`   | Show dispatched run status               |
-| `logs`     | Show or follow persisted/remote run logs |
+| Subcommand | Summary |
+| --- | --- |
+| `run` | Dispatch a command to a node workspace |
+| `status` | Show dispatched run status |
+| `logs` | Show or follow persisted/remote run logs |
 
 #### hack dispatch run
 
@@ -924,14 +927,14 @@ Options:
 
 | Flag | Type | Default | Description |
 | --- | --- | --- | --- |
-| `--project <name \| id>` | string | - | Project name or id |
-| `--node <id \| default \| auto>` | string | auto | Target node id, or use default/auto |
+| `--project <name|id>` | string | - | Project name or id |
+| `--node <id|default|auto>` | string | auto | Target node id, or use default/auto |
 | `--provider <provider>` | string | - | Provider route override used when resolving profile/bootstrap intent |
 | `--profile <profile-id>` | string | - | Provider profile route override |
 | `--bootstrap-if-needed` | boolean | false | Allow guarded provider bootstrap handoff when no reachable node is found |
 | `--branch <branch>` | string | current | Target branch on selected node |
 | `--ticket <ticket-id>` | string | - | Ticket id to associate with run metadata |
-| `--runner <generic \| codex \| claude \| cursor>` | string | `generic` | Runner identity for policy and audit |
+| `--runner <generic|codex|claude|cursor>` | string | `generic` | Runner identity for policy and audit |
 | `--approve` | boolean | false | Approve high/critical risk commands non-interactively |
 | `--pr` | boolean | false | Push branch + create/update GitHub PR on successful run |
 | `--pr-base <branch>` | string | `main` | Base branch used with `--pr` |
@@ -978,12 +981,12 @@ If you run `hack remote` with no subcommand, it prints status and offers to run
 
 Subcommands:
 
-| Subcommand | Summary                              |
-| ---------- | ------------------------------------ |
-| `setup`    | Run the guided gateway setup         |
-| `status`   | Show remote/gateway status           |
-| `monitor`  | Open a remote status TUI             |
-| `qr`       | Print a QR payload for remote access |
+| Subcommand | Summary |
+| --- | --- |
+| `setup` | Run the guided gateway setup |
+| `status` | Show remote/gateway status |
+| `monitor` | Open a remote status TUI |
+| `qr` | Print a QR payload for remote access |
 
 #### hack remote setup
 
@@ -991,13 +994,13 @@ Usage: `hack remote setup [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                         |
-| -------------------- | ------- | ------- | --------------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
-| `--project <name>`   | string  | -       | Target a registered project by name                 |
-| `--qr`               | boolean | true    | Force QR output after setup (default)               |
-| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
-| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
+| `--qr` | boolean | true | Force QR output after setup (default) |
+| `--no-qr` | boolean | false | Skip QR output after setup |
+| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
 
 #### hack remote status
 
@@ -1005,10 +1008,10 @@ Usage: `hack remote status [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack remote monitor
 
@@ -1016,10 +1019,10 @@ Usage: `hack remote monitor [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
-| `--project <name>`   | string | -       | Target a registered project by name            |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--project <name>` | string | - | Target a registered project by name |
 
 #### hack remote qr
 
@@ -1045,9 +1048,9 @@ Usage: `hack x <namespace> <command> [args...]`
 
 Arguments:
 
-| Name   | Type     | Required | Description                             |
-| ------ | -------- | -------- | --------------------------------------- |
-| `args` | string[] | no       | Extension command args (passed through) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `args` | string[] | no | Extension command args (passed through) |
 
 Notes:
 
@@ -1062,15 +1065,15 @@ Usage: `hack setup <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                                |
-| ---------- | ------------------------------------------------------ |
-| `cursor`   | Install Cursor rules for hack CLI usage                |
-| `claude`   | Install Claude Code hooks for hack CLI usage           |
-| `codex`    | Install Codex skill for hack CLI usage                 |
-| `tickets`  | Install Codex skill for hack tickets usage             |
-| `agents`   | Install AGENTS.md / CLAUDE.md snippets                 |
-| `sync`     | Refresh agent docs, skills, and MCP configs            |
-| `mcp`      | Install MCP configs for hack CLI usage (no-shell only) |
+| Subcommand | Summary |
+| --- | --- |
+| `cursor` | Install Cursor rules for hack CLI usage |
+| `claude` | Install Claude Code hooks for hack CLI usage |
+| `codex` | Install Codex skill for hack CLI usage |
+| `tickets` | Install Codex skill for hack tickets usage |
+| `agents` | Install AGENTS.md / CLAUDE.md snippets |
+| `sync` | Refresh agent docs, skills, and MCP configs |
+| `mcp` | Install MCP configs for hack CLI usage (no-shell only) |
 
 #### hack setup cursor
 
@@ -1078,12 +1081,12 @@ Usage: `hack setup cursor [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup claude
 
@@ -1091,12 +1094,12 @@ Usage: `hack setup claude [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup codex
 
@@ -1104,12 +1107,12 @@ Usage: `hack setup codex [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup agents
 
@@ -1117,14 +1120,14 @@ Usage: `hack setup agents [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--all`              | boolean | false   | Target all supported docs                      |
-| `--agents-md`        | boolean | false   | Target AGENTS.md                               |
-| `--claude-md`        | boolean | false   | Target CLAUDE.md                               |
-| `--check`            | boolean | false   | Check whether integration is installed         |
-| `--remove`           | boolean | false   | Remove integration files/config                |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--all` | boolean | false | Target all supported docs |
+| `--agents-md` | boolean | false | Target AGENTS.md |
+| `--claude-md` | boolean | false | Target CLAUDE.md |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 #### hack setup sync
 
@@ -1132,13 +1135,13 @@ Usage: `hack setup sync [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                    |
-| -------------------- | ------- | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
-| `--global`           | boolean | false   | Target global (user) scope only                |
-| `--all-scopes`       | boolean | false   | Target both project and global (user) scopes   |
-| `--check`            | boolean | false   | Check whether integrations are installed       |
-| `--remove`           | boolean | false   | Remove generated integration files/config      |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Target global (user) scope only |
+| `--all-scopes` | boolean | false | Target both project and global (user) scopes |
+| `--check` | boolean | false | Check whether integrations are installed |
+| `--remove` | boolean | false | Remove generated integration files/config |
 
 Automatic guardrail:
 
@@ -1151,16 +1154,16 @@ Usage: `hack setup mcp [options]`
 
 Options:
 
-| Flag                 | Type    | Default | Description                                      |
-| -------------------- | ------- | ------- | ------------------------------------------------ |
-| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
-| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
-| `--all`              | boolean | false   | Target all supported clients                     |
-| `--cursor`           | boolean | false   | Target Cursor integration                        |
-| `--claude`           | boolean | false   | Target Claude integration                        |
-| `--codex`            | boolean | false   | Target Codex integration                         |
-| `--check`            | boolean | false   | Check whether integration is installed           |
-| `--remove`           | boolean | false   | Remove integration files/config                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--global` | boolean | false | Use global (user) scope instead of project scope |
+| `--all` | boolean | false | Target all supported clients |
+| `--cursor` | boolean | false | Target Cursor integration |
+| `--claude` | boolean | false | Target Claude integration |
+| `--codex` | boolean | false | Target Codex integration |
+| `--check` | boolean | false | Check whether integration is installed |
+| `--remove` | boolean | false | Remove integration files/config |
 
 ### hack agent
 
@@ -1168,11 +1171,11 @@ Usage: `hack agent <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                         |
-| ---------- | ------------------------------- |
-| `prime`    | Print agent primer text         |
+| Subcommand | Summary |
+| --- | --- |
+| `prime` | Print agent primer text |
 | `patterns` | Print agent init patterns guide |
-| `init`     | Print agent init prompt         |
+| `init` | Print agent init prompt |
 
 #### hack agent init
 
@@ -1180,10 +1183,10 @@ Usage: `hack agent init [options]`
 
 Options:
 
-| Flag                    | Type   | Default | Description                                    |
-| ----------------------- | ------ | ------- | ---------------------------------------------- |
-| `-p`, `--path <dir>`    | string | -       | Run against a repo path (overrides cwd search) |
-| `-c`, `--client <cursor \| claude \| codex \| print>` | string | - | Open init prompt in an agent client (or print) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `-c`, `--client <cursor|claude|codex|print>` | string | - | Open init prompt in an agent client (or print) |
 
 ### hack mcp
 
@@ -1191,11 +1194,11 @@ Usage: `hack mcp <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                                  |
-| ---------- | ---------------------------------------- |
-| `serve`    | Run the MCP server over stdio            |
-| `install`  | Install MCP config for supported clients |
-| `print`    | Print MCP config snippets                |
+| Subcommand | Summary |
+| --- | --- |
+| `serve` | Run the MCP server over stdio |
+| `install` | Install MCP config for supported clients |
+| `print` | Print MCP config snippets |
 
 #### hack mcp install
 
@@ -1203,17 +1206,17 @@ Usage: `hack mcp install [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `--scope <user \| project>` | string | `user` | Write MCP config to user or project scope |
-| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
-| `--all`              | boolean   | false   | Target all supported clients                   |
-| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
-| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
-| `--codex`            | boolean   | false   | Target Codex MCP config                        |
-| `--docs`             | boolean   | false   | Update AGENTS.md and CLAUDE.md with hack usage |
-| `--agents-md`        | boolean   | false   | Update AGENTS.md with hack usage               |
-| `--claude-md`        | boolean   | false   | Update CLAUDE.md with hack usage               |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--scope <user|project>` | string | `user` | Write MCP config to user or project scope |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--all` | boolean | false | Target all supported clients |
+| `--cursor` | boolean | false | Target Cursor MCP config |
+| `--claude` | boolean | false | Target Claude CLI MCP config |
+| `--codex` | boolean | false | Target Codex MCP config |
+| `--docs` | boolean | false | Update AGENTS.md and CLAUDE.md with hack usage |
+| `--agents-md` | boolean | false | Update AGENTS.md with hack usage |
+| `--claude-md` | boolean | false | Update CLAUDE.md with hack usage |
 
 Notes:
 
@@ -1226,14 +1229,14 @@ Usage: `hack mcp print [options]`
 
 Options:
 
-| Flag                 | Type   | Default | Description                                    |
-| -------------------- | ------ | ------- | ---------------------------------------------- |
-| `--scope <user \| project>` | string | `user` | Print MCP config for user or project scope |
-| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
-| `--all`              | boolean   | false   | Target all supported clients                   |
-| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
-| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
-| `--codex`            | boolean   | false   | Target Codex MCP config                        |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--scope <user|project>` | string | `user` | Print MCP config for user or project scope |
+| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
+| `--all` | boolean | false | Target all supported clients |
+| `--cursor` | boolean | false | Target Cursor MCP config |
+| `--claude` | boolean | false | Target Claude CLI MCP config |
+| `--codex` | boolean | false | Target Codex MCP config |
 
 ## Diagnostics commands
 
@@ -1272,17 +1275,17 @@ Usage: `hack daemon <subcommand>`
 
 Subcommands:
 
-| Subcommand  | Summary                                    |
-| ----------- | ------------------------------------------ |
-| `start`     | Start hackd (local daemon)                 |
-| `stop`      | Stop hackd                                 |
-| `restart`   | Restart hackd                              |
-| `status`    | Show hackd status                          |
-| `metrics`   | Show hackd metrics                         |
-| `logs`      | Show hackd logs                            |
-| `clear`     | Clear stale hackd pid/socket files         |
-| `install`   | Install hackd as a launchd service (macOS) |
-| `uninstall` | Uninstall hackd launchd service (macOS)    |
+| Subcommand | Summary |
+| --- | --- |
+| `start` | Start hackd (local daemon) |
+| `stop` | Stop hackd |
+| `restart` | Restart hackd |
+| `status` | Show hackd status |
+| `metrics` | Show hackd metrics |
+| `logs` | Show hackd logs |
+| `clear` | Clear stale hackd pid/socket files |
+| `install` | Install hackd as a launchd service (macOS) |
+| `uninstall` | Uninstall hackd launchd service (macOS) |
 
 Autostart + self-heal behavior:
 
@@ -1299,9 +1302,9 @@ Usage: `hack daemon start [options]`
 
 Options:
 
-| Flag           | Type    | Default | Description                         |
-| -------------- | ------- | ------- | ----------------------------------- |
-| `--foreground` | boolean | false   | Run hackd in the foreground (debug) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--foreground` | boolean | false | Run hackd in the foreground (debug) |
 
 #### hack daemon status
 
@@ -1309,9 +1312,9 @@ Usage: `hack daemon status [options]`
 
 Options:
 
-| Flag     | Type    | Default | Description                                                    |
-| -------- | ------- | ------- | -------------------------------------------------------------- |
-| `--json` | boolean | false   | Output JSON (machine-readable, includes launchd info on macOS) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable, includes launchd info on macOS) |
 
 #### hack daemon logs
 
@@ -1319,32 +1322,35 @@ Usage: `hack daemon logs [options]`
 
 Options:
 
-| Flag         | Type   | Default | Description           |
-| ------------ | ------ | ------- | --------------------- |
-| `--tail <n>` | number | 200     | Tail last N log lines |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--tail <n>` | number | 200 | Tail last N log lines |
 
 #### hack daemon install
 
 Usage: `hack daemon install [options]`
 
-Installs hackd as a launchd service on macOS. The daemon will be managed by launchd and can optionally start automatically on login.
+Installs hackd as a launchd service on macOS. The daemon will be managed by launchd
+and can optionally start automatically on login.
 
 Options:
 
-| Flag               | Type    | Default | Description                               |
-| ------------------ | ------- | ------- | ----------------------------------------- |
-| `--run-at-load`    | boolean | true    | Start hackd automatically on login        |
-| `--no-run-at-load` | boolean | -       | Do not start hackd automatically on login |
-| `--gui-only`       | boolean | true    | Only run in GUI sessions (Aqua)           |
-| `--no-gui-only`    | boolean | -       | Run in all session types (including SSH)  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--run-at-load` | boolean | true | Start hackd automatically on login |
+| `--no-run-at-load` | boolean | - | Do not start hackd automatically on login |
+| `--gui-only` | boolean | true | Only run in GUI sessions (Aqua) |
+| `--no-gui-only` | boolean | - | Run in all session types (including SSH) |
 
-The service uses the label `dance.hack.hackd` and writes its plist to `~/Library/LaunchAgents/dance.hack.hackd.plist`.
+The service uses the label `dance.hack.hackd` and writes its plist to
+`~/Library/LaunchAgents/dance.hack.hackd.plist`.
 
 #### hack daemon uninstall
 
 Usage: `hack daemon uninstall`
 
-Uninstalls the hackd launchd service on macOS. Removes the plist and unloads the service from launchd.
+Uninstalls the hackd launchd service on macOS. Removes the plist and unloads
+the service from launchd.
 
 ### hack log-pipe
 
@@ -1354,8 +1360,8 @@ Options:
 
 | Flag | Type | Default | Description |
 | --- | --- | --- | --- |
-| `--format <auto \| docker-compose \| plain>` | string | `auto` | How to parse incoming lines from stdin |
-| `--stream <stdout \| stderr>` | string | `stdout` | Treat stdin as stdout or stderr |
+| `--format <auto|docker-compose|plain>` | string | `auto` | How to parse incoming lines from stdin |
+| `--stream <stdout|stderr>` | string | `stdout` | Treat stdin as stdout or stderr |
 
 ### hack help
 
@@ -1363,9 +1369,9 @@ Usage: `hack help [path...]`
 
 Arguments:
 
-| Name   | Type     | Required | Description                                        |
-| ------ | -------- | -------- | -------------------------------------------------- |
-| `path` | string[] | no       | Command path to show help for (e.g. `global logs`) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `path` | string[] | no | Command path to show help for (e.g. `global logs`) |
 
 ### hack update
 
@@ -1373,12 +1379,12 @@ Usage: `hack update [options]`
 
 Options:
 
-| Flag          | Type    | Default | Description                                    |
-| ------------- | ------- | ------- | ---------------------------------------------- |
-| `--check`     | boolean | false   | Check for updates (do not install)             |
-| `--yes`       | boolean | false   | Apply update without prompting                 |
-| `--tag <tag>` | string  | -       | Update to a specific release tag (e.g. v1.4.0) |
-| `--json`      | boolean | false   | Output JSON (machine-readable)                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--check` | boolean | false | Check for updates (do not install) |
+| `--yes` | boolean | false | Apply update without prompting |
+| `--tag <tag>` | string | - | Update to a specific release tag (e.g. v1.4.0) |
+| `--json` | boolean | false | Output JSON (machine-readable) |
 
 ### hack version
 
@@ -1392,23 +1398,23 @@ Usage: `hack secrets <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary                            |
-| ---------- | ---------------------------------- |
-| `set`      | Store a secret                     |
-| `get`      | Print a secret (exit 1 if missing) |
-| `delete`   | Delete a stored secret             |
+| Subcommand | Summary |
+| --- | --- |
+| `set` | Store a secret |
+| `get` | Print a secret (exit 1 if missing) |
+| `delete` | Delete a stored secret |
 
 Options (all subcommands):
 
-| Flag                  | Type   | Default    | Description                       |
-| --------------------- | ------ | ---------- | --------------------------------- |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
 | `--service <service>` | string | `hack-cli` | Override Bun.secrets service name |
 
 Arguments (set/get/delete):
 
-| Name   | Type   | Required | Description                       |
-| ------ | ------ | -------- | --------------------------------- |
-| `name` | string | no       | Secret name (prompted if omitted) |
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | no | Secret name (prompted if omitted) |
 
 ## Fun
 
@@ -1420,5 +1426,5 @@ Options:
 
 | Flag | Type | Default | Description |
 | --- | --- | --- | --- |
-| `--variant <cut \| mash \| cycle \| random>` | string | `cycle` | Animation variant |
-| `--loop`        | boolean | true    | Loop until Ctrl+C |
+| `--variant <cut|mash|cycle|random>` | string | `cycle` | Animation variant |
+| `--loop` | boolean | true | Loop until Ctrl+C |
diff --git a/docs/extensions.md b/docs/extensions.md
index d90809452..79ce4f341 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -1,6 +1,7 @@
 # Extensions & SDK (v0.1)
 
-This doc defines the extension surface area for `hack` and how extension commands are authored, configured, and dispatched.
+This doc defines the extension surface area for `hack` and how extension commands are authored,
+configured, and dispatched.
 
 ## Quick start (one command)
 
@@ -10,7 +11,8 @@ If you just want remote access working, start here:
 hack remote setup
 ```
 
-The wizard enables the gateway for the current project, creates a token + QR, and can configure Cloudflare/Tailscale/SSH exposure in one flow.
+The wizard enables the gateway for the current project, creates a token + QR, and can configure
+Cloudflare/Tailscale/SSH exposure in one flow.
 
 ## Behavior
 
@@ -18,7 +20,8 @@ The wizard enables the gateway for the current project, creates a token + QR, an
 - Each extension provides a manifest + commands (`ExtensionDefinition`).
 - The CLI dispatches extension commands via `hack x <namespace> <command>`.
 - Global enablement lives in `~/.hack/hack.config.json` (`hack config set --global ...`).
-- Per-project overrides live in `.hack/hack.config.json` and typically win over global values (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
+- Per-project overrides live in `.hack/hack.config.json` and typically win over global values
+  (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
 - Built-in Gateway enablement is project-scoped: `controlPlane.gateway.enabled` opts a project into routing.
 
 ## Extension definition (API surface)
@@ -44,14 +47,14 @@ export type ExtensionCommand = {
 ```
 
 The `ExtensionCommandContext` includes:
-
 - `controlPlaneConfig` (parsed config)
 - `projectId` and `projectName` (when available)
 - `logger` and `cwd`
 
 ## Config + enablement
 
-Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by `src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
+Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by
+`src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
 
 Enable a global extension by id:
 
@@ -75,10 +78,10 @@ Shortcut for gateway (project-scoped):
 }
 ```
 
-Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config. Project overrides for these are ignored.
+Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config.
+Project overrides for these are ignored.
 
 CLI helpers:
-
 - `hack gateway enable` (sets both gateway + extension flags)
 - `hack gateway setup` (guided enable + optional writes + token creation + QR by default)
 - `hack config set --global 'controlPlane.extensions[\"dance.hack.gateway\"].enabled' true`
@@ -103,10 +106,10 @@ Use `hack x <namespace> help` to list commands.
 - GitHub: `hack x github connect|oauth-connect|disconnect|profiles|use|status|pr-upsert`
 - Linear: `hack x linear setup|connect|oauth-connect|disconnect|status|profiles|use|projects|project-bind|sync-issue|sync-project`
 
-Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also requires global `controlPlane.gateway.allowWrites = true`).
+Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also
+requires global `controlPlane.gateway.allowWrites = true`).
 
 Current gateway API surface (HTTP/WS):
-
 - `GET /v1/status`, `GET /v1/metrics`, `GET /v1/projects`, `GET /v1/ps`
 - `GET/POST /control-plane/projects/:id/jobs`
 - `GET /control-plane/projects/:id/jobs/:jobId`
@@ -117,7 +120,6 @@ Current gateway API surface (HTTP/WS):
 - `WS /control-plane/projects/:id/shells/:shellId/stream` (requires write token + allowWrites)
 
 Local auth service surface (daemon + global Caddy route):
-
 - `GET /health`
 - `GET /v1/auth/providers`
 - `GET /gh/start` (GitHub browser OAuth entrypoint)
@@ -126,14 +128,15 @@ Local auth service surface (daemon + global Caddy route):
 - `GET /v1/auth/github/start`
 - `GET /v1/auth/github/flows/:id`
 
-Interactive shell/TTY is available via the shell stream endpoints; use `hack x supervisor shell` or see protocol below.
+Interactive shell/TTY is available via the shell stream endpoints; use
+`hack x supervisor shell` or see protocol below.
 
 For full usage guidance and structured workflow patterns, see `gateway-api.md`.
 
 For exposure helpers, see the guides:
-
 - `guides/remote-cloudflare.md`
-- `guides/remote-tailscale.md` DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
+- `guides/remote-tailscale.md`
+DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
 
 ## Command reference
 
@@ -147,12 +150,11 @@ Options:
 
 | Flag | Type | Default | Description |
 | --- | --- | --- | --- |
-| `--scope <read \| write>` | string | `read` | Token scope |
-| `--write`         | boolean | false   | Shortcut for `--scope write` |
-| `--label <label>` | string  | -       | Optional label               |
+| `--scope <read|write>` | string | `read` | Token scope |
+| `--write` | boolean | false | Shortcut for `--scope write` |
+| `--label <label>` | string | - | Optional label |
 
 Notes:
-
 - The first non-flag argument is treated as the label if `--label` is not used.
 
 #### token-list
@@ -173,11 +175,11 @@ Usage: `hack x supervisor job-list [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                 |
-| ------------------ | ------- | ------- | --------------------------- |
-| `--project <name>` | string  | -       | Target a registered project |
-| `--path <dir>`     | string  | -       | Target a repo path          |
-| `--json`           | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--json` | boolean | false | Output JSON |
 
 #### job-create
 
@@ -185,14 +187,14 @@ Usage: `hack x supervisor job-create [options] -- <command...>`
 
 Options:
 
-| Flag                | Type    | Default   | Description                                  |
-| ------------------- | ------- | --------- | -------------------------------------------- |
-| `--project <name>`  | string  | -         | Target a registered project                  |
-| `--path <dir>`      | string  | -         | Target a repo path                           |
-| `--runner <name>`   | string  | `generic` | Runner name                                  |
-| `--cwd <path>`      | string  | -         | Working directory (relative to project root) |
-| `--env <KEY=VALUE>` | string  | -         | Environment override (repeatable)            |
-| `--json`            | boolean | false     | Output JSON                                  |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--runner <name>` | string | `generic` | Runner name |
+| `--cwd <path>` | string | - | Working directory (relative to project root) |
+| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
+| `--json` | boolean | false | Output JSON |
 
 ### GitHub extension (`hack x github`)
 
@@ -255,9 +257,10 @@ hack x github pr-upsert \
 ```
 
 Notes:
-
-- Profile config lives at: `controlPlane.extensions["dance.hack.github"].config.profiles`.
-- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
+- Profile config lives at:
+  `controlPlane.extensions["dance.hack.github"].config.profiles`.
+- Profile selection precedence is:
+  `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
 - Keychain storage uses profile-specific `authRef` + `service`.
 - Token resolution order is keychain first, then environment fallback (`tokenEnv`).
 - If token metadata includes `expiresAt`, auth resolution attempts automatic GitHub App refresh using profile `appId`, `installationId`, and private key source.
@@ -271,11 +274,10 @@ Notes:
 - `auth.hack` and `auth.hack.gy` are routed by global Caddy to the daemon auth listener (`127.0.0.1:7790` by default), so this endpoint can also host future provider callbacks/hooks.
 
 Workflow scope:
-
 - Current shipped GitHub workflow support is intentionally narrow:
   - auth/profile connection and selection
   - PR create/update via `hack x github pr-upsert`
-- The first-class GitHub workflow model for the current milestone is bounded to:
+- The first-class GitHub workflow model for this milestone is explicitly bounded to:
   - review intake and review decision
   - PR update and readiness management
   - PR-level conversation comments
@@ -283,60 +285,49 @@ Workflow scope:
 - The initial set is outcome-based rather than command-based so CLI, desktop, and agent surfaces can share the same product boundary.
 - Until those additional flows land, this section should not be read as claiming those commands already exist.
 
-Initial supported set for this milestone:
-
+Initial supported set:
 1. Review intake for a relevant PR
 2. Review decision submission with a summary body
 3. PR creation/update plus draft-ready state changes
 4. Top-level PR comments
 5. Read-only repo-context handoff actions tied to a PR
 
-Initial workflow definitions:
-
+Workflow definitions and success criteria:
 - Review intake and review decision
   - Outcome: identify a PR needing action, inspect summary state, and submit `approve`, `comment`, or `request_changes`.
+  - Success: a reviewer can identify a PR that needs action and submit a decision from Hack.
 - PR update and readiness management
   - Outcome: create or update a PR, keep title/body/base accurate, and move between draft and ready states.
+  - Success: an author can create or correct PR state, including draft and ready transitions, from Hack.
 - Conversation comments
   - Outcome: leave top-level PR discussion comments without doing a full review submission.
+  - Success: a user can leave a contextual PR comment without switching to GitHub web.
 - PR-adjacent repo handoff actions
   - Outcome: move from PR context to local repo/branch context without manually reconstructing refs.
+  - Success: a user can move from PR context to local repo context without manual copy-paste of refs.
 
 Explicitly out of the initial GitHub scope:
-
 - inline diff review comments and thread resolution
 - labels, assignees, milestones, and project edits
 - merge, merge queue, auto-merge, and rebase controls
 - rerunning GitHub Actions jobs
 - GitHub Issues, Projects, Discussions, releases, or repo admin surfaces
 
-Success criteria by workflow class:
-
-- Review intake and review decision
-  - A reviewer can identify a PR that needs action and submit `approve`, `comment`, or `request_changes` from Hack.
-- PR update and readiness management
-  - An author can create or correct a PR state, including draft and ready transitions, from Hack.
-- Conversation comments
-  - A user can leave a contextual PR comment without switching to GitHub web.
-- PR-adjacent repo handoff actions
-  - A user can move from PR context to local repo context without manual copy-paste of refs.
-
 Recommended implementation order:
-
 1. shared PR/review read models
 2. review decision submission
 3. PR metadata update plus draft/ready transitions
 4. standalone PR comment creation
 5. repo-context handoff actions
 
-Detailed design and sequencing live in:
-
+Detailed design and sequencing:
 - `docs/plans/2026-03-13-github-first-class-workflows-design.md`
 - `docs/plans/2026-03-13-github-first-class-workflows-plan.md`
 
 ### Linear extension (`hack x linear`)
 
-Linear integration supports multiple auth profiles, project-level binding, and manual sync in both directions between Linear issues and hack tickets.
+Linear integration supports multiple auth profiles, project-level binding, and manual sync in both
+directions between Linear issues and hack tickets.
 
 Quick start:
 
@@ -359,9 +350,11 @@ hack x linear sync-project --from hack --owner both
 ```
 
 Notes:
-
-- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.linear.profile` -> `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
-- Project mapping is stored in project config: `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
+- Profile selection precedence is:
+  `--profile` -> `controlPlane.routing.overrides.linear.profile` ->
+  `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
+- Project mapping is stored in project config:
+  `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
 - Sync is manual by default (`sync-issue` / `sync-project`); there is no background autosync yet.
 - Ticket provenance is preserved during sync via `owner`, `source`, `tags`, and `external*` linkage fields.
 - `hack x linear connect` uses token mode when `--token`/`--stdin`/`$HACK_LINEAR_API_TOKEN` is present, and otherwise falls back to browser OAuth.
@@ -374,7 +367,8 @@ Notes:
 - Auth-broker Linear endpoints:
   - OAuth callback page: `/linear/callback`
   - Webhook ingest: `/linear/webhooks` (legacy alias: `/v1/integrations/linear/webhook`)
-- Sync toggles are configurable at `controlPlane.extensions["dance.hack.linear"].config.sync`:
+- Sync toggles are configurable at
+  `controlPlane.extensions["dance.hack.linear"].config.sync`:
   - `labels` (default `false`)
   - `statuses` (default `true`)
   - `dependencies` (default `true`)
@@ -387,11 +381,11 @@ Usage: `hack x supervisor job-show <job-id> [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                 |
-| ------------------ | ------- | ------- | --------------------------- |
-| `--project <name>` | string  | -       | Target a registered project |
-| `--path <dir>`     | string  | -       | Target a repo path          |
-| `--json`           | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--json` | boolean | false | Output JSON |
 
 #### job-cancel
 
@@ -399,10 +393,10 @@ Usage: `hack x supervisor job-cancel <job-id> [options]`
 
 Options:
 
-| Flag               | Type   | Default | Description                 |
-| ------------------ | ------ | ------- | --------------------------- |
-| `--project <name>` | string | -       | Target a registered project |
-| `--path <dir>`     | string | -       | Target a repo path          |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
 
 #### job-tail
 
@@ -410,15 +404,15 @@ Usage: `hack x supervisor job-tail <job-id> [options]`
 
 Options:
 
-| Flag               | Type    | Default | Description                 |
-| ------------------ | ------- | ------- | --------------------------- |
-| `--project <name>` | string  | -       | Target a registered project |
-| `--path <dir>`     | string  | -       | Target a repo path          |
-| `--follow`         | boolean | true    | Follow logs (default)       |
-| `--no-follow`      | boolean | false   | Print logs and exit         |
-| `--logs-from <n>`  | number  | 0       | Resume from log offset      |
-| `--from <n>`       | number  | 0       | Alias for `--logs-from`     |
-| `--json`           | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--follow` | boolean | true | Follow logs (default) |
+| `--no-follow` | boolean | false | Print logs and exit |
+| `--logs-from <n>` | number | 0 | Resume from log offset |
+| `--from <n>` | number | 0 | Alias for `--logs-from` |
+| `--json` | boolean | false | Output JSON |
 
 #### job-attach
 
@@ -426,16 +420,16 @@ Usage: `hack x supervisor job-attach <job-id> [options]`
 
 Options:
 
-| Flag                | Type    | Default | Description                 |
-| ------------------- | ------- | ------- | --------------------------- |
-| `--project <name>`  | string  | -       | Target a registered project |
-| `--path <dir>`      | string  | -       | Target a repo path          |
-| `--follow`          | boolean | true    | Follow logs (default)       |
-| `--no-follow`       | boolean | false   | Print logs and exit         |
-| `--logs-from <n>`   | number  | 0       | Resume from log offset      |
-| `--from <n>`        | number  | 0       | Alias for `--logs-from`     |
-| `--events-from <n>` | number  | 0       | Resume from event sequence  |
-| `--json`            | boolean | false   | Output JSON                 |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--path <dir>` | string | - | Target a repo path |
+| `--follow` | boolean | true | Follow logs (default) |
+| `--no-follow` | boolean | false | Print logs and exit |
+| `--logs-from <n>` | number | 0 | Resume from log offset |
+| `--from <n>` | number | 0 | Alias for `--logs-from` |
+| `--events-from <n>` | number | 0 | Resume from event sequence |
+| `--json` | boolean | false | Output JSON |
 
 #### shell
 
@@ -443,21 +437,20 @@ Usage: `hack x supervisor shell [options]`
 
 Options:
 
-| Flag                | Type   | Default                 | Description                       |
-| ------------------- | ------ | ----------------------- | --------------------------------- |
-| `--project <name>`  | string | -                       | Target a registered project       |
-| `--project-id <id>` | string | -                       | Target by project id (gateway)    |
-| `--path <dir>`      | string | -                       | Target a repo path                |
-| `--gateway <url>`   | string | `http://127.0.0.1:7788` | Gateway URL                       |
-| `--token <token>`   | string | -                       | Gateway write token               |
-| `--shell <path>`    | string | -                       | Shell path                        |
-| `--cwd <path>`      | string | -                       | Working directory                 |
-| `--cols <n>`        | number | -                       | Terminal columns                  |
-| `--rows <n>`        | number | -                       | Terminal rows                     |
-| `--env <KEY=VALUE>` | string | -                       | Environment override (repeatable) |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--project <name>` | string | - | Target a registered project |
+| `--project-id <id>` | string | - | Target by project id (gateway) |
+| `--path <dir>` | string | - | Target a repo path |
+| `--gateway <url>` | string | `http://127.0.0.1:7788` | Gateway URL |
+| `--token <token>` | string | - | Gateway write token |
+| `--shell <path>` | string | - | Shell path |
+| `--cwd <path>` | string | - | Working directory |
+| `--cols <n>` | number | - | Terminal columns |
+| `--rows <n>` | number | - | Terminal rows |
+| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
 
 Notes:
-
 - `--project` and `--project-id` are mutually exclusive.
 
 ### Cloudflare extension (`hack x cloudflare`)
@@ -468,15 +461,15 @@ Usage: `hack x cloudflare tunnel-print [options]`
 
 Options:
 
-| Flag                        | Type   | Default                 | Description                  |
-| --------------------------- | ------ | ----------------------- | ---------------------------- |
-| `--hostname <host>`         | string | -                       | Gateway hostname             |
-| `--tunnel <name>`           | string | `hack-gateway`          | Tunnel name                  |
-| `--origin <url>`            | string | `http://127.0.0.1:7788` | Gateway origin               |
-| `--ssh-hostname <host>`     | string | -                       | SSH hostname (optional)      |
-| `--ssh-origin <url>`        | string | `ssh://127.0.0.1:22`    | SSH origin                   |
-| `--credentials-file <path>` | string | -                       | Cloudflared credentials file |
-| `--out <path>`              | string | -                       | Write config to a file       |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--hostname <host>` | string | - | Gateway hostname |
+| `--tunnel <name>` | string | `hack-gateway` | Tunnel name |
+| `--origin <url>` | string | `http://127.0.0.1:7788` | Gateway origin |
+| `--ssh-hostname <host>` | string | - | SSH hostname (optional) |
+| `--ssh-origin <url>` | string | `ssh://127.0.0.1:22` | SSH origin |
+| `--credentials-file <path>` | string | - | Cloudflared credentials file |
+| `--out <path>` | string | - | Write config to a file |
 
 #### tunnel-setup
 
@@ -503,11 +496,11 @@ Usage: `hack x cloudflare tunnel-start [options]`
 
 Options:
 
-| Flag              | Type   | Default                     | Description          |
-| ----------------- | ------ | --------------------------- | -------------------- |
-| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path          |
-| `--out <path>`    | string | -                           | Alias for `--config` |
-| `--tunnel <name>` | string | -                           | Override tunnel name |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path |
+| `--out <path>` | string | - | Alias for `--config` |
+| `--tunnel <name>` | string | - | Override tunnel name |
 
 #### tunnel-stop
 
@@ -519,10 +512,10 @@ Usage: `hack x cloudflare access-setup [options]`
 
 Options:
 
-| Flag                    | Type   | Default | Description  |
-| ----------------------- | ------ | ------- | ------------ |
-| `--ssh-hostname <host>` | string | -       | SSH hostname |
-| `--user <user>`         | string | -       | SSH username |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--ssh-hostname <host>` | string | - | SSH hostname |
+| `--user <user>` | string | - | SSH username |
 
 ### Tailscale extension (`hack x tailscale`)
 
@@ -555,7 +548,6 @@ Usage: `hack x tailscale oauth-disconnect [--auth-ref <ref>] [--json]`
 Usage: `hack x tailscale ip [args...]`
 
 Notes:
-
 - `status` and `ip` forward extra args directly to `tailscale`.
 - `ip` defaults to `-4` when no args are provided.
 
@@ -604,18 +596,17 @@ The gateway binds to `127.0.0.1` by default. Expose it through one of:
 - SSH tunnel (ad‑hoc): `ssh -L 7788:127.0.0.1:7788 <host>`
 - Zero Trust/VPN (persistent): Tailscale, Cloudflare, etc. targeting the gateway port
 - Optional Caddy route for local convenience (`https://gateway.hack`):
-  - Add a small labeled container in the global Caddy compose that proxies to `host.docker.internal:7788` (or `host-gateway` on Linux).
+  - Add a small labeled container in the global Caddy compose that proxies to
+    `host.docker.internal:7788` (or `host-gateway` on Linux).
 
 Keep tokens read-only unless you explicitly need writes.
 
 Recommended order:
-
-1. Start with SSH tunneling for quick remote access.
-2. Move to a private Zero Trust/VPN network once you want persistent access.
-3. Add the Caddy route only for nicer local URLs (not required for remote access).
+1) Start with SSH tunneling for quick remote access.
+2) Move to a private Zero Trust/VPN network once you want persistent access.
+3) Add the Caddy route only for nicer local URLs (not required for remote access).
 
 Remote helper commands:
-
 - `hack remote status` shows gateway + exposure status.
 - `hack remote qr` emits QR payloads for SSH or gateway clients.
 
@@ -649,7 +640,7 @@ Server → client:
 
 ```
 {"type":"ready","shellId":"...","cols":120,"rows":30,"cwd":"/repo","shell":"/bin/zsh","status":"running"}
-{"type":"output","data":"..."}
+{"type":"output","data":"..."} 
 {"type":"exit","exitCode":0,"signal":null}
 ```
 

From 0bbe84e61b86d64822de0c1acf9b71ba8c7575d7 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 19:04:54 +0000
Subject: [PATCH 092/134] docs: format github workflow docs

---
 docs/cli.md        | 832 ++++++++++++++++++++++-----------------------
 docs/extensions.md | 213 ++++++------
 2 files changed, 518 insertions(+), 527 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 83ab9a58b..bf561b525 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,7 +1,6 @@
 # CLI Reference
 
-This reference mirrors the CLI spec in `src/cli/spec.ts`.
-Run `hack help` or `hack help <command>` for interactive help.
+This reference mirrors the CLI spec in `src/cli/spec.ts`. Run `hack help` or `hack help <command>` for interactive help.
 
 If you are new to Hack, scan the CLI in this order:
 
@@ -70,17 +69,17 @@ Usage: `hack global <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `install` | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy |
-| `up` | Start global infra containers |
-| `down` | Stop global infra containers |
-| `status` | Show status for global infra (containers + networks) |
-| `logs` | Tail global infra logs (caddy|grafana|loki|alloy) |
-| `ca` | Export Caddy Local CA cert (print path or PEM) |
-| `cert` | Generate local TLS certs via mkcert (for non-Caddy services) |
-| `trust` | Trust Caddy Local CA (macOS) so https://*.hack is trusted |
-| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards) |
+| Subcommand   | Summary                                                      |
+| ------------ | ------------------------------------------------------------ | ------- | ---- | ------ |
+| `install`    | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy     |
+| `up`         | Start global infra containers                                |
+| `down`       | Stop global infra containers                                 |
+| `status`     | Show status for global infra (containers + networks)         |
+| `logs`       | Tail global infra logs (caddy                                | grafana | loki | alloy) |
+| `ca`         | Export Caddy Local CA cert (print path or PEM)               |
+| `cert`       | Generate local TLS certs via mkcert (for non-Caddy services) |
+| `trust`      | Trust Caddy Local CA (macOS) so https://\*.hack is trusted   |
+| `logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards)          |
 
 #### hack global logs
 
@@ -88,18 +87,18 @@ Usage: `hack global logs [service] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | no | Filter to one global service (caddy, grafana, loki, alloy) |
+| Name      | Type   | Required | Description                                                |
+| --------- | ------ | -------- | ---------------------------------------------------------- |
+| `service` | string | no       | Filter to one global service (caddy, grafana, loki, alloy) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-f`, `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--tail <n>` | number | 200 | Tail last N log lines |
-| `--pretty` | boolean | false | Pretty-print logs (best-effort JSON parsing + formatting) |
+| Flag             | Type    | Default | Description                                               |
+| ---------------- | ------- | ------- | --------------------------------------------------------- |
+| `-f`, `--follow` | boolean | true    | Follow logs (default)                                     |
+| `--no-follow`    | boolean | false   | Print logs and exit                                       |
+| `--tail <n>`     | number  | 200     | Tail last N log lines                                     |
+| `--pretty`       | boolean | false   | Pretty-print logs (best-effort JSON parsing + formatting) |
 
 #### hack global ca
 
@@ -107,9 +106,9 @@ Usage: `hack global ca [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--print` | boolean | false | Print the CA cert PEM to stdout (instead of printing its path) |
+| Flag      | Type    | Default | Description                                                    |
+| --------- | ------- | ------- | -------------------------------------------------------------- |
+| `--print` | boolean | false   | Print the CA cert PEM to stdout (instead of printing its path) |
 
 #### hack global cert
 
@@ -117,16 +116,16 @@ Usage: `hack global cert <hosts...> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `hosts` | string[] | yes | One or more hostnames to generate certs for |
+| Name    | Type     | Required | Description                                 |
+| ------- | -------- | -------- | ------------------------------------------- |
+| `hosts` | string[] | yes      | One or more hostnames to generate certs for |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--install` | boolean | false | Run mkcert -install before generating certs |
-| `--out <dir>` | string | `~/.hack/certs` | Directory for generated cert/key |
+| Flag          | Type    | Default         | Description                                 |
+| ------------- | ------- | --------------- | ------------------------------------------- |
+| `--install`   | boolean | false           | Run mkcert -install before generating certs |
+| `--out <dir>` | string  | `~/.hack/certs` | Directory for generated cert/key            |
 
 ### hack projects
 
@@ -151,9 +150,9 @@ Usage: `hack projects prune [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
+| Flag               | Type    | Default | Description                                   |
+| ------------------ | ------- | ------- | --------------------------------------------- |
+| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
 
 ### hack status
 
@@ -161,12 +160,12 @@ Usage: `hack status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Filter to a registered project name |
-| `--include-global` | boolean | false | Include global infra projects under `~/.hack` |
-| `--all` | boolean | false | Include unregistered docker compose projects |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag               | Type    | Default | Description                                   |
+| ------------------ | ------- | ------- | --------------------------------------------- |
+| `--project <name>` | string  | -       | Filter to a registered project name           |
+| `--include-global` | boolean | false   | Include global infra projects under `~/.hack` |
+| `--all`            | boolean | false   | Include unregistered docker compose projects  |
+| `--json`           | boolean | false   | Output JSON (machine-readable)                |
 
 ### hack usage
 
@@ -209,13 +208,13 @@ Usage: `hack up [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `-d`, `--detach` | boolean | false | Run in background (docker compose up -d) |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack down
 
@@ -224,12 +223,12 @@ Usage: `hack down [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack restart
 
@@ -238,12 +237,12 @@ Usage: `hack restart [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto|local|remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack ps
 
@@ -265,9 +264,9 @@ Usage: `hack logs [service] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | no | Filter logs by service (shortcut for `--services`) |
+| Name      | Type   | Required | Description                                        |
+| --------- | ------ | -------- | -------------------------------------------------- |
+| `service` | string | no       | Filter logs by service (shortcut for `--services`) |
 
 Options:
 
@@ -301,10 +300,10 @@ Usage: `hack run <service> [-- <cmd...>] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `service` | string | yes | Compose service name |
-| `cmd` | string[] | no | Command to run (defaults to service entrypoint) |
+| Name      | Type     | Required | Description                                     |
+| --------- | -------- | -------- | ----------------------------------------------- |
+| `service` | string   | yes      | Compose service name                            |
+| `cmd`     | string[] | no       | Command to run (defaults to service entrypoint) |
 
 Options:
 
@@ -322,18 +321,18 @@ Usage: `hack open [target] [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `target` | string | no | `www` (default), `logs`, a subdomain, or a full URL |
+| Name     | Type   | Required | Description                                         |
+| -------- | ------ | -------- | --------------------------------------------------- |
+| `target` | string | no       | `www` (default), `logs`, a subdomain, or a full URL |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--branch <name>` | string | - | Run against a branch-specific instance |
-| `--json` | boolean | false | Output JSON with `{ "url": "..." }` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--branch <name>`    | string  | -       | Run against a branch-specific instance         |
+| `--json`             | boolean | false   | Output JSON with `{ "url": "..." }`            |
 
 Notes:
 
@@ -348,10 +347,10 @@ Usage: `hack tui [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 Notes:
 
@@ -363,12 +362,12 @@ Usage: `hack branch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `add` | Register a branch alias for this project |
-| `list` | List registered branch aliases |
-| `remove` | Remove a branch alias |
-| `open` | Open the branch host in a browser |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `add`      | Register a branch alias for this project |
+| `list`     | List registered branch aliases           |
+| `remove`   | Remove a branch alias                    |
+| `open`     | Open the branch host in a browser        |
 
 #### hack branch add
 
@@ -376,17 +375,17 @@ Usage: `hack branch add <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--note <text>` | string | - | Optional note for the branch entry |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
+| `--note <text>`      | string | -       | Optional note for the branch entry             |
 
 #### hack branch list
 
@@ -394,10 +393,10 @@ Usage: `hack branch list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack branch remove
 
@@ -405,16 +404,16 @@ Usage: `hack branch remove <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack branch open
 
@@ -422,16 +421,16 @@ Usage: `hack branch open <name> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Branch name or alias |
+| Name   | Type   | Required | Description          |
+| ------ | ------ | -------- | -------------------- |
+| `name` | string | yes      | Branch name or alias |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 ### hack config
 
@@ -439,10 +438,10 @@ Usage: `hack config <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `get` | Read a value from hack.config.json |
-| `set` | Update a value in hack.config.json |
+| Subcommand | Summary                            |
+| ---------- | ---------------------------------- |
+| `get`      | Read a value from hack.config.json |
+| `set`      | Update a value in hack.config.json |
 
 #### hack config get
 
@@ -450,17 +449,17 @@ Usage: `hack config get <key> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
+| Name  | Type   | Required | Description                             |
+| ----- | ------ | -------- | --------------------------------------- |
+| `key` | string | yes      | Dot path (e.g. `logs.snapshot_backend`) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--global` | boolean | false | Read global `~/.hack/hack.config.json` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--global`           | boolean | false   | Read global `~/.hack/hack.config.json`         |
 
 #### hack config set
 
@@ -468,18 +467,18 @@ Usage: `hack config set <key> <value> [options]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `key` | string | yes | Dot path (e.g. `logs.snapshot_backend`) |
-| `value` | string | yes | JSON value or raw string (parsed as JSON when valid) |
+| Name    | Type   | Required | Description                                          |
+| ------- | ------ | -------- | ---------------------------------------------------- |
+| `key`   | string | yes      | Dot path (e.g. `logs.snapshot_backend`)              |
+| `value` | string | yes      | JSON value or raw string (parsed as JSON when valid) |
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--global` | boolean | false | Write global `~/.hack/hack.config.json` |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string  | -       | Target a registered project by name            |
+| `--global`           | boolean | false   | Write global `~/.hack/hack.config.json`        |
 
 ## Collaboration & integrations
 
@@ -547,12 +546,12 @@ Usage: `hack env <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List env contract vars and resolution state |
-| `set` | Set an env value (.hack/.env or secret backend) |
-| `unset` | Unset an env value (.hack/.env and secret backend) |
-| `backend` | Manage env/secret backend strategy |
+| Subcommand | Summary                                            |
+| ---------- | -------------------------------------------------- |
+| `list`     | List env contract vars and resolution state        |
+| `set`      | Set an env value (.hack/.env or secret backend)    |
+| `unset`    | Unset an env value (.hack/.env and secret backend) |
+| `backend`  | Manage env/secret backend strategy                 |
 
 #### hack env list
 
@@ -560,12 +559,12 @@ Usage: `hack env list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--json` | boolean | false | Output JSON (machine-readable) |
-| `--show-secrets` | boolean | false | Print secret values (secret backend) in plaintext |
+| Flag                 | Type    | Default | Description                                       |
+| -------------------- | ------- | ------- | ------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)    |
+| `--project <name>`   | string  | -       | Target a registered project by name               |
+| `--json`             | boolean | false   | Output JSON (machine-readable)                    |
+| `--show-secrets`     | boolean | false   | Print secret values (secret backend) in plaintext |
 
 #### hack env set
 
@@ -587,10 +586,10 @@ Usage: `hack env unset [key] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack env backend
 
@@ -598,10 +597,10 @@ Usage: `hack env backend <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `status` | Show configured env/secret backend strategy |
-| `use` | Select env/secret backend strategy |
+| Subcommand | Summary                                     |
+| ---------- | ------------------------------------------- |
+| `status`   | Show configured env/secret backend strategy |
+| `use`      | Select env/secret backend strategy          |
 
 #### hack env backend status
 
@@ -609,9 +608,9 @@ Usage: `hack env backend status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag     | Type    | Default | Description                    |
+| -------- | ------- | ------- | ------------------------------ |
+| `--json` | boolean | false   | Output JSON (machine-readable) |
 
 #### hack env backend use
 
@@ -620,8 +619,8 @@ Usage: `hack env backend use <keychain|encrypted_file|cloud> [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--provider <aws|gcp|azure|vault>` | string | - | Cloud provider when backend is `cloud` |
+| --- | --- | --- | --- | --- | --- | --- |
+| `--provider <aws | gcp | azure | vault>` | string | - | Cloud provider when backend is `cloud` |
 | `--store-path <path>` | string | - | Encrypted file path when backend is `encrypted_file` |
 | `--secret-project <id>` | string | - | Optional cloud account/project identifier |
 | `--secret-prefix <prefix>` | string | - | Optional cloud secret name prefix |
@@ -635,16 +634,16 @@ With no subcommand, opens an interactive picker of active sessions and available
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List active sessions |
-| `start` | Start or attach to a session for a project |
-| `stop` | Stop (kill) a session |
-| `attach` | Attach to an existing session |
-| `exec` | Execute a command in a session |
-| `panes` | List panes in a tmux session |
-| `capture` | Capture recent output from a tmux session |
-| `tail` | Tail output from a tmux session |
+| Subcommand | Summary                                    |
+| ---------- | ------------------------------------------ |
+| `list`     | List active sessions                       |
+| `start`    | Start or attach to a session for a project |
+| `stop`     | Stop (kill) a session                      |
+| `attach`   | Attach to an existing session              |
+| `exec`     | Execute a command in a session             |
+| `panes`    | List panes in a tmux session               |
+| `capture`  | Capture recent output from a tmux session  |
+| `tail`     | Tail output from a tmux session            |
 
 #### hack session start
 
@@ -652,11 +651,11 @@ Usage: `hack session start [project] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--up` | boolean | false | Run hack up -d before attaching |
-| `--new` | boolean | false | Force create new session even if one exists |
-| `--name <suffix>` | string | - | Custom suffix for new session (e.g., agent-1) |
+| Flag              | Type    | Default | Description                                   |
+| ----------------- | ------- | ------- | --------------------------------------------- |
+| `--up`            | boolean | false   | Run hack up -d before attaching               |
+| `--new`           | boolean | false   | Force create new session even if one exists   |
+| `--name <suffix>` | string  | -       | Custom suffix for new session (e.g., agent-1) |
 
 #### hack session panes
 
@@ -664,10 +663,10 @@ Usage: `hack session panes <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag       | Type    | Default | Description                          |
+| ---------- | ------- | ------- | ------------------------------------ |
+| `--json`   | boolean | false   | Output NDJSON stream (start/log/end) |
+| `--pretty` | boolean | false   | Output human-friendly text           |
 
 #### hack session capture
 
@@ -675,12 +674,12 @@ Usage: `hack session capture <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--target <target>` | string | - | Tmux pane target (default: active pane) |
-| `--lines <n>` | number | 200 | Number of lines to capture |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag                | Type    | Default | Description                             |
+| ------------------- | ------- | ------- | --------------------------------------- |
+| `--target <target>` | string  | -       | Tmux pane target (default: active pane) |
+| `--lines <n>`       | number  | 200     | Number of lines to capture              |
+| `--json`            | boolean | false   | Output NDJSON stream (start/log/end)    |
+| `--pretty`          | boolean | false   | Output human-friendly text              |
 
 #### hack session tail
 
@@ -688,14 +687,14 @@ Usage: `hack session tail <session> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--target <target>` | string | - | Tmux pane target (default: active pane) |
-| `--lines <n>` | number | 200 | Number of lines to capture |
-| `--interval-ms <ms>` | number | 500 | Polling interval in milliseconds |
-| `--max-ms <ms>` | number | 5000 | Stop tailing after N milliseconds |
-| `--json` | boolean | false | Output NDJSON stream (start/log/end) |
-| `--pretty` | boolean | false | Output human-friendly text |
+| Flag                 | Type    | Default | Description                             |
+| -------------------- | ------- | ------- | --------------------------------------- |
+| `--target <target>`  | string  | -       | Tmux pane target (default: active pane) |
+| `--lines <n>`        | number  | 200     | Number of lines to capture              |
+| `--interval-ms <ms>` | number  | 500     | Polling interval in milliseconds        |
+| `--max-ms <ms>`      | number  | 5000    | Stop tailing after N milliseconds       |
+| `--json`             | boolean | false   | Output NDJSON stream (start/log/end)    |
+| `--pretty`           | boolean | false   | Output human-friendly text              |
 
 ### hack ssh
 
@@ -703,27 +702,25 @@ Usage: `hack ssh [session] [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-H`, `--host <host>` | string | - | SSH host (hostname or IP) |
-| `-u`, `--user <user>` | string | - | SSH username |
-| `-t`, `--tailscale` | boolean | false | Use Tailscale SSH |
-| `-d`, `--direct` | boolean | false | Use direct SSH (requires --host) |
-| `-p`, `--port <port>` | string | - | SSH port for direct connection (default: 22) |
+| Flag                  | Type    | Default | Description                                  |
+| --------------------- | ------- | ------- | -------------------------------------------- |
+| `-H`, `--host <host>` | string  | -       | SSH host (hostname or IP)                    |
+| `-u`, `--user <user>` | string  | -       | SSH username                                 |
+| `-t`, `--tailscale`   | boolean | false   | Use Tailscale SSH                            |
+| `-d`, `--direct`      | boolean | false   | Use direct SSH (requires --host)             |
+| `-p`, `--port <port>` | string  | -       | SSH port for direct connection (default: 22) |
 
 ### hack tickets
 
 Usage: `hack tickets <args...>`
 
-`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`).
-Run `hack tickets` with no args to see available subcommands.
+`hack tickets` is a convenience alias for the tickets extension (`hack x tickets ...`). Run `hack tickets` with no args to see available subcommands.
 
 ### hack linear
 
 Usage: `hack linear <args...>`
 
-`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`).
-Run `hack linear` with no args to see available subcommands.
+`hack linear` is a convenience alias for the Linear extension (`hack x linear ...`). Run `hack linear` with no args to see available subcommands.
 
 ## Internal commands
 
@@ -733,8 +730,8 @@ Usage: `hack internal <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
+| Subcommand    | Summary                             |
+| ------------- | ----------------------------------- |
 | `extra-hosts` | Manage internal Compose extra_hosts |
 
 #### hack internal extra-hosts
@@ -743,17 +740,17 @@ Usage: `hack internal extra-hosts <subcommand> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <path>` | string | - | Start directory (defaults to cwd) |
+| Flag                  | Type   | Default | Description                       |
+| --------------------- | ------ | ------- | --------------------------------- |
+| `-p`, `--path <path>` | string | -       | Start directory (defaults to cwd) |
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `set` | Set an internal extra_hosts entry |
-| `unset` | Remove an internal extra_hosts entry |
-| `list` | List internal extra_hosts entries |
+| Subcommand | Summary                              |
+| ---------- | ------------------------------------ |
+| `set`      | Set an internal extra_hosts entry    |
+| `unset`    | Remove an internal extra_hosts entry |
+| `list`     | List internal extra_hosts entries    |
 
 #### hack internal extra-hosts set
 
@@ -775,11 +772,11 @@ Usage: `hack gateway <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `enable` | Enable the gateway and start hackd |
-| `setup` | Guided gateway setup (enable + token) |
-| `disable` | Disable the gateway (does not stop hackd) |
+| Subcommand | Summary                                   |
+| ---------- | ----------------------------------------- |
+| `enable`   | Enable the gateway and start hackd        |
+| `setup`    | Guided gateway setup (enable + token)     |
+| `disable`  | Disable the gateway (does not stop hackd) |
 
 #### hack gateway enable
 
@@ -787,10 +784,10 @@ Usage: `hack gateway enable [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack gateway setup
 
@@ -798,13 +795,13 @@ Usage: `hack gateway setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--qr` | boolean | true | Force QR output after setup (default) |
-| `--no-qr` | boolean | false | Skip QR output after setup |
-| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
+| Flag                 | Type    | Default | Description                                         |
+| -------------------- | ------- | ------- | --------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
+| `--project <name>`   | string  | -       | Target a registered project by name                 |
+| `--qr`               | boolean | true    | Force QR output after setup (default)               |
+| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
+| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
 
 #### hack gateway disable
 
@@ -812,10 +809,10 @@ Usage: `hack gateway disable [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 ### hack node
 
@@ -823,20 +820,20 @@ Usage: `hack node <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `init` | Initialize this host as a node and emit enrollment bundle |
-| `pair` | Pair node with one-command or expiring verification-code flow |
-| `ssh` | Manage SSH bootstrap for node pairing and remote runs |
-| `add` | Add a node from an enrollment bundle |
-| `list` | List registered nodes |
-| `status` | Probe node health and report live status |
-| `use` | Set default node |
-| `remove` | Remove node registration |
-| `workspace` | Inspect and repair node workspace map entries |
-| `routes` | Inspect and repair controller-side remote route bridge |
-| `provider` | Manage provider-specific node bootstrap workflows |
-| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints |
+| Subcommand     | Summary                                                       |
+| -------------- | ------------------------------------------------------------- |
+| `init`         | Initialize this host as a node and emit enrollment bundle     |
+| `pair`         | Pair node with one-command or expiring verification-code flow |
+| `ssh`          | Manage SSH bootstrap for node pairing and remote runs         |
+| `add`          | Add a node from an enrollment bundle                          |
+| `list`         | List registered nodes                                         |
+| `status`       | Probe node health and report live status                      |
+| `use`          | Set default node                                              |
+| `remove`       | Remove node registration                                      |
+| `workspace`    | Inspect and repair node workspace map entries                 |
+| `routes`       | Inspect and repair controller-side remote route bridge        |
+| `provider`     | Manage provider-specific node bootstrap workflows             |
+| `devcontainer` | Manage remote node devcontainer lifecycle and attach hints    |
 
 Examples:
 
@@ -941,12 +938,12 @@ Usage: `hack node workspace <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `list` | List node-local workspace map entries |
-| `resolve` | Resolve a map entry by controller project selector |
-| `attach` | Attach an existing local workspace to project selector |
-| `remove` | Remove a map entry by project selector |
+| Subcommand | Summary                                                |
+| ---------- | ------------------------------------------------------ |
+| `list`     | List node-local workspace map entries                  |
+| `resolve`  | Resolve a map entry by controller project selector     |
+| `attach`   | Attach an existing local workspace to project selector |
+| `remove`   | Remove a map entry by project selector                 |
 
 Examples:
 
@@ -963,10 +960,10 @@ Usage: `hack node routes <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `status` | Show controller-side remote route bridge state |
-| `repair` | Re-render and re-apply persisted route bridge stack |
+| Subcommand | Summary                                             |
+| ---------- | --------------------------------------------------- |
+| `status`   | Show controller-side remote route bridge state      |
+| `repair`   | Re-render and re-apply persisted route bridge stack |
 
 Examples:
 
@@ -982,11 +979,11 @@ Usage: `hack dispatch <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `run` | Dispatch a command to a node workspace |
-| `status` | Show dispatched run status |
-| `logs` | Show or follow persisted/remote run logs |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `run`      | Dispatch a command to a node workspace   |
+| `status`   | Show dispatched run status               |
+| `logs`     | Show or follow persisted/remote run logs |
 
 #### hack dispatch run
 
@@ -995,15 +992,15 @@ Usage: `hack dispatch run --project <name|id> [options] -- <command...>`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name|id>` | string | - | Project name or id |
-| `--node <id|default|auto>` | string | auto | Target node id, or use default/auto |
+| --- | --- | --- | --- | --- | --- | --- |
+| `--project <name | id>` | string | - | Project name or id |
+| `--node <id | default | auto>` | string | auto | Target node id, or use default/auto |
 | `--provider <provider>` | string | - | Provider route override used when resolving profile/bootstrap intent |
 | `--profile <profile-id>` | string | - | Provider profile route override |
 | `--bootstrap-if-needed` | boolean | false | Allow guarded provider bootstrap handoff when no reachable node is found |
 | `--branch <branch>` | string | current | Target branch on selected node |
 | `--ticket <ticket-id>` | string | - | Ticket id to associate with run metadata |
-| `--runner <generic|codex|claude|cursor>` | string | `generic` | Runner identity for policy and audit |
+| `--runner <generic | codex | claude | cursor>` | string | `generic` | Runner identity for policy and audit |
 | `--approve` | boolean | false | Approve high/critical risk commands non-interactively |
 | `--pr` | boolean | false | Push branch + create/update GitHub PR on successful run |
 | `--pr-base <branch>` | string | `main` | Base branch used with `--pr` |
@@ -1050,12 +1047,12 @@ If you run `hack remote` with no subcommand, it prints status and offers to run
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `setup` | Run the guided gateway setup |
-| `status` | Show remote/gateway status |
-| `monitor` | Open a remote status TUI |
-| `qr` | Print a QR payload for remote access |
+| Subcommand | Summary                              |
+| ---------- | ------------------------------------ |
+| `setup`    | Run the guided gateway setup         |
+| `status`   | Show remote/gateway status           |
+| `monitor`  | Open a remote status TUI             |
+| `qr`       | Print a QR payload for remote access |
 
 #### hack remote setup
 
@@ -1063,13 +1060,13 @@ Usage: `hack remote setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
-| `--qr` | boolean | true | Force QR output after setup (default) |
-| `--no-qr` | boolean | false | Skip QR output after setup |
-| `--yes` | boolean | false | Skip confirmation prompts when printing QR payloads |
+| Flag                 | Type    | Default | Description                                         |
+| -------------------- | ------- | ------- | --------------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)      |
+| `--project <name>`   | string  | -       | Target a registered project by name                 |
+| `--qr`               | boolean | true    | Force QR output after setup (default)               |
+| `--no-qr`            | boolean | false   | Skip QR output after setup                          |
+| `--yes`              | boolean | false   | Skip confirmation prompts when printing QR payloads |
 
 #### hack remote status
 
@@ -1077,10 +1074,10 @@ Usage: `hack remote status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack remote monitor
 
@@ -1088,10 +1085,10 @@ Usage: `hack remote monitor [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--project <name>` | string | - | Target a registered project by name |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string | -       | Run against a repo path (overrides cwd search) |
+| `--project <name>`   | string | -       | Target a registered project by name            |
 
 #### hack remote qr
 
@@ -1119,9 +1116,9 @@ Usage: `hack x <namespace> <command> [args...]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `args` | string[] | no | Extension command args (passed through) |
+| Name   | Type     | Required | Description                             |
+| ------ | -------- | -------- | --------------------------------------- |
+| `args` | string[] | no       | Extension command args (passed through) |
 
 Notes:
 
@@ -1136,15 +1133,15 @@ Usage: `hack setup <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `cursor` | Install Cursor rules for hack CLI usage |
-| `claude` | Install Claude Code hooks for hack CLI usage |
-| `codex` | Install Codex skill for hack CLI usage |
-| `tickets` | Install Codex skill for hack tickets usage |
-| `agents` | Install AGENTS.md / CLAUDE.md snippets |
-| `sync` | Refresh agent docs, skills, and MCP configs |
-| `mcp` | Install MCP configs for hack CLI usage (no-shell only) |
+| Subcommand | Summary                                                |
+| ---------- | ------------------------------------------------------ |
+| `cursor`   | Install Cursor rules for hack CLI usage                |
+| `claude`   | Install Claude Code hooks for hack CLI usage           |
+| `codex`    | Install Codex skill for hack CLI usage                 |
+| `tickets`  | Install Codex skill for hack tickets usage             |
+| `agents`   | Install AGENTS.md / CLAUDE.md snippets                 |
+| `sync`     | Refresh agent docs, skills, and MCP configs            |
+| `mcp`      | Install MCP configs for hack CLI usage (no-shell only) |
 
 #### hack setup cursor
 
@@ -1152,12 +1149,12 @@ Usage: `hack setup cursor [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup claude
 
@@ -1165,12 +1162,12 @@ Usage: `hack setup claude [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup codex
 
@@ -1178,12 +1175,12 @@ Usage: `hack setup codex [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 #### hack setup agents
 
@@ -1191,14 +1188,14 @@ Usage: `hack setup agents [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported docs |
-| `--agents-md` | boolean | false | Target AGENTS.md |
-| `--claude-md` | boolean | false | Target CLAUDE.md |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean | false   | Target all supported docs                      |
+| `--agents-md`        | boolean | false   | Target AGENTS.md                               |
+| `--claude-md`        | boolean | false   | Target CLAUDE.md                               |
+| `--check`            | boolean | false   | Check whether integration is installed         |
+| `--remove`           | boolean | false   | Remove integration files/config                |
 
 #### hack setup sync
 
@@ -1206,13 +1203,13 @@ Usage: `hack setup sync [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Target global (user) scope only |
-| `--all-scopes` | boolean | false | Target both project and global (user) scopes |
-| `--check` | boolean | false | Check whether integrations are installed |
-| `--remove` | boolean | false | Remove generated integration files/config |
+| Flag                 | Type    | Default | Description                                    |
+| -------------------- | ------- | ------- | ---------------------------------------------- |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search) |
+| `--global`           | boolean | false   | Target global (user) scope only                |
+| `--all-scopes`       | boolean | false   | Target both project and global (user) scopes   |
+| `--check`            | boolean | false   | Check whether integrations are installed       |
+| `--remove`           | boolean | false   | Remove generated integration files/config      |
 
 Automatic guardrail:
 
@@ -1225,16 +1222,16 @@ Usage: `hack setup mcp [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--global` | boolean | false | Use global (user) scope instead of project scope |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor integration |
-| `--claude` | boolean | false | Target Claude integration |
-| `--codex` | boolean | false | Target Codex integration |
-| `--check` | boolean | false | Check whether integration is installed |
-| `--remove` | boolean | false | Remove integration files/config |
+| Flag                 | Type    | Default | Description                                      |
+| -------------------- | ------- | ------- | ------------------------------------------------ |
+| `-p`, `--path <dir>` | string  | -       | Run against a repo path (overrides cwd search)   |
+| `--global`           | boolean | false   | Use global (user) scope instead of project scope |
+| `--all`              | boolean | false   | Target all supported clients                     |
+| `--cursor`           | boolean | false   | Target Cursor integration                        |
+| `--claude`           | boolean | false   | Target Claude integration                        |
+| `--codex`            | boolean | false   | Target Codex integration                         |
+| `--check`            | boolean | false   | Check whether integration is installed           |
+| `--remove`           | boolean | false   | Remove integration files/config                  |
 
 ### hack agent
 
@@ -1242,11 +1239,11 @@ Usage: `hack agent <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `prime` | Print agent primer text |
+| Subcommand | Summary                         |
+| ---------- | ------------------------------- |
+| `prime`    | Print agent primer text         |
 | `patterns` | Print agent init patterns guide |
-| `init` | Print agent init prompt |
+| `init`     | Print agent init prompt         |
 
 #### hack agent init
 
@@ -1254,10 +1251,10 @@ Usage: `hack agent init [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `-c`, `--client <cursor|claude|codex|print>` | string | - | Open init prompt in an agent client (or print) |
+| Flag                    | Type   | Default | Description                                    |
+| ----------------------- | ------ | ------- | ---------------------------------------------- | ------ | --- | ---------------------------------------------- |
+| `-p`, `--path <dir>`    | string | -       | Run against a repo path (overrides cwd search) |
+| `-c`, `--client <cursor | claude | codex   | print>`                                        | string | -   | Open init prompt in an agent client (or print) |
 
 ### hack mcp
 
@@ -1265,11 +1262,11 @@ Usage: `hack mcp <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `serve` | Run the MCP server over stdio |
-| `install` | Install MCP config for supported clients |
-| `print` | Print MCP config snippets |
+| Subcommand | Summary                                  |
+| ---------- | ---------------------------------------- |
+| `serve`    | Run the MCP server over stdio            |
+| `install`  | Install MCP config for supported clients |
+| `print`    | Print MCP config snippets                |
 
 #### hack mcp install
 
@@ -1277,17 +1274,17 @@ Usage: `hack mcp install [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <user|project>` | string | `user` | Write MCP config to user or project scope |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor MCP config |
-| `--claude` | boolean | false | Target Claude CLI MCP config |
-| `--codex` | boolean | false | Target Codex MCP config |
-| `--docs` | boolean | false | Update AGENTS.md and CLAUDE.md with hack usage |
-| `--agents-md` | boolean | false | Update AGENTS.md with hack usage |
-| `--claude-md` | boolean | false | Update CLAUDE.md with hack usage |
+| Flag                 | Type      | Default | Description                                    |
+| -------------------- | --------- | ------- | ---------------------------------------------- | ----------------------------------------- |
+| `--scope <user       | project>` | string  | `user`                                         | Write MCP config to user or project scope |
+| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean   | false   | Target all supported clients                   |
+| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
+| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
+| `--codex`            | boolean   | false   | Target Codex MCP config                        |
+| `--docs`             | boolean   | false   | Update AGENTS.md and CLAUDE.md with hack usage |
+| `--agents-md`        | boolean   | false   | Update AGENTS.md with hack usage               |
+| `--claude-md`        | boolean   | false   | Update CLAUDE.md with hack usage               |
 
 Notes:
 
@@ -1300,14 +1297,14 @@ Usage: `hack mcp print [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <user|project>` | string | `user` | Print MCP config for user or project scope |
-| `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
-| `--all` | boolean | false | Target all supported clients |
-| `--cursor` | boolean | false | Target Cursor MCP config |
-| `--claude` | boolean | false | Target Claude CLI MCP config |
-| `--codex` | boolean | false | Target Codex MCP config |
+| Flag                 | Type      | Default | Description                                    |
+| -------------------- | --------- | ------- | ---------------------------------------------- | ------------------------------------------ |
+| `--scope <user       | project>` | string  | `user`                                         | Print MCP config for user or project scope |
+| `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
+| `--all`              | boolean   | false   | Target all supported clients                   |
+| `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
+| `--claude`           | boolean   | false   | Target Claude CLI MCP config                   |
+| `--codex`            | boolean   | false   | Target Codex MCP config                        |
 
 ## Diagnostics commands
 
@@ -1346,17 +1343,17 @@ Usage: `hack daemon <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `start` | Start hackd (local daemon) |
-| `stop` | Stop hackd |
-| `restart` | Restart hackd |
-| `status` | Show hackd status |
-| `metrics` | Show hackd metrics |
-| `logs` | Show hackd logs |
-| `clear` | Clear stale hackd pid/socket files |
-| `install` | Install hackd as a launchd service (macOS) |
-| `uninstall` | Uninstall hackd launchd service (macOS) |
+| Subcommand  | Summary                                    |
+| ----------- | ------------------------------------------ |
+| `start`     | Start hackd (local daemon)                 |
+| `stop`      | Stop hackd                                 |
+| `restart`   | Restart hackd                              |
+| `status`    | Show hackd status                          |
+| `metrics`   | Show hackd metrics                         |
+| `logs`      | Show hackd logs                            |
+| `clear`     | Clear stale hackd pid/socket files         |
+| `install`   | Install hackd as a launchd service (macOS) |
+| `uninstall` | Uninstall hackd launchd service (macOS)    |
 
 Autostart + self-heal behavior:
 
@@ -1373,9 +1370,9 @@ Usage: `hack daemon start [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--foreground` | boolean | false | Run hackd in the foreground (debug) |
+| Flag           | Type    | Default | Description                         |
+| -------------- | ------- | ------- | ----------------------------------- |
+| `--foreground` | boolean | false   | Run hackd in the foreground (debug) |
 
 #### hack daemon status
 
@@ -1383,9 +1380,9 @@ Usage: `hack daemon status [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--json` | boolean | false | Output JSON (machine-readable, includes launchd info on macOS) |
+| Flag     | Type    | Default | Description                                                    |
+| -------- | ------- | ------- | -------------------------------------------------------------- |
+| `--json` | boolean | false   | Output JSON (machine-readable, includes launchd info on macOS) |
 
 #### hack daemon logs
 
@@ -1393,35 +1390,32 @@ Usage: `hack daemon logs [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--tail <n>` | number | 200 | Tail last N log lines |
+| Flag         | Type   | Default | Description           |
+| ------------ | ------ | ------- | --------------------- |
+| `--tail <n>` | number | 200     | Tail last N log lines |
 
 #### hack daemon install
 
 Usage: `hack daemon install [options]`
 
-Installs hackd as a launchd service on macOS. The daemon will be managed by launchd
-and can optionally start automatically on login.
+Installs hackd as a launchd service on macOS. The daemon will be managed by launchd and can optionally start automatically on login.
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--run-at-load` | boolean | true | Start hackd automatically on login |
-| `--no-run-at-load` | boolean | - | Do not start hackd automatically on login |
-| `--gui-only` | boolean | true | Only run in GUI sessions (Aqua) |
-| `--no-gui-only` | boolean | - | Run in all session types (including SSH) |
+| Flag               | Type    | Default | Description                               |
+| ------------------ | ------- | ------- | ----------------------------------------- |
+| `--run-at-load`    | boolean | true    | Start hackd automatically on login        |
+| `--no-run-at-load` | boolean | -       | Do not start hackd automatically on login |
+| `--gui-only`       | boolean | true    | Only run in GUI sessions (Aqua)           |
+| `--no-gui-only`    | boolean | -       | Run in all session types (including SSH)  |
 
-The service uses the label `dance.hack.hackd` and writes its plist to
-`~/Library/LaunchAgents/dance.hack.hackd.plist`.
+The service uses the label `dance.hack.hackd` and writes its plist to `~/Library/LaunchAgents/dance.hack.hackd.plist`.
 
 #### hack daemon uninstall
 
 Usage: `hack daemon uninstall`
 
-Uninstalls the hackd launchd service on macOS. Removes the plist and unloads
-the service from launchd.
+Uninstalls the hackd launchd service on macOS. Removes the plist and unloads the service from launchd.
 
 ### hack log-pipe
 
@@ -1429,10 +1423,10 @@ Usage: `hack log-pipe [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--format <auto|docker-compose|plain>` | string | `auto` | How to parse incoming lines from stdin |
-| `--stream <stdout|stderr>` | string | `stdout` | Treat stdin as stdout or stderr |
+| Flag              | Type           | Default | Description |
+| ----------------- | -------------- | ------- | ----------- | ------------------------------- | -------------------------------------- |
+| `--format <auto   | docker-compose | plain>` | string      | `auto`                          | How to parse incoming lines from stdin |
+| `--stream <stdout | stderr>`       | string  | `stdout`    | Treat stdin as stdout or stderr |
 
 ### hack help
 
@@ -1440,9 +1434,9 @@ Usage: `hack help [path...]`
 
 Arguments:
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `path` | string[] | no | Command path to show help for (e.g. `global logs`) |
+| Name   | Type     | Required | Description                                        |
+| ------ | -------- | -------- | -------------------------------------------------- |
+| `path` | string[] | no       | Command path to show help for (e.g. `global logs`) |
 
 ### hack update
 
@@ -1450,12 +1444,12 @@ Usage: `hack update [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--check` | boolean | false | Check for updates (do not install) |
-| `--yes` | boolean | false | Apply update without prompting |
-| `--tag <tag>` | string | - | Update to a specific release tag (e.g. v1.4.0) |
-| `--json` | boolean | false | Output JSON (machine-readable) |
+| Flag          | Type    | Default | Description                                    |
+| ------------- | ------- | ------- | ---------------------------------------------- |
+| `--check`     | boolean | false   | Check for updates (do not install)             |
+| `--yes`       | boolean | false   | Apply update without prompting                 |
+| `--tag <tag>` | string  | -       | Update to a specific release tag (e.g. v1.4.0) |
+| `--json`      | boolean | false   | Output JSON (machine-readable)                 |
 
 ### hack version
 
@@ -1469,23 +1463,23 @@ Usage: `hack secrets <subcommand>`
 
 Subcommands:
 
-| Subcommand | Summary |
-| --- | --- |
-| `set` | Store a secret |
-| `get` | Print a secret (exit 1 if missing) |
-| `delete` | Delete a stored secret |
+| Subcommand | Summary                            |
+| ---------- | ---------------------------------- |
+| `set`      | Store a secret                     |
+| `get`      | Print a secret (exit 1 if missing) |
+| `delete`   | Delete a stored secret             |
 
 Options (all subcommands):
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
+| Flag                  | Type   | Default    | Description                       |
+| --------------------- | ------ | ---------- | --------------------------------- |
 | `--service <service>` | string | `hack-cli` | Override Bun.secrets service name |
 
 Arguments (set/get/delete):
 
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | no | Secret name (prompted if omitted) |
+| Name   | Type   | Required | Description                       |
+| ------ | ------ | -------- | --------------------------------- |
+| `name` | string | no       | Secret name (prompted if omitted) |
 
 ## Fun
 
@@ -1495,7 +1489,7 @@ Usage: `hack the planet [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--variant <cut|mash|cycle|random>` | string | `cycle` | Animation variant |
-| `--loop` | boolean | true | Loop until Ctrl+C |
+| Flag            | Type    | Default | Description       |
+| --------------- | ------- | ------- | ----------------- | ------ | ------- | ----------------- |
+| `--variant <cut | mash    | cycle   | random>`          | string | `cycle` | Animation variant |
+| `--loop`        | boolean | true    | Loop until Ctrl+C |
diff --git a/docs/extensions.md b/docs/extensions.md
index a2ef0b51c..de9cf86b7 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -13,8 +13,7 @@ If you just want remote access working, start here:
 hack remote setup
 ```
 
-The wizard enables the gateway for the current project, creates a token + QR, and can configure
-Cloudflare/Tailscale/SSH exposure in one flow.
+The wizard enables the gateway for the current project, creates a token + QR, and can configure Cloudflare/Tailscale/SSH exposure in one flow.
 
 ## Behavior
 
@@ -22,8 +21,7 @@ Cloudflare/Tailscale/SSH exposure in one flow.
 - Each extension provides a manifest + commands (`ExtensionDefinition`).
 - The CLI dispatches extension commands via `hack x <namespace> <command>`.
 - Global enablement lives in `~/.hack/hack.config.json` (`hack config set --global ...`).
-- Per-project overrides live in `.hack/hack.config.json` and typically win over global values
-  (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
+- Per-project overrides live in `.hack/hack.config.json` and typically win over global values (except global-only extensions like Cloudflare/Tailscale/GitHub, which ignore project overrides).
 - Built-in Gateway enablement is project-scoped: `controlPlane.gateway.enabled` opts a project into routing.
 
 ## Extension definition (API surface)
@@ -49,14 +47,14 @@ export type ExtensionCommand = {
 ```
 
 The `ExtensionCommandContext` includes:
+
 - `controlPlaneConfig` (parsed config)
 - `projectId` and `projectName` (when available)
 - `logger` and `cwd`
 
 ## Config + enablement
 
-Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by
-`src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
+Global `controlPlane` lives in `~/.hack/hack.config.json` and is parsed by `src/control-plane/sdk/config.ts`. Per-project overrides use `.hack/hack.config.json`.
 
 Enable a global extension by id:
 
@@ -80,10 +78,10 @@ Shortcut for gateway (project-scoped):
 }
 ```
 
-Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config.
-Project overrides for these are ignored.
+Global-only extensions (e.g. Cloudflare, Tailscale, GitHub) must be configured in the global config. Project overrides for these are ignored.
 
 CLI helpers:
+
 - `hack gateway enable` (sets both gateway + extension flags)
 - `hack gateway setup` (guided enable + optional writes + token creation + QR by default)
 - `hack config set --global 'controlPlane.extensions[\"dance.hack.gateway\"].enabled' true`
@@ -108,10 +106,10 @@ Use `hack x <namespace> help` to list commands.
 - GitHub: `hack x github connect|oauth-connect|disconnect|profiles|use|status|pr-upsert`
 - Linear: `hack x linear setup|connect|oauth-connect|disconnect|status|profiles|use|projects|project-bind|sync-issue|sync-project`
 
-Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also
-requires global `controlPlane.gateway.allowWrites = true`).
+Gateway tokens default to `read` scope. Use `--scope write` to permit non-GET requests (also requires global `controlPlane.gateway.allowWrites = true`).
 
 Current gateway API surface (HTTP/WS):
+
 - `GET /v1/status`, `GET /v1/metrics`, `GET /v1/projects`, `GET /v1/ps`
 - `GET/POST /control-plane/projects/:id/jobs`
 - `GET /control-plane/projects/:id/jobs/:jobId`
@@ -122,6 +120,7 @@ Current gateway API surface (HTTP/WS):
 - `WS /control-plane/projects/:id/shells/:shellId/stream` (requires write token + allowWrites)
 
 Local auth service surface (daemon + global Caddy route):
+
 - `GET /health`
 - `GET /v1/auth/providers`
 - `GET /gh/start` (GitHub browser OAuth entrypoint)
@@ -130,15 +129,14 @@ Local auth service surface (daemon + global Caddy route):
 - `GET /v1/auth/github/start`
 - `GET /v1/auth/github/flows/:id`
 
-Interactive shell/TTY is available via the shell stream endpoints; use
-`hack x supervisor shell` or see protocol below.
+Interactive shell/TTY is available via the shell stream endpoints; use `hack x supervisor shell` or see protocol below.
 
 For full usage guidance and structured workflow patterns, see `gateway-api.md`.
 
 For exposure helpers, see the guides:
+
 - `guides/remote-cloudflare.md`
-- `guides/remote-tailscale.md`
-DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
+- `guides/remote-tailscale.md` DNS note: Cloudflare Tunnel uses a CNAME (`<tunnel-id>.cfargotunnel.com`) in your Cloudflare zone.
 
 ## Command reference
 
@@ -150,13 +148,14 @@ Usage: `hack x gateway token-create [options] [label]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--scope <read|write>` | string | `read` | Token scope |
-| `--write` | boolean | false | Shortcut for `--scope write` |
-| `--label <label>` | string | - | Optional label |
+| Flag              | Type    | Default | Description                  |
+| ----------------- | ------- | ------- | ---------------------------- | ----------- |
+| `--scope <read    | write>` | string  | `read`                       | Token scope |
+| `--write`         | boolean | false   | Shortcut for `--scope write` |
+| `--label <label>` | string  | -       | Optional label               |
 
 Notes:
+
 - The first non-flag argument is treated as the label if `--label` is not used.
 
 #### token-list
@@ -177,11 +176,11 @@ Usage: `hack x supervisor job-list [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-create
 
@@ -189,14 +188,14 @@ Usage: `hack x supervisor job-create [options] -- <command...>`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--runner <name>` | string | `generic` | Runner name |
-| `--cwd <path>` | string | - | Working directory (relative to project root) |
-| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
-| `--json` | boolean | false | Output JSON |
+| Flag                | Type    | Default   | Description                                  |
+| ------------------- | ------- | --------- | -------------------------------------------- |
+| `--project <name>`  | string  | -         | Target a registered project                  |
+| `--path <dir>`      | string  | -         | Target a repo path                           |
+| `--runner <name>`   | string  | `generic` | Runner name                                  |
+| `--cwd <path>`      | string  | -         | Working directory (relative to project root) |
+| `--env <KEY=VALUE>` | string  | -         | Environment override (repeatable)            |
+| `--json`            | boolean | false     | Output JSON                                  |
 
 ### GitHub extension (`hack x github`)
 
@@ -259,10 +258,9 @@ hack x github pr-upsert \
 ```
 
 Notes:
-- Profile config lives at:
-  `controlPlane.extensions["dance.hack.github"].config.profiles`.
-- Profile selection precedence is:
-  `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
+
+- Profile config lives at: `controlPlane.extensions["dance.hack.github"].config.profiles`.
+- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.github.profile` -> `config.defaultProfile`.
 - Keychain storage uses profile-specific `authRef` + `service`.
 - Token resolution order is keychain first, then environment fallback (`tokenEnv`).
 - If token metadata includes `expiresAt`, auth resolution attempts automatic GitHub App refresh using profile `appId`, `installationId`, and private key source.
@@ -341,8 +339,7 @@ Detailed design and sequencing live in:
 
 ### Linear extension (`hack x linear`)
 
-Linear integration supports multiple auth profiles, project-level binding, and manual sync in both
-directions between Linear issues and hack tickets.
+Linear integration supports multiple auth profiles, project-level binding, and manual sync in both directions between Linear issues and hack tickets.
 
 Quick start:
 
@@ -365,11 +362,9 @@ hack x linear sync-project --from hack --owner both
 ```
 
 Notes:
-- Profile selection precedence is:
-  `--profile` -> `controlPlane.routing.overrides.linear.profile` ->
-  `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
-- Project mapping is stored in project config:
-  `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
+
+- Profile selection precedence is: `--profile` -> `controlPlane.routing.overrides.linear.profile` -> `controlPlane.extensions["dance.hack.linear"].config.defaultProfile` -> implicit `default`.
+- Project mapping is stored in project config: `controlPlane.routing.overrides.linear.projectId|projectName|teamId`.
 - Sync is manual by default (`sync-issue` / `sync-project`); there is no background autosync yet.
 - Ticket provenance is preserved during sync via `owner`, `source`, `tags`, and `external*` linkage fields.
 - `hack x linear connect` uses token mode when `--token`/`--stdin`/`$HACK_LINEAR_API_TOKEN` is present, and otherwise falls back to browser OAuth.
@@ -382,8 +377,7 @@ Notes:
 - Auth-broker Linear endpoints:
   - OAuth callback page: `/linear/callback`
   - Webhook ingest: `/linear/webhooks` (legacy alias: `/v1/integrations/linear/webhook`)
-- Sync toggles are configurable at
-  `controlPlane.extensions["dance.hack.linear"].config.sync`:
+- Sync toggles are configurable at `controlPlane.extensions["dance.hack.linear"].config.sync`:
   - `labels` (default `false`)
   - `statuses` (default `true`)
   - `dependencies` (default `true`)
@@ -396,11 +390,11 @@ Usage: `hack x supervisor job-show <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-cancel
 
@@ -408,10 +402,10 @@ Usage: `hack x supervisor job-cancel <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
+| Flag               | Type   | Default | Description                 |
+| ------------------ | ------ | ------- | --------------------------- |
+| `--project <name>` | string | -       | Target a registered project |
+| `--path <dir>`     | string | -       | Target a repo path          |
 
 #### job-tail
 
@@ -419,15 +413,15 @@ Usage: `hack x supervisor job-tail <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--logs-from <n>` | number | 0 | Resume from log offset |
-| `--from <n>` | number | 0 | Alias for `--logs-from` |
-| `--json` | boolean | false | Output JSON |
+| Flag               | Type    | Default | Description                 |
+| ------------------ | ------- | ------- | --------------------------- |
+| `--project <name>` | string  | -       | Target a registered project |
+| `--path <dir>`     | string  | -       | Target a repo path          |
+| `--follow`         | boolean | true    | Follow logs (default)       |
+| `--no-follow`      | boolean | false   | Print logs and exit         |
+| `--logs-from <n>`  | number  | 0       | Resume from log offset      |
+| `--from <n>`       | number  | 0       | Alias for `--logs-from`     |
+| `--json`           | boolean | false   | Output JSON                 |
 
 #### job-attach
 
@@ -435,16 +429,16 @@ Usage: `hack x supervisor job-attach <job-id> [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--path <dir>` | string | - | Target a repo path |
-| `--follow` | boolean | true | Follow logs (default) |
-| `--no-follow` | boolean | false | Print logs and exit |
-| `--logs-from <n>` | number | 0 | Resume from log offset |
-| `--from <n>` | number | 0 | Alias for `--logs-from` |
-| `--events-from <n>` | number | 0 | Resume from event sequence |
-| `--json` | boolean | false | Output JSON |
+| Flag                | Type    | Default | Description                 |
+| ------------------- | ------- | ------- | --------------------------- |
+| `--project <name>`  | string  | -       | Target a registered project |
+| `--path <dir>`      | string  | -       | Target a repo path          |
+| `--follow`          | boolean | true    | Follow logs (default)       |
+| `--no-follow`       | boolean | false   | Print logs and exit         |
+| `--logs-from <n>`   | number  | 0       | Resume from log offset      |
+| `--from <n>`        | number  | 0       | Alias for `--logs-from`     |
+| `--events-from <n>` | number  | 0       | Resume from event sequence  |
+| `--json`            | boolean | false   | Output JSON                 |
 
 #### shell
 
@@ -452,20 +446,21 @@ Usage: `hack x supervisor shell [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--project <name>` | string | - | Target a registered project |
-| `--project-id <id>` | string | - | Target by project id (gateway) |
-| `--path <dir>` | string | - | Target a repo path |
-| `--gateway <url>` | string | `http://127.0.0.1:7788` | Gateway URL |
-| `--token <token>` | string | - | Gateway write token |
-| `--shell <path>` | string | - | Shell path |
-| `--cwd <path>` | string | - | Working directory |
-| `--cols <n>` | number | - | Terminal columns |
-| `--rows <n>` | number | - | Terminal rows |
-| `--env <KEY=VALUE>` | string | - | Environment override (repeatable) |
+| Flag                | Type   | Default                 | Description                       |
+| ------------------- | ------ | ----------------------- | --------------------------------- |
+| `--project <name>`  | string | -                       | Target a registered project       |
+| `--project-id <id>` | string | -                       | Target by project id (gateway)    |
+| `--path <dir>`      | string | -                       | Target a repo path                |
+| `--gateway <url>`   | string | `http://127.0.0.1:7788` | Gateway URL                       |
+| `--token <token>`   | string | -                       | Gateway write token               |
+| `--shell <path>`    | string | -                       | Shell path                        |
+| `--cwd <path>`      | string | -                       | Working directory                 |
+| `--cols <n>`        | number | -                       | Terminal columns                  |
+| `--rows <n>`        | number | -                       | Terminal rows                     |
+| `--env <KEY=VALUE>` | string | -                       | Environment override (repeatable) |
 
 Notes:
+
 - `--project` and `--project-id` are mutually exclusive.
 
 ### Cloudflare extension (`hack x cloudflare`)
@@ -476,15 +471,15 @@ Usage: `hack x cloudflare tunnel-print [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--hostname <host>` | string | - | Gateway hostname |
-| `--tunnel <name>` | string | `hack-gateway` | Tunnel name |
-| `--origin <url>` | string | `http://127.0.0.1:7788` | Gateway origin |
-| `--ssh-hostname <host>` | string | - | SSH hostname (optional) |
-| `--ssh-origin <url>` | string | `ssh://127.0.0.1:22` | SSH origin |
-| `--credentials-file <path>` | string | - | Cloudflared credentials file |
-| `--out <path>` | string | - | Write config to a file |
+| Flag                        | Type   | Default                 | Description                  |
+| --------------------------- | ------ | ----------------------- | ---------------------------- |
+| `--hostname <host>`         | string | -                       | Gateway hostname             |
+| `--tunnel <name>`           | string | `hack-gateway`          | Tunnel name                  |
+| `--origin <url>`            | string | `http://127.0.0.1:7788` | Gateway origin               |
+| `--ssh-hostname <host>`     | string | -                       | SSH hostname (optional)      |
+| `--ssh-origin <url>`        | string | `ssh://127.0.0.1:22`    | SSH origin                   |
+| `--credentials-file <path>` | string | -                       | Cloudflared credentials file |
+| `--out <path>`              | string | -                       | Write config to a file       |
 
 #### tunnel-setup
 
@@ -511,11 +506,11 @@ Usage: `hack x cloudflare tunnel-start [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path |
-| `--out <path>` | string | - | Alias for `--config` |
-| `--tunnel <name>` | string | - | Override tunnel name |
+| Flag              | Type   | Default                     | Description          |
+| ----------------- | ------ | --------------------------- | -------------------- |
+| `--config <path>` | string | `~/.cloudflared/config.yml` | Config path          |
+| `--out <path>`    | string | -                           | Alias for `--config` |
+| `--tunnel <name>` | string | -                           | Override tunnel name |
 
 #### tunnel-stop
 
@@ -527,10 +522,10 @@ Usage: `hack x cloudflare access-setup [options]`
 
 Options:
 
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--ssh-hostname <host>` | string | - | SSH hostname |
-| `--user <user>` | string | - | SSH username |
+| Flag                    | Type   | Default | Description  |
+| ----------------------- | ------ | ------- | ------------ |
+| `--ssh-hostname <host>` | string | -       | SSH hostname |
+| `--user <user>`         | string | -       | SSH username |
 
 ### Tailscale extension (`hack x tailscale`)
 
@@ -563,6 +558,7 @@ Usage: `hack x tailscale oauth-disconnect [--auth-ref <ref>] [--json]`
 Usage: `hack x tailscale ip [args...]`
 
 Notes:
+
 - `status` and `ip` forward extra args directly to `tailscale`.
 - `ip` defaults to `-4` when no args are provided.
 
@@ -611,17 +607,18 @@ The gateway binds to `127.0.0.1` by default. Expose it through one of:
 - SSH tunnel (ad‑hoc): `ssh -L 7788:127.0.0.1:7788 <host>`
 - Zero Trust/VPN (persistent): Tailscale, Cloudflare, etc. targeting the gateway port
 - Optional Caddy route for local convenience (`https://gateway.hack`):
-  - Add a small labeled container in the global Caddy compose that proxies to
-    `host.docker.internal:7788` (or `host-gateway` on Linux).
+  - Add a small labeled container in the global Caddy compose that proxies to `host.docker.internal:7788` (or `host-gateway` on Linux).
 
 Keep tokens read-only unless you explicitly need writes.
 
 Recommended order:
-1) Start with SSH tunneling for quick remote access.
-2) Move to a private Zero Trust/VPN network once you want persistent access.
-3) Add the Caddy route only for nicer local URLs (not required for remote access).
+
+1. Start with SSH tunneling for quick remote access.
+2. Move to a private Zero Trust/VPN network once you want persistent access.
+3. Add the Caddy route only for nicer local URLs (not required for remote access).
 
 Remote helper commands:
+
 - `hack remote status` shows gateway + exposure status.
 - `hack remote qr` emits QR payloads for SSH or gateway clients.
 

From 3f30fd29203869bf3394786576aa33ff65db00fa Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 19:18:13 +0000
Subject: [PATCH 093/134] HACK-448: checkpoint merge prep

---
 docs/cli.md        | 58 +++++++++++++++++++++++-----------------------
 docs/extensions.md |  6 ++---
 2 files changed, 32 insertions(+), 32 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index bf561b525..c4e86c2bc 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -70,12 +70,12 @@ Usage: `hack global <subcommand>`
 Subcommands:
 
 | Subcommand   | Summary                                                      |
-| ------------ | ------------------------------------------------------------ | ------- | ---- | ------ |
+| ------------ | ------------------------------------------------------------ |
 | `install`    | Bootstrap `~/.hack` and start Caddy + Grafana/Loki/Alloy     |
 | `up`         | Start global infra containers                                |
 | `down`       | Stop global infra containers                                 |
 | `status`     | Show status for global infra (containers + networks)         |
-| `logs`       | Tail global infra logs (caddy                                | grafana | loki | alloy) |
+| `logs`       | Tail global infra logs (`caddy`, `grafana`, `loki`, `alloy`) |
 | `ca`         | Export Caddy Local CA cert (print path or PEM)               |
 | `cert`       | Generate local TLS certs via mkcert (for non-Caddy services) |
 | `trust`      | Trust Caddy Local CA (macOS) so https://\*.hack is trusted   |
@@ -208,13 +208,13 @@ Usage: `hack up [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `-d`, `--detach` | boolean | false | Run in background (docker compose up -d) |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto \| local \| remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack down
 
@@ -223,12 +223,12 @@ Usage: `hack down [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto \| local \| remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack restart
 
@@ -237,12 +237,12 @@ Usage: `hack restart [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- |
 | `-p`, `--path <dir>` | string | - | Run against a repo path (overrides cwd search) |
 | `--project <name>` | string | - | Target a registered project by name |
 | `--branch <name>` | string | - | Run against a branch-specific instance |
 | `--profile <name[,name...]>` | string | - | Enable one or more compose profiles |
-| `--target <auto | local | remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
+| `--target <auto \| local \| remote>` | string | `auto` | Execution routing target (`auto` follows project execution mode and node affinity) |
 
 ### hack ps
 
@@ -619,8 +619,8 @@ Usage: `hack env backend use <keychain|encrypted_file|cloud> [options]`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- | --- |
-| `--provider <aws | gcp | azure | vault>` | string | - | Cloud provider when backend is `cloud` |
+| --- | --- | --- | --- |
+| `--provider <aws \| gcp \| azure \| vault>` | string | - | Cloud provider when backend is `cloud` |
 | `--store-path <path>` | string | - | Encrypted file path when backend is `encrypted_file` |
 | `--secret-project <id>` | string | - | Optional cloud account/project identifier |
 | `--secret-prefix <prefix>` | string | - | Optional cloud secret name prefix |
@@ -992,15 +992,15 @@ Usage: `hack dispatch run --project <name|id> [options] -- <command...>`
 Options:
 
 | Flag | Type | Default | Description |
-| --- | --- | --- | --- | --- | --- | --- |
-| `--project <name | id>` | string | - | Project name or id |
-| `--node <id | default | auto>` | string | auto | Target node id, or use default/auto |
+| --- | --- | --- | --- |
+| `--project <name \| id>` | string | - | Project name or id |
+| `--node <id \| default \| auto>` | string | auto | Target node id, or use default/auto |
 | `--provider <provider>` | string | - | Provider route override used when resolving profile/bootstrap intent |
 | `--profile <profile-id>` | string | - | Provider profile route override |
 | `--bootstrap-if-needed` | boolean | false | Allow guarded provider bootstrap handoff when no reachable node is found |
 | `--branch <branch>` | string | current | Target branch on selected node |
 | `--ticket <ticket-id>` | string | - | Ticket id to associate with run metadata |
-| `--runner <generic | codex | claude | cursor>` | string | `generic` | Runner identity for policy and audit |
+| `--runner <generic \| codex \| claude \| cursor>` | string | `generic` | Runner identity for policy and audit |
 | `--approve` | boolean | false | Approve high/critical risk commands non-interactively |
 | `--pr` | boolean | false | Push branch + create/update GitHub PR on successful run |
 | `--pr-base <branch>` | string | `main` | Base branch used with `--pr` |
@@ -1252,9 +1252,9 @@ Usage: `hack agent init [options]`
 Options:
 
 | Flag                    | Type   | Default | Description                                    |
-| ----------------------- | ------ | ------- | ---------------------------------------------- | ------ | --- | ---------------------------------------------- |
+| ----------------------- | ------ | ------- | ---------------------------------------------- |
 | `-p`, `--path <dir>`    | string | -       | Run against a repo path (overrides cwd search) |
-| `-c`, `--client <cursor | claude | codex   | print>`                                        | string | -   | Open init prompt in an agent client (or print) |
+| `-c`, `--client <cursor \| claude \| codex \| print>` | string | - | Open init prompt in an agent client (or print) |
 
 ### hack mcp
 
@@ -1274,9 +1274,9 @@ Usage: `hack mcp install [options]`
 
 Options:
 
-| Flag                 | Type      | Default | Description                                    |
-| -------------------- | --------- | ------- | ---------------------------------------------- | ----------------------------------------- |
-| `--scope <user       | project>` | string  | `user`                                         | Write MCP config to user or project scope |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `--scope <user \| project>` | string | `user` | Write MCP config to user or project scope |
 | `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
 | `--all`              | boolean   | false   | Target all supported clients                   |
 | `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
@@ -1297,9 +1297,9 @@ Usage: `hack mcp print [options]`
 
 Options:
 
-| Flag                 | Type      | Default | Description                                    |
-| -------------------- | --------- | ------- | ---------------------------------------------- | ------------------------------------------ |
-| `--scope <user       | project>` | string  | `user`                                         | Print MCP config for user or project scope |
+| Flag                 | Type   | Default | Description                                    |
+| -------------------- | ------ | ------- | ---------------------------------------------- |
+| `--scope <user \| project>` | string | `user` | Print MCP config for user or project scope |
 | `-p`, `--path <dir>` | string    | -       | Run against a repo path (overrides cwd search) |
 | `--all`              | boolean   | false   | Target all supported clients                   |
 | `--cursor`           | boolean   | false   | Target Cursor MCP config                       |
@@ -1423,10 +1423,10 @@ Usage: `hack log-pipe [options]`
 
 Options:
 
-| Flag              | Type           | Default | Description |
-| ----------------- | -------------- | ------- | ----------- | ------------------------------- | -------------------------------------- |
-| `--format <auto   | docker-compose | plain>` | string      | `auto`                          | How to parse incoming lines from stdin |
-| `--stream <stdout | stderr>`       | string  | `stdout`    | Treat stdin as stdout or stderr |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--format <auto \| docker-compose \| plain>` | string | `auto` | How to parse incoming lines from stdin |
+| `--stream <stdout \| stderr>` | string | `stdout` | Treat stdin as stdout or stderr |
 
 ### hack help
 
@@ -1489,7 +1489,7 @@ Usage: `hack the planet [options]`
 
 Options:
 
-| Flag            | Type    | Default | Description       |
-| --------------- | ------- | ------- | ----------------- | ------ | ------- | ----------------- |
-| `--variant <cut | mash    | cycle   | random>`          | string | `cycle` | Animation variant |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--variant <cut \| mash \| cycle \| random>` | string | `cycle` | Animation variant |
 | `--loop`        | boolean | true    | Loop until Ctrl+C |
diff --git a/docs/extensions.md b/docs/extensions.md
index de9cf86b7..e724e0dbe 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -148,9 +148,9 @@ Usage: `hack x gateway token-create [options] [label]`
 
 Options:
 
-| Flag              | Type    | Default | Description                  |
-| ----------------- | ------- | ------- | ---------------------------- | ----------- |
-| `--scope <read    | write>` | string  | `read`                       | Token scope |
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--scope <read \| write>` | string | `read` | Token scope |
 | `--write`         | boolean | false   | Shortcut for `--scope write` |
 | `--label <label>` | string  | -       | Optional label               |
 

From ddaaca56be20d39fb827a679bf7aa2c089a5e674 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:58:27 +0000
Subject: [PATCH 094/134] HACK-429: fix tickets checkout fallback wiring

---
 .../extensions/tickets/tickets-git-channel.ts | 133 +++++++++++++++---
 tests/tickets-git-channel.test.ts             |  56 ++++++++
 2 files changed, 168 insertions(+), 21 deletions(-)

diff --git a/src/control-plane/extensions/tickets/tickets-git-channel.ts b/src/control-plane/extensions/tickets/tickets-git-channel.ts
index 94aff0833..8a8cf3609 100644
--- a/src/control-plane/extensions/tickets/tickets-git-channel.ts
+++ b/src/control-plane/extensions/tickets/tickets-git-channel.ts
@@ -383,9 +383,10 @@ export function createGitTicketsChannel(opts: {
   }): Promise<{
     readonly checkoutRef?: string;
     readonly fetchFailure: string | null;
+    readonly allowFetchFailureFallback: boolean;
   }> => {
     if (!input.remoteUrl) {
-      return { fetchFailure: null };
+      return { fetchFailure: null, allowFetchFailureFallback: true };
     }
 
     const fetched = await fetchRemoteRef(remoteRef);
@@ -400,16 +401,20 @@ export function createGitTicketsChannel(opts: {
       return {
         checkoutRef: `origin/${branch}`,
         fetchFailure,
+        allowFetchFailureFallback: false,
       };
     }
 
     if (fetched.missing) {
       return legacyRemoteRef
         ? await resolveLegacyRemoteCheckoutPlan()
-        : { fetchFailure: null };
+        : { fetchFailure: null, allowFetchFailureFallback: true };
     }
 
-    return { fetchFailure: `git fetch failed: ${fetched.error}` };
+    return {
+      fetchFailure: `git fetch failed: ${fetched.error}`,
+      allowFetchFailureFallback: true,
+    };
   };
 
   const resolveLegacyFetchFailure = async (input: {
@@ -429,9 +434,10 @@ export function createGitTicketsChannel(opts: {
   const resolveLegacyRemoteCheckoutPlan = async (): Promise<{
     readonly checkoutRef?: string;
     readonly fetchFailure: string | null;
+    readonly allowFetchFailureFallback: boolean;
   }> => {
     if (!legacyRemoteRef) {
-      return { fetchFailure: null };
+      return { fetchFailure: null, allowFetchFailureFallback: true };
     }
 
     const legacyFetch = legacyTrackingRef
@@ -441,12 +447,16 @@ export function createGitTicketsChannel(opts: {
       return {
         checkoutRef: legacyTrackingRef ?? `origin/${branch}`,
         fetchFailure: null,
+        allowFetchFailureFallback: true,
       };
     }
     if (legacyFetch.missing) {
-      return { fetchFailure: null };
+      return { fetchFailure: null, allowFetchFailureFallback: true };
     }
-    return { fetchFailure: `git fetch failed: ${legacyFetch.error}` };
+    return {
+      fetchFailure: `git fetch failed: ${legacyFetch.error}`,
+      allowFetchFailureFallback: false,
+    };
   };
 
   const initializeOrphanTicketsBranch = async (): Promise<
@@ -486,7 +496,9 @@ export function createGitTicketsChannel(opts: {
     return { ok: true, pushRef: remoteRef };
   };
 
-  const checkoutLocalBranch = async (): Promise<
+  const checkoutLocalBranch = async (input: {
+    readonly pushRef: string;
+  }): Promise<
     | { readonly ok: true; readonly pushRef: string }
     | { readonly ok: false; readonly error: string }
   > => {
@@ -503,11 +515,12 @@ export function createGitTicketsChannel(opts: {
       return { ok: false, error: `git reset failed: ${reset.stderr.trim()}` };
     }
 
-    return { ok: true, pushRef: remoteRef };
+    return { ok: true, pushRef: input.pushRef };
   };
 
   const checkoutHead = async (input: {
     readonly remoteUrl: string | null;
+    readonly allowFetchFailureFallback: boolean;
   }): Promise<
     | { readonly ok: true; readonly pushRef: string }
     | { readonly ok: false; readonly error: string }
@@ -538,7 +551,21 @@ export function createGitTicketsChannel(opts: {
       return await initializeOrphanTicketsBranch();
     }
 
-    return await checkoutLocalBranch();
+    const preferredTrackingRef = await resolvePreferredTrackingRef();
+    const localFallback = resolveLocalCheckoutFallback({
+      fetchFailure: remotePlan.fetchFailure,
+      allowFetchFailureFallback:
+        input.allowFetchFailureFallback && remotePlan.allowFetchFailureFallback,
+      preferredTrackingRef,
+      remoteRef,
+      legacyTrackingRef,
+      legacyRemoteRef,
+    });
+    if (!localFallback.ok) {
+      return localFallback;
+    }
+
+    return await checkoutLocalBranch({ pushRef: localFallback.pushRef });
   };
 
   const mergeLegacyRefIntoCurrentBranch = async (input: {
@@ -556,10 +583,10 @@ export function createGitTicketsChannel(opts: {
       legacyTrackingRef
     );
     if (!fetched.ok) {
-      if (fetched.missing) {
-        return { ok: true, imported: false };
-      }
-      return { ok: true, imported: false };
+      return resolveLegacyImportFetchResult({
+        missing: fetched.missing,
+        error: fetched.error,
+      });
     }
 
     const legacyPaths = await listLegacyEventPaths({
@@ -592,7 +619,9 @@ export function createGitTicketsChannel(opts: {
     return { ok: true, imported: true };
   };
 
-  const ensureCheckedOut = async (): Promise<
+  const ensureCheckedOut = async (input: {
+    readonly allowFetchFailureFallback: boolean;
+  }): Promise<
     | {
         readonly ok: true;
         readonly remoteUrl: string | null;
@@ -622,7 +651,10 @@ export function createGitTicketsChannel(opts: {
       return { ok: true, remoteUrl, pushRef };
     }
 
-    const checkedOut = await checkoutHead({ remoteUrl });
+    const checkedOut = await checkoutHead({
+      remoteUrl,
+      allowFetchFailureFallback: input.allowFetchFailureFallback,
+    });
     if (!checkedOut.ok) {
       return checkedOut;
     }
@@ -767,7 +799,10 @@ export function createGitTicketsChannel(opts: {
       message: `git push failed, retrying after fetch: ${pushError.message}`,
     });
 
-    const checkedOut = await checkoutHead({ remoteUrl: input.remoteUrl });
+    const checkedOut = await checkoutHead({
+      remoteUrl: input.remoteUrl,
+      allowFetchFailureFallback: false,
+    });
     if (!checkedOut.ok) {
       return checkedOut;
     }
@@ -891,7 +926,9 @@ export function createGitTicketsChannel(opts: {
   };
 
   const inspect = async (): Promise<TicketsGitInspectResult> => {
-    const checkedOut = await ensureCheckedOut();
+    const checkedOut = await ensureCheckedOut({
+      allowFetchFailureFallback: true,
+    });
     if (!checkedOut.ok) {
       return checkedOut;
     }
@@ -940,7 +977,9 @@ export function createGitTicketsChannel(opts: {
   const repair = async (input: {
     readonly pruneLegacyRef: boolean;
   }): Promise<TicketsGitRepairResult> => {
-    const checkedOut = await ensureCheckedOut();
+    const checkedOut = await ensureCheckedOut({
+      allowFetchFailureFallback: false,
+    });
     if (!checkedOut.ok) {
       return checkedOut;
     }
@@ -1006,7 +1045,9 @@ export function createGitTicketsChannel(opts: {
   }): Promise<
     { readonly ok: true } | { readonly ok: false; readonly error: string }
   > => {
-    const checkedOut = await ensureCheckedOut();
+    const checkedOut = await ensureCheckedOut({
+      allowFetchFailureFallback: false,
+    });
     if (!checkedOut.ok) {
       return checkedOut;
     }
@@ -1043,7 +1084,9 @@ export function createGitTicketsChannel(opts: {
       }
     | { readonly ok: false; readonly error: string }
   > => {
-    const checkedOut = await ensureCheckedOut();
+    const checkedOut = await ensureCheckedOut({
+      allowFetchFailureFallback: false,
+    });
     if (!checkedOut.ok) {
       return checkedOut;
     }
@@ -1077,7 +1120,9 @@ export function createGitTicketsChannel(opts: {
 
   return {
     ensureCheckedOut: async () => {
-      const checkedOut = await ensureCheckedOut();
+      const checkedOut = await ensureCheckedOut({
+        allowFetchFailureFallback: true,
+      });
       if (!checkedOut.ok) {
         throw new Error(checkedOut.error);
       }
@@ -1537,9 +1582,55 @@ function isGitIndexLockError(message: string): boolean {
 
 export const __testOnly = {
   mergeTicketEventLogs,
+  resolveLegacyImportFetchResult,
+  resolveLocalCheckoutFallback,
   resolvePushRefForCheckoutRef,
 };
 
+function resolveLegacyImportFetchResult(input: {
+  readonly missing: boolean;
+  readonly error: string;
+}):
+  | { readonly ok: true; readonly imported: false }
+  | { readonly ok: false; readonly error: string } {
+  if (input.missing) {
+    return { ok: true, imported: false };
+  }
+  return {
+    ok: false,
+    error: `git fetch failed: ${input.error}`,
+  };
+}
+
+function resolveLocalCheckoutFallback(input: {
+  readonly fetchFailure: string | null;
+  readonly allowFetchFailureFallback: boolean;
+  readonly preferredTrackingRef: string | null;
+  readonly remoteRef: string;
+  readonly legacyTrackingRef?: string | null;
+  readonly legacyRemoteRef?: string | null;
+}):
+  | { readonly ok: true; readonly pushRef: string }
+  | { readonly ok: false; readonly error: string } {
+  if (input.fetchFailure && !input.allowFetchFailureFallback) {
+    return { ok: false, error: input.fetchFailure };
+  }
+
+  if (!input.preferredTrackingRef) {
+    return { ok: true, pushRef: input.remoteRef };
+  }
+
+  return {
+    ok: true,
+    pushRef: resolvePushRefForCheckoutRef({
+      checkoutRef: input.preferredTrackingRef,
+      remoteRef: input.remoteRef,
+      legacyTrackingRef: input.legacyTrackingRef,
+      legacyRemoteRef: input.legacyRemoteRef,
+    }),
+  };
+}
+
 function resolvePushRefForCheckoutRef(input: {
   readonly checkoutRef: string;
   readonly remoteRef: string;
diff --git a/tests/tickets-git-channel.test.ts b/tests/tickets-git-channel.test.ts
index c93f8419f..66957f318 100644
--- a/tests/tickets-git-channel.test.ts
+++ b/tests/tickets-git-channel.test.ts
@@ -73,3 +73,59 @@ test("resolvePushRefForCheckoutRef keeps hidden ref when checkout came from hidd
 
   expect(pushRef).toBe("refs/hack/tickets");
 });
+
+test("resolveLocalCheckoutFallback blocks stale local fallback when fetch failure must be surfaced", () => {
+  const result = __testOnly.resolveLocalCheckoutFallback({
+    fetchFailure: "git fetch failed: origin unavailable",
+    allowFetchFailureFallback: false,
+    preferredTrackingRef: "refs/remotes/origin/__legacy__/hack/tickets",
+    remoteRef: "refs/hack/tickets",
+    legacyTrackingRef: "refs/remotes/origin/__legacy__/hack/tickets",
+    legacyRemoteRef: "refs/heads/hack/tickets",
+  });
+
+  expect(result).toEqual({
+    ok: false,
+    error: "git fetch failed: origin unavailable",
+  });
+});
+
+test("resolveLocalCheckoutFallback preserves the legacy push ref when local fallback is allowed", () => {
+  const result = __testOnly.resolveLocalCheckoutFallback({
+    fetchFailure: "git fetch failed: origin unavailable",
+    allowFetchFailureFallback: true,
+    preferredTrackingRef: "refs/remotes/origin/__legacy__/hack/tickets",
+    remoteRef: "refs/hack/tickets",
+    legacyTrackingRef: "refs/remotes/origin/__legacy__/hack/tickets",
+    legacyRemoteRef: "refs/heads/hack/tickets",
+  });
+
+  expect(result).toEqual({
+    ok: true,
+    pushRef: "refs/heads/hack/tickets",
+  });
+});
+
+test("resolveLegacyImportFetchResult surfaces non-missing legacy fetch failures", () => {
+  const result = __testOnly.resolveLegacyImportFetchResult({
+    missing: false,
+    error: "fatal: remote transport failed",
+  });
+
+  expect(result).toEqual({
+    ok: false,
+    error: "git fetch failed: fatal: remote transport failed",
+  });
+});
+
+test("resolveLegacyImportFetchResult ignores missing legacy refs", () => {
+  const result = __testOnly.resolveLegacyImportFetchResult({
+    missing: true,
+    error: "fatal: couldn't find remote ref refs/heads/hack/tickets",
+  });
+
+  expect(result).toEqual({
+    ok: true,
+    imported: false,
+  });
+});

From 421c4ea2a4a5f51768c17a47d16334eee70fc685 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:59:18 +0000
Subject: [PATCH 095/134] docs(session): align gateway workspace wording

---
 docs/gateway-api.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/gateway-api.md b/docs/gateway-api.md
index 0e626e9d6..fc3b52e33 100644
--- a/docs/gateway-api.md
+++ b/docs/gateway-api.md
@@ -204,8 +204,8 @@ Base URL: `http://127.0.0.1:7788` (or your tunnel URL)
 | GET | `/v1/metrics` | no | Cache + stream metrics |
 | GET | `/v1/projects` | no | Gateway-enabled projects + runtime snapshot |
 | GET | `/v1/ps` | no | Compose project container list |
-| GET | `/v1/sessions` | no | List persistent tmux-backed workspaces |
-| POST | `/v1/sessions` | yes | Create persistent tmux-backed workspace |
+| GET | `/v1/sessions` | no | List persistent mux-backed workspaces |
+| POST | `/v1/sessions` | yes | Create persistent mux-backed workspace |
 | GET | `/v1/sessions/:id` | no | Get workspace details |
 | POST | `/v1/sessions/:id/stop` | yes | Stop (kill) workspace |
 | POST | `/v1/sessions/:id/exec` | yes | Execute command in workspace |

From 16c19308efb373a078ca3a116d0f5b953383a35e Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 22:00:08 +0000
Subject: [PATCH 096/134] fix: close prerequisite matrix coverage gaps

---
 docs/guides/prerequisite-detection-matrix.md |  7 +++
 src/cli/prerequisites.ts                     | 38 ++++++++++++++-
 tests/prerequisites-matrix.test.ts           | 50 ++++++++++++++++++++
 3 files changed, 94 insertions(+), 1 deletion(-)

diff --git a/docs/guides/prerequisite-detection-matrix.md b/docs/guides/prerequisite-detection-matrix.md
index 7182363bf..b768fcc78 100644
--- a/docs/guides/prerequisite-detection-matrix.md
+++ b/docs/guides/prerequisite-detection-matrix.md
@@ -46,10 +46,13 @@ The goal is not to make every command fail earlier. The goal is to decide, in a
 | `hack global down` | `docker_cli`, `docker_daemon` | guide, guide | Conditional: only when a managed global stack already exists; otherwise teardown should stay idempotent |
 | `hack global ca`, `hack global trust` | `global_bootstrap`, `docker_cli`, `docker_daemon`, `global_services` | guide, guide, guide, guide | CA export/trust depends on an installed and running Caddy-managed global stack |
 | `hack up`, `hack down`, `hack restart`, `hack ps`, `hack run`, `hack tui` | `docker_cli`, `docker_daemon` | guide, guide | Core Docker-backed runtime commands |
+| `hack projects prune` | `docker_cli`, `docker_daemon` | guide, guide | Operational cleanup should repair Docker availability before mutating runtime state |
+| `hack status`, `hack projects` | `docker_cli`, `docker_daemon` | warn, warn | Inventory/diagnostic commands should preserve degraded runtime visibility instead of intercepting |
 | `hack up`, `hack restart` | `mux_backend` | guide | Only when lifecycle host processes or mux-backed pre-start hooks are configured |
 | `hack open` | `global_services` | guide | Routed `*.hack` access should repair global routing instead of failing opaquely |
 | `hack logs` | `docker_cli`, `docker_daemon`, `global_services` | guide, guide, warn | Default logs may fall back from Loki to compose logs |
 | `hack logs --loki`, `hack logs --query` | `global_services` | guide | Explicit Loki mode should not silently fall back |
+| `hack logs --compose` | `docker_cli`, `docker_daemon` | guide, guide | Explicit compose logs bypass Loki entirely, so only Docker availability matters |
 | `hack session`, `hack session list`, `hack session start`, `hack session attach`, `hack session exec`, `hack session stop`, `hack ssh` | `tmux_binary` | guide | The current session and session-aware SSH implementation is tmux-backed even when mux config exists elsewhere |
 | `hack session panes`, `hack session capture`, `hack session tail`, `hack setup tmux` | `tmux_binary` | guide | tmux-only surfaces |
 | `hack x github status`, `hack x github profiles` | `github_profile`, `github_token` | warn, warn | Diagnostics should expose missing state instead of intercepting it |
@@ -110,10 +113,14 @@ restart
 ps
 run
 tui
+projects prune
+status
+projects
 open
 logs
 logs --loki
 logs --query
+logs --compose
 session
 session list
 session start
diff --git a/src/cli/prerequisites.ts b/src/cli/prerequisites.ts
index ad34e1c8f..75ada5de4 100644
--- a/src/cli/prerequisites.ts
+++ b/src/cli/prerequisites.ts
@@ -291,7 +291,7 @@ export const COMMAND_PREREQUISITE_CONTRACTS = [
   },
   {
     name: "Project runtime lifecycle",
-    commands: ["up", "down", "restart", "ps", "run", "tui"],
+    commands: ["up", "down", "restart", "ps", "run", "tui", "projects prune"],
     rules: [
       {
         checkId: "docker_cli",
@@ -307,6 +307,24 @@ export const COMMAND_PREREQUISITE_CONTRACTS = [
       },
     ],
   },
+  {
+    name: "Project inventory diagnostics",
+    commands: ["status", "projects"],
+    rules: [
+      {
+        checkId: "docker_cli",
+        onMissing: "warn",
+        reason:
+          "Project inventory commands can still show registered state even when Docker is unavailable, so they should surface degraded runtime status instead of redirecting.",
+      },
+      {
+        checkId: "docker_daemon",
+        onMissing: "warn",
+        reason:
+          "These commands already report runtime unavailability inline and should preserve that diagnostic behavior.",
+      },
+    ],
+  },
   {
     name: "Project lifecycle host processes",
     commands: ["up", "restart"],
@@ -369,6 +387,24 @@ export const COMMAND_PREREQUISITE_CONTRACTS = [
       },
     ],
   },
+  {
+    name: "Project logs with compose-only backend",
+    commands: ["logs --compose"],
+    rules: [
+      {
+        checkId: "docker_cli",
+        onMissing: "guide",
+        reason:
+          "An explicit compose log request bypasses Loki entirely and still depends on Docker-backed logs.",
+      },
+      {
+        checkId: "docker_daemon",
+        onMissing: "guide",
+        reason:
+          "Without a reachable daemon there is no compose log backend available for an explicit `--compose` request.",
+      },
+    ],
+  },
   {
     name: "Session commands",
     commands: [
diff --git a/tests/prerequisites-matrix.test.ts b/tests/prerequisites-matrix.test.ts
index 0c94525fa..c3b32c7a0 100644
--- a/tests/prerequisites-matrix.test.ts
+++ b/tests/prerequisites-matrix.test.ts
@@ -37,10 +37,14 @@ test("command coverage includes the major first-run and integration paths", () =
     "ps",
     "run",
     "tui",
+    "projects prune",
+    "status",
+    "projects",
     "open",
     "logs",
     "logs --loki",
     "logs --query",
+    "logs --compose",
     "session",
     "session list",
     "session start",
@@ -109,6 +113,26 @@ test("status-style auth commands warn instead of intercepting missing auth", ()
   );
 });
 
+test("runtime inventory diagnostics warn instead of intercepting Docker availability", () => {
+  const [status] = getCommandPrerequisiteContracts({
+    command: "status",
+  });
+  const [projects] = getCommandPrerequisiteContracts({
+    command: "projects",
+  });
+
+  expect(status?.rules.every((rule) => rule.onMissing === "warn")).toBe(true);
+  expect(projects?.rules.every((rule) => rule.onMissing === "warn")).toBe(true);
+  expect(status?.rules.map((rule) => rule.checkId)).toEqual([
+    "docker_cli",
+    "docker_daemon",
+  ]);
+  expect(projects?.rules.map((rule) => rule.checkId)).toEqual([
+    "docker_cli",
+    "docker_daemon",
+  ]);
+});
+
 test("x linear aliases resolve to the shared Linear prerequisite contracts", () => {
   const [linearStatus] = getCommandPrerequisiteContracts({
     command: "linear status",
@@ -145,6 +169,32 @@ test("action commands escalate to guidance for missing integration auth", () =>
   ]);
 });
 
+test("compose-only operational commands guide Docker availability", () => {
+  const [projectsPrune] = getCommandPrerequisiteContracts({
+    command: "projects prune",
+  });
+  const [logsCompose] = getCommandPrerequisiteContracts({
+    command: "logs --compose",
+  });
+
+  expect(projectsPrune?.rules.map((rule) => rule.checkId)).toEqual([
+    "docker_cli",
+    "docker_daemon",
+  ]);
+  expect(projectsPrune?.rules.map((rule) => rule.onMissing)).toEqual([
+    "guide",
+    "guide",
+  ]);
+  expect(logsCompose?.rules.map((rule) => rule.checkId)).toEqual([
+    "docker_cli",
+    "docker_daemon",
+  ]);
+  expect(logsCompose?.rules.map((rule) => rule.onMissing)).toEqual([
+    "guide",
+    "guide",
+  ]);
+});
+
 test("session commands require tmux instead of only resolving a mux backend", () => {
   const [sessionStart] = getCommandPrerequisiteContracts({
     command: "session start",

From 3477a23b323263e5a079c3f47cd78c236c0571aa Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 22:00:53 +0000
Subject: [PATCH 097/134] test: widen env backend integration timeouts

---
 tests/env-backend-command.test.ts | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/tests/env-backend-command.test.ts b/tests/env-backend-command.test.ts
index f76644393..c71829700 100644
--- a/tests/env-backend-command.test.ts
+++ b/tests/env-backend-command.test.ts
@@ -9,6 +9,8 @@ type RunResult = {
   readonly stderr: string;
 };
 
+const ENV_BACKEND_COMMAND_TIMEOUT_MS = 60_000;
+
 let tempDir: string | null = null;
 let tempGlobalConfigPath: string | null = null;
 let previousGlobalConfigPath: string | undefined;
@@ -42,7 +44,7 @@ afterEach(async () => {
 
 test(
   "env backend status defaults to keychain",
-  { timeout: 10_000 },
+  { timeout: ENV_BACKEND_COMMAND_TIMEOUT_MS },
   async () => {
     const result = await runHack({
       args: ["env", "backend", "status", "--json"],
@@ -63,7 +65,7 @@ test(
 
 test(
   "env backend use encrypted_file persists selection",
-  { timeout: 10_000 },
+  { timeout: ENV_BACKEND_COMMAND_TIMEOUT_MS },
   async () => {
     const result = await runHack({
       args: [
@@ -96,7 +98,7 @@ test(
 
 test(
   "env backend use encrypted_file can provision a stable key file",
-  { timeout: 10_000 },
+  { timeout: ENV_BACKEND_COMMAND_TIMEOUT_MS },
   async () => {
     if (!(tempDir && tempGlobalConfigPath)) {
       throw new Error("Missing temp global config state");
@@ -144,7 +146,7 @@ test(
 
 test(
   "env backend use cloud requires provider and stores cloud settings",
-  { timeout: 10_000 },
+  { timeout: ENV_BACKEND_COMMAND_TIMEOUT_MS },
   async () => {
     const invalid = await runHack({
       args: ["env", "backend", "use", "cloud"],
@@ -195,7 +197,7 @@ test(
 
 test(
   "env set --secret stores value using encrypted backend",
-  { timeout: 20_000 },
+  { timeout: ENV_BACKEND_COMMAND_TIMEOUT_MS },
   async () => {
     if (!tempDir) {
       throw new Error("Missing temp dir");
@@ -283,7 +285,7 @@ test(
 
 test(
   "env list --json explains storage and trust boundaries",
-  { timeout: 20_000 },
+  { timeout: ENV_BACKEND_COMMAND_TIMEOUT_MS },
   async () => {
     if (!tempDir) {
       throw new Error("Missing temp dir");
@@ -414,7 +416,7 @@ test(
 
 test(
   "env list --json marks cloud backend as a local shim",
-  { timeout: 20_000 },
+  { timeout: ENV_BACKEND_COMMAND_TIMEOUT_MS },
   async () => {
     if (!tempDir) {
       throw new Error("Missing temp dir");
@@ -508,7 +510,7 @@ test(
 
 test(
   "env list shows storage summary even when no contract exists",
-  { timeout: 60_000 },
+  { timeout: ENV_BACKEND_COMMAND_TIMEOUT_MS },
   async () => {
     if (!tempDir) {
       throw new Error("Missing temp dir");

From eef134365d8d51bfccfc3402a761d31bdc4d3c43 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 22:00:58 +0000
Subject: [PATCH 098/134] test(tickets): harden normalized model invariants

---
 docs/guides/tickets-normalization.md          |   5 +
 .../extensions/tickets/normalized-model.ts    |  14 +++
 tests/tickets-normalized-model.test.ts        | 117 ++++++++++++++++++
 3 files changed, 136 insertions(+)

diff --git a/docs/guides/tickets-normalization.md b/docs/guides/tickets-normalization.md
index b15ff83f3..edd5680fe 100644
--- a/docs/guides/tickets-normalization.md
+++ b/docs/guides/tickets-normalization.md
@@ -134,11 +134,16 @@ The schema is intentionally stricter than a plain JSON shape. A valid normalized
 satisfy these cross-record rules:
 
 - `provenance.links[*].linkId` values are unique within a ticket.
+- `provenance.links[*].linkId` must equal `${system}:${remote.id}` so persisted records keep a stable
+  provider-derived identity.
 - Local-origin tickets cannot carry an `origin`-role external link.
 - External-origin tickets must point at a matching `origin`-role link with the same `system` and
   `linkId`.
 - Any authority winner with `{ kind: "link", linkId }` must reference a link that exists on the
   same ticket.
+- `canonical.tags`, `canonical.relationships.dependsOn`, `canonical.relationships.blocks`, and
+  `provenance.links[*].remote.containers` are deduplicated sets in persisted state, not just
+  normalized on write.
 - `buildNormalizedTicketLink()` validates remote identifiers and URLs up front, so adapter code
   cannot emit blank link records accidentally.
 - Legacy summaries with `source` set to an external provider must include matching
diff --git a/src/control-plane/extensions/tickets/normalized-model.ts b/src/control-plane/extensions/tickets/normalized-model.ts
index 8e447f92c..cb1fe9315 100644
--- a/src/control-plane/extensions/tickets/normalized-model.ts
+++ b/src/control-plane/extensions/tickets/normalized-model.ts
@@ -715,6 +715,10 @@ const parseNormalizedTicketLink = (input: unknown): NormalizedTicketLink => {
 
   const remoteRecord = asRecord(record.remote, "normalized ticket remote");
   assertNonEmptyString(remoteRecord.id, "normalized ticket remote id");
+  assertValue(
+    record.linkId === `${record.system}:${remoteRecord.id}`,
+    "normalized ticket linkId must match system and remote id"
+  );
   if (remoteRecord.key !== undefined) {
     assertNonEmptyString(remoteRecord.key, "normalized ticket remote key");
   }
@@ -725,6 +729,7 @@ const parseNormalizedTicketLink = (input: unknown): NormalizedTicketLink => {
     Array.isArray(remoteRecord.containers),
     "normalized ticket remote containers must be an array"
   );
+  const containerKeys = new Set<string>();
   for (const container of remoteRecord.containers) {
     const containerRecord = asRecord(container, "normalized ticket container");
     assertValue(
@@ -740,6 +745,12 @@ const parseNormalizedTicketLink = (input: unknown): NormalizedTicketLink => {
         "normalized ticket container name"
       );
     }
+    const containerKey = `${containerRecord.kind}:${containerRecord.id}`;
+    assertValue(
+      !containerKeys.has(containerKey),
+      "normalized ticket remote containers must not contain duplicates"
+    );
+    containerKeys.add(containerKey);
   }
 
   if (record.adapterMetadata !== undefined) {
@@ -824,8 +835,11 @@ const assertTicketSchemaValue = (input: unknown, label: string): void => {
 
 const assertStringList = (input: unknown, label: string): void => {
   assertValue(Array.isArray(input), `${label} must be an array`);
+  const seen = new Set<string>();
   for (const [index, value] of input.entries()) {
     assertNonEmptyString(value, `${label}[${index}]`);
+    assertValue(!seen.has(value), `${label} must not contain duplicates`);
+    seen.add(value);
   }
 };
 
diff --git a/tests/tickets-normalized-model.test.ts b/tests/tickets-normalized-model.test.ts
index a9fec0f98..272e4918d 100644
--- a/tests/tickets-normalized-model.test.ts
+++ b/tests/tickets-normalized-model.test.ts
@@ -442,3 +442,120 @@ test("rejects blank remote identifiers when building normalized links", () => {
     })
   ).toThrow("normalized ticket remote id must be a non-empty string");
 });
+
+test("rejects local-origin tickets that still carry an origin link", () => {
+  const normalized = createMinimalNormalizedTicket();
+
+  expect(() =>
+    normalizedTicketEntitySchema.parse({
+      ...normalized,
+      provenance: {
+        ...normalized.provenance,
+        links: [
+          buildNormalizedTicketLink({
+            system: "github",
+            remoteId: "issue_51",
+            role: "origin",
+          }),
+        ],
+      },
+    })
+  ).toThrow("normalized ticket local origin cannot include origin links");
+});
+
+test("rejects parsed links whose linkId does not match the remote system identity", () => {
+  expect(() =>
+    normalizedTicketEntitySchema.parse({
+      ...createMinimalNormalizedTicket(),
+      provenance: {
+        origin: {
+          kind: "external",
+          system: "linear",
+          linkId: "linear:lin_52",
+        },
+        links: [
+          {
+            ...buildNormalizedTicketLink({
+              system: "linear",
+              remoteId: "lin_52",
+              role: "origin",
+            }),
+            linkId: "linear:lin_other",
+          },
+        ],
+        authority: {
+          defaultRule: {
+            policy: "replace",
+            winner: { kind: "origin" },
+          },
+          fieldRules: {},
+        },
+      },
+    })
+  ).toThrow("normalized ticket linkId must match system and remote id");
+});
+
+test("rejects duplicate canonical list values in parsed entities", () => {
+  expect(() =>
+    normalizedTicketEntitySchema.parse({
+      ...createMinimalNormalizedTicket(),
+      canonical: {
+        ...createMinimalNormalizedTicket().canonical,
+        tags: ["sync", "sync"],
+      },
+    })
+  ).toThrow("normalized ticket canonical tags must not contain duplicates");
+});
+
+test("rejects duplicate remote containers in parsed links", () => {
+  expect(() =>
+    normalizedTicketEntitySchema.parse({
+      ...createMinimalNormalizedTicket(),
+      provenance: {
+        origin: {
+          kind: "external",
+          system: "asana",
+          linkId: "asana:task_53",
+        },
+        links: [
+          {
+            ...buildNormalizedTicketLink({
+              system: "asana",
+              remoteId: "task_53",
+              role: "origin",
+              containers: [
+                {
+                  kind: "project",
+                  id: "proj_1",
+                  name: "Tickets",
+                },
+              ],
+            }),
+            remote: {
+              id: "task_53",
+              containers: [
+                {
+                  kind: "project",
+                  id: "proj_1",
+                  name: "Tickets",
+                },
+                {
+                  kind: "project",
+                  id: "proj_1",
+                  name: "Tickets",
+                },
+              ],
+            },
+          },
+        ],
+        authority: {
+          defaultRule: {
+            policy: "replace",
+            winner: { kind: "origin" },
+          },
+          fieldRules: {},
+        },
+      },
+    })
+  ).toThrow("normalized ticket remote containers must not contain duplicates");
+});

From bdced945fbbddc0b657392bdfae88b9e1a6d2cd6 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 22:01:01 +0000
Subject: [PATCH 099/134] fix(tickets): finalize normalization conflict
 semantics

---
 .../extensions/linear/commands.ts             |  43 +-
 .../extensions/tickets/domain.ts              |  50 ++-
 .../extensions/tickets/provenance.ts          |  16 +-
 tests/linear-commands.test.ts                 | 405 +++++++++++++++++-
 tests/tickets-store.test.ts                   |  86 ++++
 5 files changed, 555 insertions(+), 45 deletions(-)

diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index 0df57957f..60ab39b41 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -13,6 +13,7 @@ import { openUrl } from "../../../lib/os.ts";
 import { display } from "../../../ui/display.ts";
 import {
   findTicketRemoteLink,
+  normalizeTicketFieldName,
   projectRemoteLinkToCompatibilityFields,
 } from "../tickets/provenance.ts";
 import {
@@ -2984,7 +2985,7 @@ function detectAuthoritativeFieldConflicts(input: {
   });
   if (localBody !== remoteBody) {
     conflicts.push({
-      field: "body",
+      field: normalizeTicketFieldName("body"),
       authority: input.authority,
       summary: `Authoritative ${authorityLabel} body diverged from the other side.`,
       localValue: localBody,
@@ -3188,7 +3189,7 @@ function buildConflictDedupKey(input: {
   readonly remoteValue?: TicketMetadataValue;
 }): string {
   return [
-    input.field,
+    normalizeTicketFieldName(input.field),
     JSON.stringify(input.localValue ?? null),
     JSON.stringify(input.remoteValue ?? null),
   ].join("|");
@@ -3227,7 +3228,7 @@ function buildLinearConflictIdempotencyKey(input: {
   const fingerprint = createHash("sha256")
     .update(
       JSON.stringify({
-        field: input.conflict.field,
+        field: normalizeTicketFieldName(input.conflict.field),
         authority: input.conflict.authority ?? null,
         summary: input.conflict.summary ?? null,
         localValue: input.conflict.localValue ?? null,
@@ -3812,25 +3813,25 @@ async function syncTicketToLinearIssue(input: {
     return { ok: false, error: recordedConflicts.error };
   }
 
-  const effectiveFields =
-    authority === "linear" && existingIssue.issue
-      ? {
-          ...fields.value,
-          title: existingIssue.issue.title,
-          description: existingIssue.issue.description ?? "",
-          ...(existingIssue.issue.assigneeId
-            ? { assigneeId: existingIssue.issue.assigneeId }
-            : {}),
-          ...(input.syncToggles.statuses
-            ? { stateId: existingIssue.issue.state.id }
-            : {}),
-        }
-      : fields.value;
+  const preserveRemoteIssueFields = authority !== "hack" && existingIssue.issue;
+
+  const effectiveFields = preserveRemoteIssueFields
+    ? {
+        ...fields.value,
+        title: existingIssue.issue.title,
+        description: existingIssue.issue.description ?? "",
+        ...(existingIssue.issue.assigneeId
+          ? { assigneeId: existingIssue.issue.assigneeId }
+          : {}),
+        ...(input.syncToggles.statuses
+          ? { stateId: existingIssue.issue.state.id }
+          : {}),
+      }
+    : fields.value;
 
-  const effectiveProjectId =
-    authority === "linear" && existingIssue.issue
-      ? existingIssue.issue.projectId
-      : target.value.projectId;
+  const effectiveProjectId = preserveRemoteIssueFields
+    ? existingIssue.issue.projectId
+    : target.value.projectId;
 
   const syncedIssue = await upsertLinearIssueForTicketSync({
     runtime: input.runtime,
diff --git a/src/control-plane/extensions/tickets/domain.ts b/src/control-plane/extensions/tickets/domain.ts
index b2af16d47..0c60ad7d1 100644
--- a/src/control-plane/extensions/tickets/domain.ts
+++ b/src/control-plane/extensions/tickets/domain.ts
@@ -1,6 +1,10 @@
-import { buildLegacyDescriptionDocument } from "./documents.ts";
+import {
+  buildLegacyDescriptionDocument,
+  getActiveTicketDescription,
+} from "./documents.ts";
 import {
   buildTicketProvenance,
+  normalizeTicketFieldName,
   projectRemoteLinkToCompatibilityFields,
 } from "./provenance.ts";
 
@@ -200,9 +204,9 @@ export function createNormalizedTicket(input: {
 export function projectNormalizedTicketSummary(input: {
   readonly ticket: NormalizedTicket;
 }): TicketSummaryCompatibility {
-  const description = input.ticket.documents.find(
-    (document) => document.role === "description"
-  );
+  const description = getActiveTicketDescription({
+    documents: input.ticket.documents,
+  });
   const primaryRemote = input.ticket.provenance.remotes[0];
 
   return {
@@ -257,17 +261,31 @@ function buildFieldStates(input: {
   readonly fieldAuthorities: readonly TicketFieldAuthorityEntry[];
   readonly conflicts: readonly TicketSyncConflictCompatibility[];
 }): TicketFieldState[] {
-  return input.fieldAuthorities
-    .filter((fieldAuthority) =>
-      ["title", "status", "assignee", "description"].includes(
-        fieldAuthority.field
-      )
-    )
-    .map((fieldAuthority) => ({
-      field: fieldAuthority.field,
+  const trackedFields = new Map<string, TicketFieldState>();
+
+  for (const fieldAuthority of input.fieldAuthorities) {
+    const field = normalizeTicketFieldName(fieldAuthority.field);
+    if (!["title", "status", "assignee", "description"].includes(field)) {
+      continue;
+    }
+    trackedFields.set(field, {
+      field,
       authority: fieldAuthority.authority,
-      conflictIds: input.conflicts
-        .filter((conflict) => conflict.field === fieldAuthority.field)
-        .map((conflict) => conflict.conflictId),
-    }));
+      conflictIds: [],
+    });
+  }
+
+  for (const conflict of input.conflicts) {
+    const field = normalizeTicketFieldName(conflict.field);
+    const current = trackedFields.get(field);
+    if (!current) {
+      continue;
+    }
+    trackedFields.set(field, {
+      ...current,
+      conflictIds: [...current.conflictIds, conflict.conflictId],
+    });
+  }
+
+  return [...trackedFields.values()];
 }
diff --git a/src/control-plane/extensions/tickets/provenance.ts b/src/control-plane/extensions/tickets/provenance.ts
index 2407ab100..f6cb855b3 100644
--- a/src/control-plane/extensions/tickets/provenance.ts
+++ b/src/control-plane/extensions/tickets/provenance.ts
@@ -93,6 +93,10 @@ export type TicketFieldVersion = {
   readonly value?: TicketMetadataValue;
 };
 
+export function normalizeTicketFieldName(field: string): string {
+  return field === "body" ? "description" : field;
+}
+
 export function inferTicketSourceSystem(input: {
   readonly ticket: Pick<
     TicketProvenanceCompatibility,
@@ -300,9 +304,10 @@ export function buildTicketFieldAuthorities(input: {
   });
 
   for (const conflict of input.conflicts ?? []) {
-    const current = byField.get(conflict.field);
-    byField.set(conflict.field, {
-      field: conflict.field,
+    const field = normalizeTicketFieldName(conflict.field);
+    const current = byField.get(field);
+    byField.set(field, {
+      field,
       authority: conflict.authority ?? current?.authority ?? defaultAuthority,
     });
   }
@@ -345,9 +350,10 @@ export function buildTicketFieldVersions(input: {
   }
 
   for (const conflict of input.conflicts ?? []) {
+    const field = normalizeTicketFieldName(conflict.field);
     if (conflict.localValue !== undefined) {
       versions.push({
-        field: conflict.field,
+        field,
         source: "local",
         recordedAt: conflict.updatedAt,
         value: conflict.localValue,
@@ -355,7 +361,7 @@ export function buildTicketFieldVersions(input: {
     }
     if (conflict.remoteValue !== undefined) {
       versions.push({
-        field: conflict.field,
+        field,
         source: "remote",
         provider: conflict.provider,
         recordedAt: conflict.updatedAt,
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index a2155b3b5..a13e6c9db 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -795,7 +795,7 @@ test("detectAuthoritativeFieldConflicts reports divergence for hack-owned ticket
 
   expect(conflicts.map((conflict) => conflict.field)).toEqual([
     "title",
-    "body",
+    "description",
     "status",
     "project",
   ]);
@@ -1090,7 +1090,7 @@ test("syncIssueFromLinearToTicket preserves hack authority, appends comments, an
   expect(result.commentsPulled).toBe(1);
   expect(result.conflictsRecorded).toBe(4);
   expect(appendedBodies).toEqual(["Fresh remote note"]);
-  expect(conflicts).toEqual(["title", "body", "status", "project"]);
+  expect(conflicts).toEqual(["title", "description", "status", "project"]);
   expect(checkpoints).toEqual(["linear_to_hack"]);
   expect(updatedTickets).toHaveLength(1);
   expect(updatedTickets[0]?.title).toBeUndefined();
@@ -1245,7 +1245,10 @@ test("syncIssueFromLinearToTicket records review-required conflicts for dual-hom
   expect(result.conflictsRecorded).toBe(4);
   expect(recordedConflicts).toEqual([
     expect.objectContaining({ field: "title", authority: "review_required" }),
-    expect.objectContaining({ field: "body", authority: "review_required" }),
+    expect.objectContaining({
+      field: "description",
+      authority: "review_required",
+    }),
     expect.objectContaining({ field: "status", authority: "review_required" }),
     expect.objectContaining({ field: "project", authority: "review_required" }),
   ]);
@@ -1615,6 +1618,402 @@ test("syncTicketToLinearIssue reuses a linked Linear issue inferred from provena
   expect(updatedIssues).toHaveLength(1);
 });
 
+test("syncTicketToLinearIssue preserves remote issue fields for review-required authority", async () => {
+  const recordedConflicts: Array<{
+    readonly field: string;
+    readonly authority?: string;
+  }> = [];
+  const updatedIssues: Record<string, unknown>[] = [];
+
+  const runtime = {
+    profileId: "default",
+    apiUrl: "https://api.linear.app/graphql",
+    projectBinding: {
+      teamId: "team-1",
+      additionalProjects: [],
+    },
+    assigneeMappings: [],
+    tickets: {
+      getTicket: async () => ({
+        ticketId: "T-00005",
+        title: "Local title",
+        body: "Local body",
+        status: "open" as const,
+        createdAt: "2026-03-05T10:00:00.000Z",
+        updatedAt: "2026-03-05T10:00:00.000Z",
+        dependsOn: [],
+        blocks: [],
+        owner: "hack",
+        source: "linear",
+        assignee: "alice@example.com",
+        tags: [],
+        externalSystem: "linear",
+        externalId: "issue-5",
+        externalKey: "ENG-555",
+        externalProjectId: "proj-local",
+        externalTeamId: "team-1",
+      }),
+      updateTicket: async () => ({ ok: true as const }),
+      listTickets: async () => [],
+      getTicketDetail: async () => ({
+        ticket: null,
+        events: [],
+        comments: [],
+        reviewNotes: [],
+        syncCheckpoints: [],
+        conflicts: [],
+      }),
+      linkCommentExternalId: async () => ({ ok: true as const }),
+      recordSyncCheckpoint: async () => ({
+        ok: true as const,
+        checkpoint: {
+          checkpointId: "checkpoint-5",
+          ticketId: "T-00005",
+          provider: "linear",
+          direction: "hack_to_linear",
+          actor: "test",
+          createdAt: "2026-03-05T10:10:00.000Z",
+        },
+      }),
+      recordSyncConflict: async (input: {
+        readonly field: string;
+        readonly authority?: string;
+      }) => {
+        recordedConflicts.push(input);
+        return {
+          ok: true as const,
+          conflict: {
+            conflictId: `conflict-${input.field}`,
+            ticketId: "T-00005",
+            provider: "linear",
+            field: input.field,
+            status: "open" as const,
+            authority: input.authority,
+            createdAt: "2026-03-05T10:10:00.000Z",
+            updatedAt: "2026-03-05T10:10:00.000Z",
+          },
+        };
+      },
+    },
+    linear: {
+      getIssueById: async () => ({
+        ok: true as const,
+        data: {
+          id: "issue-5",
+          identifier: "ENG-555",
+          title: "Linear title",
+          description: "Linear body",
+          state: {
+            id: "state-2",
+            name: "Done",
+            type: "completed" as const,
+          },
+          url: "https://linear.app/hack/issue/ENG-555",
+          teamId: "team-1",
+          projectId: "proj-remote",
+          assigneeId: "user-1",
+          labels: [],
+        },
+      }),
+      getIssueByIdentifier: async () => ({ ok: true as const, data: null }),
+      updateIssue: async (input: Record<string, unknown>) => {
+        updatedIssues.push(input);
+        return {
+          ok: true as const,
+          data: {
+            id: "issue-5",
+            identifier: "ENG-555",
+            title: "Linear title",
+            description: "Linear body",
+            state: {
+              id: "state-2",
+              name: "Done",
+              type: "completed" as const,
+            },
+            url: "https://linear.app/hack/issue/ENG-555",
+            teamId: "team-1",
+            projectId: "proj-remote",
+            assigneeId: "user-1",
+            labels: [],
+          },
+        };
+      },
+      createIssue: async () => {
+        throw new Error("createIssue should not be called");
+      },
+      listTeamStates: async () => ({
+        ok: true as const,
+        data: [
+          {
+            id: "state-1",
+            name: "Todo",
+            type: "unstarted" as const,
+          },
+          {
+            id: "state-2",
+            name: "Done",
+            type: "completed" as const,
+          },
+        ],
+      }),
+      listTeamLabels: async () => ({
+        ok: true as const,
+        data: [],
+      }),
+      listIssueComments: async () => ({
+        ok: true as const,
+        data: [],
+      }),
+      createComment: async () => {
+        throw new Error("createComment should not be called");
+      },
+      listTeamUsers: async () => ({
+        ok: true as const,
+        data: [
+          {
+            id: "user-1",
+            email: "alice@example.com",
+            displayName: "Alice",
+          },
+        ],
+      }),
+      getProject: async () => ({ ok: true as const, data: null }),
+    },
+  };
+
+  const result = await __testOnly.syncTicketToLinearIssue({
+    runtime,
+    ticketId: "T-00005",
+    syncToggles: {
+      labels: false,
+      statuses: true,
+      dependencies: false,
+      projects: true,
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(recordedConflicts).toEqual([
+    expect.objectContaining({ field: "title", authority: "review_required" }),
+    expect.objectContaining({
+      field: "description",
+      authority: "review_required",
+    }),
+    expect.objectContaining({ field: "status", authority: "review_required" }),
+    expect.objectContaining({ field: "project", authority: "review_required" }),
+  ]);
+  expect(updatedIssues).toHaveLength(1);
+  expect(updatedIssues[0]).toEqual(
+    expect.objectContaining({
+      issueId: "issue-5",
+      title: "Linear title",
+      description: "Linear body",
+      stateId: "state-2",
+      projectId: "proj-remote",
+      assigneeId: "user-1",
+    })
+  );
+});
+
+test("syncTicketToLinearIssue does not duplicate legacy body conflicts after field normalization", async () => {
+  const recordedConflicts: Array<{
+    readonly field: string;
+    readonly authority?: string;
+  }> = [];
+
+  const runtime = {
+    profileId: "default",
+    apiUrl: "https://api.linear.app/graphql",
+    projectBinding: {
+      teamId: "team-1",
+      additionalProjects: [],
+    },
+    assigneeMappings: [],
+    tickets: {
+      getTicket: async () => ({
+        ticketId: "T-00006",
+        title: "Local title",
+        body: "Local body",
+        status: "open" as const,
+        createdAt: "2026-03-05T10:00:00.000Z",
+        updatedAt: "2026-03-05T10:00:00.000Z",
+        dependsOn: [],
+        blocks: [],
+        owner: "hack",
+        source: "linear",
+        assignee: "alice@example.com",
+        tags: [],
+        externalSystem: "linear",
+        externalId: "issue-6",
+        externalKey: "ENG-666",
+        externalProjectId: "proj-local",
+        externalTeamId: "team-1",
+      }),
+      updateTicket: async () => ({ ok: true as const }),
+      listTickets: async () => [],
+      getTicketDetail: async () => ({
+        ticket: null,
+        events: [],
+        comments: [],
+        reviewNotes: [],
+        syncCheckpoints: [],
+        conflicts: [
+          {
+            conflictId: "conflict-body",
+            ticketId: "T-00006",
+            provider: "linear" as const,
+            field: "body",
+            status: "open" as const,
+            authority: "review_required" as const,
+            localValue: "Local body",
+            remoteValue: "Linear body",
+            createdAt: "2026-03-05T10:05:00.000Z",
+            updatedAt: "2026-03-05T10:05:00.000Z",
+          },
+        ],
+      }),
+      linkCommentExternalId: async () => ({ ok: true as const }),
+      recordSyncCheckpoint: async () => ({
+        ok: true as const,
+        checkpoint: {
+          checkpointId: "checkpoint-6",
+          ticketId: "T-00006",
+          provider: "linear",
+          direction: "hack_to_linear",
+          actor: "test",
+          createdAt: "2026-03-05T10:10:00.000Z",
+        },
+      }),
+      recordSyncConflict: async (input: {
+        readonly field: string;
+        readonly authority?: string;
+      }) => {
+        recordedConflicts.push(input);
+        return {
+          ok: true as const,
+          conflict: {
+            conflictId: `conflict-${input.field}`,
+            ticketId: "T-00006",
+            provider: "linear",
+            field: input.field,
+            status: "open" as const,
+            authority: input.authority,
+            createdAt: "2026-03-05T10:10:00.000Z",
+            updatedAt: "2026-03-05T10:10:00.000Z",
+          },
+        };
+      },
+    },
+    linear: {
+      getIssueById: async () => ({
+        ok: true as const,
+        data: {
+          id: "issue-6",
+          identifier: "ENG-666",
+          title: "Linear title",
+          description: "Linear body",
+          state: {
+            id: "state-2",
+            name: "Done",
+            type: "completed" as const,
+          },
+          url: "https://linear.app/hack/issue/ENG-666",
+          teamId: "team-1",
+          projectId: "proj-remote",
+          assigneeId: "user-1",
+          labels: [],
+        },
+      }),
+      getIssueByIdentifier: async () => ({ ok: true as const, data: null }),
+      updateIssue: async () => ({
+        ok: true as const,
+        data: {
+          id: "issue-6",
+          identifier: "ENG-666",
+          title: "Linear title",
+          description: "Linear body",
+          state: {
+            id: "state-2",
+            name: "Done",
+            type: "completed" as const,
+          },
+          url: "https://linear.app/hack/issue/ENG-666",
+          teamId: "team-1",
+          projectId: "proj-remote",
+          assigneeId: "user-1",
+          labels: [],
+        },
+      }),
+      createIssue: async () => {
+        throw new Error("createIssue should not be called");
+      },
+      listTeamStates: async () => ({
+        ok: true as const,
+        data: [
+          {
+            id: "state-1",
+            name: "Todo",
+            type: "unstarted" as const,
+          },
+          {
+            id: "state-2",
+            name: "Done",
+            type: "completed" as const,
+          },
+        ],
+      }),
+      listTeamLabels: async () => ({
+        ok: true as const,
+        data: [],
+      }),
+      listIssueComments: async () => ({
+        ok: true as const,
+        data: [],
+      }),
+      createComment: async () => {
+        throw new Error("createComment should not be called");
+      },
+      listTeamUsers: async () => ({
+        ok: true as const,
+        data: [
+          {
+            id: "user-1",
+            email: "alice@example.com",
+            displayName: "Alice",
+          },
+        ],
+      }),
+      getProject: async () => ({ ok: true as const, data: null }),
+    },
+  };
+
+  const result = await __testOnly.syncTicketToLinearIssue({
+    runtime,
+    ticketId: "T-00006",
+    syncToggles: {
+      labels: false,
+      statuses: true,
+      dependencies: false,
+      projects: true,
+    },
+  });
+
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    return;
+  }
+
+  expect(recordedConflicts).toEqual([
+    expect.objectContaining({ field: "title", authority: "review_required" }),
+    expect.objectContaining({ field: "status", authority: "review_required" }),
+    expect.objectContaining({ field: "project", authority: "review_required" }),
+  ]);
+});
+
 test("syncTicketToLinearIssue records a deterministic checkpoint idempotency key", async () => {
   const checkpointInputs: Record<string, unknown>[] = [];
 
diff --git a/tests/tickets-store.test.ts b/tests/tickets-store.test.ts
index db942bb90..47d8e89b9 100644
--- a/tests/tickets-store.test.ts
+++ b/tests/tickets-store.test.ts
@@ -825,6 +825,92 @@ test("normalized ticket provenance captures multiple remotes, field authority, a
   );
 });
 
+test("projectNormalizedTicketSummary uses the latest description document", () => {
+  const normalized = createNormalizedTicket({
+    ticket: {
+      ticketId: "T-00089",
+      title: "Prefer the latest description",
+      body: "Legacy body",
+      status: "open",
+      createdAt: "2026-03-13T09:00:00.000Z",
+      updatedAt: "2026-03-13T12:00:00.000Z",
+      dependsOn: [],
+      blocks: [],
+      owner: "hack",
+      source: "hack",
+      tags: [],
+    },
+    documents: [
+      {
+        documentId: "T-00089:description:created",
+        ticketId: "T-00089",
+        kind: "description",
+        role: "description",
+        content: "Original description",
+        contentSha256: "sha-original",
+        createdAt: "2026-03-13T09:00:00.000Z",
+        updatedAt: "2026-03-13T09:00:00.000Z",
+      },
+      {
+        documentId: "T-00089:description:updated",
+        ticketId: "T-00089",
+        kind: "description",
+        role: "description",
+        content: "Latest description",
+        contentSha256: "sha-latest",
+        createdAt: "2026-03-13T11:00:00.000Z",
+        updatedAt: "2026-03-13T12:00:00.000Z",
+      },
+    ],
+  });
+
+  expect(projectNormalizedTicketSummary({ ticket: normalized }).body).toBe(
+    "Latest description"
+  );
+});
+
+test("normalized ticket field states map legacy body conflicts to description", () => {
+  const normalized = createNormalizedTicket({
+    ticket: {
+      ticketId: "T-00090",
+      title: "Normalize body conflicts",
+      body: "Local body",
+      status: "open",
+      createdAt: "2026-03-13T09:00:00.000Z",
+      updatedAt: "2026-03-13T12:00:00.000Z",
+      dependsOn: [],
+      blocks: [],
+      owner: "hack",
+      source: "linear",
+      tags: [],
+    },
+    conflicts: [
+      {
+        conflictId: "conflict-description",
+        ticketId: "T-00090",
+        provider: "linear",
+        field: "body",
+        status: "open",
+        authority: "review_required",
+        localValue: "Local body",
+        remoteValue: "Remote body",
+        createdAt: "2026-03-13T12:00:00.000Z",
+        updatedAt: "2026-03-13T12:00:00.000Z",
+      },
+    ],
+  });
+
+  expect(normalized.fieldStates).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        field: "description",
+        authority: "review_required",
+        conflictIds: ["conflict-description"],
+      }),
+    ])
+  );
+});
+
 test("ticket provenance infers a remote provider from source metadata when externalSystem is absent", () => {
   const ticket = {
     ticketId: "T-00088",

From 18ee39f2e9bb9e3ec4b5f1b88d066821f3fd6516 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 22:19:45 +0000
Subject: [PATCH 100/134] docs(tickets): finalize projection doc cleanup

---
 docs/architecture.md                          | 36 ++++++++-----------
 docs/guides/tickets.md                        | 21 ++++++-----
 ...-03-14-hack-tickets-sqlite-journal-plan.md |  3 +-
 3 files changed, 28 insertions(+), 32 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 1f5f88055..3f47d146f 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,7 +1,6 @@
 ## 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/`.
+
+`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/`.
 
 - **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.
@@ -68,7 +67,6 @@ graph LR
     - `.internal/extra-hosts.json` (user-managed extra_hosts merged into the override)
     - `.branch/compose.<branch>.override.yml` (branch builds)
 
-
 ## Internal DNS + TLS (containers)
 
 When `internal.dns` / `internal.tls` are enabled, `hack up` writes a Compose override that:
@@ -79,8 +77,7 @@ When `internal.dns` / `internal.tls` are enabled, `hack up` writes a Compose ove
 - injects `extra_hosts` mappings for `*.hack` → current Caddy IP (for runtimes that ignore custom DNS)
 - merges any repo-local `.hack/.internal/extra-hosts.json` entries (for host tunnels / dynamic domains)
 
-This lets containers use the same `https://*.hack` hostnames as the host machine. If Caddy’s IP changes,
-`hack status`, `hack doctor`, and the TUI will warn; `hack restart` refreshes the mapping.
+This lets containers use the same `https://*.hack` hostnames as the host machine. If Caddy’s IP changes, `hack status`, `hack doctor`, and the TUI will warn; `hack restart` refreshes the mapping.
 
 ```mermaid
 graph LR
@@ -89,7 +86,7 @@ graph LR
   Service -->|"HTTPS request"| Caddy["Caddy docker-proxy"]
   Caddy -->|"Routes by labels"| Upstream["Service upstream"]
 ```
- 
+
 ## Project env + secrets
 
 Projects can declare a shareable env contract (no values) and safely inject secrets into compose:
@@ -98,17 +95,13 @@ Projects can declare a shareable env contract (no values) and safely inject secr
 - Plain values: `.hack/.env` (gitignored, per-project)
 - Secrets: OS keychain via `Bun.secrets` (namespaced per project)
 
-At runtime, hack generates `.hack/.internal/compose.env.override.yml` containing `${KEY}` placeholders
-for the contract variables and invokes `docker compose` with a process environment that includes the
-resolved values (including keychain secrets).
+At runtime, hack generates `.hack/.internal/compose.env.override.yml` containing `${KEY}` placeholders for the contract variables and invokes `docker compose` with a process environment that includes the resolved values (including keychain secrets).
 
 See `docs/env.md` for the full contract format and CLI/API surface.
 
 ## Project lifecycle hooks + host processes
 
-Projects can run host-side hooks around `hack up/down` and start managed host processes (auth steps,
-local proxies/tunnels). Processes are started inside a mux session (tmux or zellij) so they have a
-stable home and can be torn down on `hack down`.
+Projects can run host-side hooks around `hack up/down` and start managed host processes (auth steps, local proxies/tunnels). Processes are started inside a mux session (tmux or zellij) so they have a stable home and can be torn down on `hack down`.
 
 See `docs/lifecycle.md` for config and behavior.
 
@@ -149,6 +142,7 @@ sequenceDiagram
 NDJSON streaming (`hack logs --json`) emits `start`, `log`, 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.
 - Per-project overrides live in `hack.config.json` under `logs.retention_period` and apply when `hack down` prunes logs.
 
@@ -165,8 +159,7 @@ Note: the daemon does not proxy logs yet; `hack logs` still talks directly to Do
 
 ## Daemon (hackd)
 
-`hackd` is an optional local daemon that watches Docker events and maintains a cached view of running
-containers. It serves a small local API over a Unix socket at `~/.hack/daemon/hackd.sock` and powers:
+`hackd` is an optional local daemon that watches Docker events and maintains a cached view of running containers. It serves a small local API over a Unix socket at `~/.hack/daemon/hackd.sock` and powers:
 
 - `hack projects --json`
 - `hack ps --json`
@@ -175,12 +168,12 @@ containers. It serves a small local API over a Unix socket at `~/.hack/daemon/ha
 If the daemon is not running (or version-mismatched), the CLI falls back to direct Docker calls.
 
 Runtime health:
-- The daemon treats the container runtime as ephemeral; it fingerprints the engine (socket + engine id)
-  and detects resets.
-- When the runtime is unavailable, cached state is retained but marked stale; API responses include
-  `runtime_*` metadata and project `status` becomes `unknown`.
+
+- The daemon treats the container runtime as ephemeral; it fingerprints the engine (socket + engine id) and detects resets.
+- When the runtime is unavailable, cached state is retained but marked stale; API responses include `runtime_*` metadata and project `status` becomes `unknown`.
 
 Why optional:
+
 - The CLI must keep working with zero background processes.
 - Not all users need cached JSON (especially if they only use interactive commands).
 - It stays off in minimal or constrained environments, but is available when you want faster status.
@@ -196,8 +189,7 @@ graph LR
 
 ## Control plane + extensions
 
-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`.
+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.
@@ -217,11 +209,13 @@ graph LR
 ### Gateway API + remote workflows
 
 The gateway exposes:
+
 - `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.
diff --git a/docs/guides/tickets.md b/docs/guides/tickets.md
index b9594fed9..e53e2b937 100644
--- a/docs/guides/tickets.md
+++ b/docs/guides/tickets.md
@@ -1,8 +1,6 @@
 # Tickets (git-backed)
 
-The tickets extension is a lightweight, git-backed ticket log intended for small teams and solo dev.
-It stores events in a dedicated git ref (`refs/hack/tickets` by default, hidden from branch lists) so
-ticket history is versioned and syncable without requiring an external service.
+The tickets extension is a lightweight, git-backed ticket log intended for small teams and solo dev. It stores events in a dedicated git ref (`refs/hack/tickets` by default, hidden from branch lists) so ticket history is versioned and syncable without requiring an external service.
 
 - CLI namespace: `tickets`
 - Extension id: `dance.hack.tickets`
@@ -40,13 +38,14 @@ hack x tickets setup
 ```
 
 Options:
+
 - `--global` installs the Codex skill into `~/.codex/skills/hack-tickets/` instead of the repo.
 - `--agents` / `--claude` / `--all` control which agent-doc files get a tickets snippet.
 - `--check` and `--remove` work as expected.
 
 Notes:
-- Most tickets commands prompt to run setup if `.hack/tickets/` is tracked, missing from `.gitignore`,
-  or if agent docs/skills are missing (TTY + gum only).
+
+- Most tickets commands prompt to run setup if `.hack/tickets/` is tracked, missing from `.gitignore`, or if agent docs/skills are missing (TTY + gum only).
 - Setup also prompts to repair legacy tickets branches or stray files in the tickets ref.
 - In non-interactive or `--json` modes, the CLI prints a warning instead of prompting.
 
@@ -116,8 +115,11 @@ Recommended body template (Markdown):
 
 ```md
 ## Context
+
 ## Goals
+
 ## Notes
+
 ## Links
 ```
 
@@ -153,8 +155,7 @@ In your project repo:
 
 ## Configuration
 
-Tickets git configuration lives under `controlPlane.tickets.git`.
-Defaults:
+Tickets git configuration lives under `controlPlane.tickets.git`. Defaults:
 
 - `enabled: true`
 - `branch: "hack/tickets"`
@@ -171,16 +172,18 @@ hack config set --global 'controlPlane.tickets.git.refMode' 'hidden'
 ```
 
 Notes:
-- If your remote rejects hidden refs, set `refMode` to `heads` to use `refs/heads/<branch>` and
-  protect the branch in your git hosting UI.
+
+- If your remote rejects hidden refs, set `refMode` to `heads` to use `refs/heads/<branch>` and protect the branch in your git hosting UI.
 
 ## When to use this
 
 Use tickets when you want:
+
 - A local-first backlog that works offline.
 - A shared ticket stream without adding Jira/Linear.
 - A simple paper trail for small projects.
 
 Don’t use it when:
+
 - You need multi-user assignment, workflow states, or strict permissions.
 - You need rich issue templates or deep integrations.
diff --git a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
index b5dd5524a..86c84533e 100644
--- a/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
+++ b/docs/plans/2026-03-14-hack-tickets-sqlite-journal-plan.md
@@ -132,8 +132,7 @@ git commit -m "feat(tickets): replay journal into sqlite projection"
 - `getTicketDetail`
 - any sync lookup helpers added during implementation
 
-These reads should prefer SQLite and only trigger replay or rebuild when projection state is missing or stale.
-Add assertions that `tickets list`, `tickets show`, and `tickets status` still expose the correct status, `updated_at`, and effective blocker set once reads come from SQLite.
+These reads should prefer SQLite and only trigger replay or rebuild when projection state is missing or stale. Add assertions that `tickets list`, `tickets show`, and `tickets status` still expose the correct status, `updated_at`, and effective blocker set once reads come from SQLite.
 
 **Step 2: Preserve write path semantics**
 

From c54be5e2abcec96375a481deaae29f8ca6b4c9ce Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 22:20:12 +0000
Subject: [PATCH 101/134] docs: clarify github integration capability story

---
 README.md            |  7 ++++---
 docs/integrations.md | 17 ++++++++++++++---
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 40bd39448..73bd9e4db 100644
--- a/README.md
+++ b/README.md
@@ -87,11 +87,12 @@ Hack has a few supporting surfaces that matter after your project is already run
 
 ### GitHub
 
-Use GitHub integration when you want Hack to authenticate repo workflows or create and update pull
-requests for you.
+Use GitHub integration when you want Hack to authenticate repo workflows and carry pull-request
+context cleanly between GitHub and local Hack work.
 
 - Main surface: `hack x github ...`
-- Common use: connect a profile, then use PR or repo automation from Hack workflows
+- Common use: connect a profile, inspect status, then use PR update or repo-aware automation
+  workflows from Hack
 - Reference: [docs/extensions.md](docs/extensions.md)
 
 ### Linear
diff --git a/docs/integrations.md b/docs/integrations.md
index 6edaede17..2b22aad85 100644
--- a/docs/integrations.md
+++ b/docs/integrations.md
@@ -10,23 +10,34 @@ The easiest way to think about these integrations is:
 
 ## GitHub
 
-GitHub integration is for repo auth and pull-request workflows.
+GitHub integration is the capability layer for repo auth, pull-request workflows, and repo-aware
+handoff between GitHub context and local Hack work.
 
 Use it when you want Hack to:
 
 - authenticate private repo or automation flows
+- keep more than one GitHub identity or installation context available on the same machine
 - create or update a PR as part of a run or release workflow
-- keep more than one GitHub profile available on the same machine
+- make the first-class GitHub workflow set explicit before deeper review/comment/repo-handoff
+  commands land
 
-Main surface:
+Main surface today:
 
 - `hack x github connect`
 - `hack x github status`
 - `hack x github pr-upsert`
 
+Defined workflow boundary for this milestone:
+
+- review intake and review decision
+- PR update and readiness management
+- PR-level conversation comments
+- PR-adjacent repo handoff actions
+
 Reference:
 
 - [Extensions & SDK reference](extensions.md)
+- [GitHub first-class workflows design](plans/2026-03-13-github-first-class-workflows-design.md)
 
 ## Linear
 

From 73203cd4ad4644f082ebffabbce6e9318cd511e4 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 22:20:37 +0000
Subject: [PATCH 102/134] docs(env): clarify managed artifact invariants

---
 docs/env.md                                                 | 3 ++-
 ...026-03-13-portable-project-env-artifact-schema-design.md | 6 ++++--
 src/templates.ts                                            | 2 +-
 tests/project-config-schema.test.ts                         | 3 ++-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/docs/env.md b/docs/env.md
index 06b396f14..8b5c9db19 100644
--- a/docs/env.md
+++ b/docs/env.md
@@ -100,6 +100,7 @@ Managed artifact rules:
 
 - `entries[].value.kind` distinguishes logical plaintext from logical secrets
 - `entries[].value.text` is the canonical string value before outer-envelope encryption
+- duplicate keys and unsorted entry lists are parser and writer invariants; the JSON Schema documents the contract but cannot enforce those constraints on its own
 - `services` belongs in the managed artifact because portability must preserve service intent outside the originating machine
 - `metadata` captures human and CLI/Desktop provenance, not machine-local backend details
 - the artifact must not store local absolute paths, keychain service names, backend provider configuration, or runtime resolution history such as `resolvedFrom`
@@ -113,7 +114,7 @@ Local compatibility rules:
 
 Planned CLI behavior when a managed artifact is active:
 
-1. Reads validate artifact keys against `.hack/hack.env.json` when present.
+1. Reads validate artifact keys against the normalized `.hack/hack.env.json` contract when present. Current contract parsing is looser than the published schema, so artifact-aware commands should surface drift instead of assuming strict schema parity.
 2. Reads report artifact intent, local materialization state, and drift between them.
 3. `hack env set` mutates the canonical artifact first, then materializes the entry to `.hack/.env` or the configured secret backend based on `value.kind`.
 4. If an entry changes kind, Hack removes stale local state from the old compatibility target before writing the new one.
diff --git a/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md b/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md
index c95aedaad..c9e2856ee 100644
--- a/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md
+++ b/docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md
@@ -148,7 +148,7 @@ Purpose:
 - `metadata.updatedAt`: RFC 3339 timestamp for the last artifact mutation
 - `metadata.updatedBy`: actor class such as `cli`, `desktop`, or `api`
 - `metadata.source`: producing surface such as `hack-cli` or `hack-desktop`
-- `entries`: stable, key-sorted list of managed env entries
+- `entries`: stable, key-sorted list of managed env entries. Duplicate keys and unsorted lists are parser and writer errors even though JSON Schema cannot enforce them directly.
 
 ### Entry fields
 
@@ -222,10 +222,12 @@ The contract and artifact intentionally overlap on a few fields. The rules shoul
 
 - contract defines the expected shape of the project env surface
 - artifact carries the managed snapshot used for portability
-- when both exist, key names must be validated against the contract
+- when both exist, key names must be validated against the normalized contract
 - if `required`, `services`, or `description` disagree, the artifact wins for apply/export behavior and the CLI should surface drift
 - unknown artifact keys should warn by default and require explicit confirmation before apply
 
+Today the live contract parser is looser than the published contract schema. Artifact-aware commands should therefore normalize and compare contract entries explicitly instead of assuming the current parser already enforces uppercase key, source, or service-shape invariants.
+
 This keeps the artifact self-contained while still treating the committed contract as the project declaration surface.
 
 ## CLI Read Behavior
diff --git a/src/templates.ts b/src/templates.ts
index e35c3db9d..bdc16f4c3 100644
--- a/src/templates.ts
+++ b/src/templates.ts
@@ -694,7 +694,7 @@ export function renderProjectManagedEnvSchemaJson(): string {
       entries: {
         type: "array",
         description:
-          "Managed env entries sorted by key. Duplicate keys must be rejected by artifact parsers and writers.",
+          "Managed env entries sorted by key. Duplicate keys and unsorted entries must be rejected by dedicated artifact parsers and writers.",
         items: {
           type: "object",
           additionalProperties: false,
diff --git a/tests/project-config-schema.test.ts b/tests/project-config-schema.test.ts
index 4640bad90..b4708b154 100644
--- a/tests/project-config-schema.test.ts
+++ b/tests/project-config-schema.test.ts
@@ -77,7 +77,8 @@ test("managed env schema models entry kind, metadata, and service scope", () =>
   });
 
   const entries = properties.entries as Record<string, unknown>;
-  expect(entries.description).toContain("Duplicate keys must be rejected");
+  expect(entries.description).toContain("Duplicate keys");
+  expect(entries.description).toContain("unsorted entries");
   const entry = entries.items as Record<string, unknown>;
   expect(entry.additionalProperties).toBe(false);
   expect(entry.required).toEqual(["key", "value", "required"]);

From ef8b180ed8d137271721b62fe424b1bb434560eb Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 22:21:17 +0000
Subject: [PATCH 103/134] fix: unify recovery workflow formatting

---
 src/commands/crash-capture.ts     | 61 ++-----------------------------
 src/commands/doctor.ts            | 51 ++++----------------------
 src/commands/recovery-guidance.ts | 61 +++++++++++++++++++++++++++++++
 tests/doctor-command.test.ts      | 30 +++++++++++++++
 4 files changed, 102 insertions(+), 101 deletions(-)

diff --git a/src/commands/crash-capture.ts b/src/commands/crash-capture.ts
index a4e5caaab..18948d587 100644
--- a/src/commands/crash-capture.ts
+++ b/src/commands/crash-capture.ts
@@ -14,10 +14,9 @@ import { display } from "../ui/display.ts";
 import {
   buildDoctorRecoveryGuidance,
   buildRecoveryNextSteps,
+  buildRecoveryWorkflowLines,
   type DoctorRecoveryGuidance,
   type RecoveryCheckResult,
-  scopeDoctorRecoveryGuidance,
-  scopeRecoveryCommand,
 } from "./recovery-guidance.ts";
 
 const DEFAULT_LOG_WINDOW = "45m";
@@ -931,64 +930,10 @@ export function renderCrashCaptureReadme(input: {
     ...failedCommands,
     "",
     "Suggested recovery flow:",
-    ...renderRecoveryWorkflow({
+    ...buildRecoveryWorkflowLines({
       guidance: input.recovery,
       projectRoot: input.projectRoot,
+      includeClassifyStep: true,
     }),
   ].join("\n");
 }
-
-function renderRecoveryWorkflow(input: {
-  readonly guidance: DoctorRecoveryGuidance;
-  readonly projectRoot: string | null;
-}): readonly string[] {
-  const scoped = scopeDoctorRecoveryGuidance({
-    guidance: input.guidance,
-    projectRoot: input.projectRoot,
-  });
-  const lines = [
-    "1. Classify:",
-    `   - \`${scopeRecoveryCommand({
-      command: "hack doctor",
-      projectRoot: input.projectRoot,
-    })}\``,
-  ];
-  let stepNumber = 2;
-
-  if (scoped.temporaryBreakage.length > 0) {
-    lines.push(`${stepNumber}. Temporary breakage:`);
-    for (const command of scoped.temporaryBreakage) {
-      lines.push(`   - \`${command}\``);
-    }
-    stepNumber += 1;
-  }
-
-  if (scoped.configurationRepair.length > 0) {
-    lines.push(`${stepNumber}. Configuration repair:`);
-    for (const command of scoped.configurationRepair) {
-      lines.push(`   - \`${command}\``);
-    }
-    stepNumber += 1;
-  }
-
-  if (scoped.followUp.length > 0) {
-    lines.push(`${stepNumber}. Manual follow-up:`);
-    for (const item of scoped.followUp) {
-      lines.push(`   - ${item}`);
-    }
-    stepNumber += 1;
-  }
-
-  lines.push(`${stepNumber}. Verify:`);
-  for (const command of scoped.verify) {
-    lines.push(`   - \`${command}\``);
-  }
-  stepNumber += 1;
-
-  lines.push(`${stepNumber}. If it still fails:`);
-  for (const command of scoped.capture) {
-    lines.push(`   - \`${command}\``);
-  }
-
-  return lines;
-}
diff --git a/src/commands/doctor.ts b/src/commands/doctor.ts
index c5bce2e5f..8727da150 100644
--- a/src/commands/doctor.ts
+++ b/src/commands/doctor.ts
@@ -70,7 +70,10 @@ import {
   resolvePreferredHostDnsTarget,
   resolverHasNameserver,
 } from "./doctor-utils.ts";
-import { buildDoctorRecoveryGuidance } from "./recovery-guidance.ts";
+import {
+  buildDoctorRecoveryGuidance,
+  buildRecoveryWorkflowLines,
+} from "./recovery-guidance.ts";
 
 type CheckStatus = "ok" | "warn" | "error";
 
@@ -2189,51 +2192,13 @@ async function renderRecoveryGuidance(
     return;
   }
 
-  const lines: string[] = [];
-
-  if (guidance.temporaryBreakage.length > 0) {
-    lines.push("Temporary breakage:");
-    for (const command of guidance.temporaryBreakage) {
-      lines.push(`- ${command}`);
-    }
-  }
-
-  if (guidance.configurationRepair.length > 0) {
-    if (lines.length > 0) {
-      lines.push("");
-    }
-    lines.push("Configuration repair:");
-    for (const command of guidance.configurationRepair) {
-      lines.push(`- ${command}`);
-    }
-  }
-
-  if (guidance.followUp.length > 0) {
-    if (lines.length > 0) {
-      lines.push("");
-    }
-    lines.push("Manual follow-up:");
-    for (const item of guidance.followUp) {
-      lines.push(`- ${item}`);
-    }
-  }
-
-  lines.push("");
-  lines.push("Verify:");
-  for (const command of guidance.verify) {
-    lines.push(`- ${command}`);
-  }
-
-  lines.push("");
-  lines.push("If it still fails:");
-  for (const command of guidance.capture) {
-    lines.push(`- ${command}`);
-  }
-
   await display.panel({
     title: "Recovery workflow",
     tone: "info",
-    lines,
+    lines: buildRecoveryWorkflowLines({
+      guidance,
+      projectRoot: null,
+    }),
   });
 }
 
diff --git a/src/commands/recovery-guidance.ts b/src/commands/recovery-guidance.ts
index 161de4f9b..57f9ba599 100644
--- a/src/commands/recovery-guidance.ts
+++ b/src/commands/recovery-guidance.ts
@@ -147,6 +147,67 @@ export function buildRecoveryNextSteps(input: {
   return nextSteps;
 }
 
+export function buildRecoveryWorkflowLines(input: {
+  readonly guidance: DoctorRecoveryGuidance;
+  readonly projectRoot: string | null;
+  readonly includeClassifyStep?: boolean;
+}): readonly string[] {
+  const scoped = scopeDoctorRecoveryGuidance({
+    guidance: input.guidance,
+    projectRoot: input.projectRoot,
+  });
+  const lines: string[] = [];
+  let stepNumber = 1;
+
+  if (input.includeClassifyStep ?? false) {
+    lines.push(`${stepNumber}. Classify:`);
+    lines.push(
+      `   - \`${scopeRecoveryCommand({
+        command: "hack doctor",
+        projectRoot: input.projectRoot,
+      })}\``
+    );
+    stepNumber += 1;
+  }
+
+  if (scoped.temporaryBreakage.length > 0) {
+    lines.push(`${stepNumber}. Temporary breakage:`);
+    for (const command of scoped.temporaryBreakage) {
+      lines.push(`   - \`${command}\``);
+    }
+    stepNumber += 1;
+  }
+
+  if (scoped.configurationRepair.length > 0) {
+    lines.push(`${stepNumber}. Configuration repair:`);
+    for (const command of scoped.configurationRepair) {
+      lines.push(`   - \`${command}\``);
+    }
+    stepNumber += 1;
+  }
+
+  if (scoped.followUp.length > 0) {
+    lines.push(`${stepNumber}. Manual follow-up:`);
+    for (const item of scoped.followUp) {
+      lines.push(`   - ${item}`);
+    }
+    stepNumber += 1;
+  }
+
+  lines.push(`${stepNumber}. Verify:`);
+  for (const command of scoped.verify) {
+    lines.push(`   - \`${command}\``);
+  }
+  stepNumber += 1;
+
+  lines.push(`${stepNumber}. If it still fails:`);
+  for (const command of scoped.capture) {
+    lines.push(`   - \`${command}\``);
+  }
+
+  return lines;
+}
+
 export function scopeRecoveryCommand(input: {
   readonly command: string;
   readonly projectRoot: string | null;
diff --git a/tests/doctor-command.test.ts b/tests/doctor-command.test.ts
index ff5323ac8..3905e4049 100644
--- a/tests/doctor-command.test.ts
+++ b/tests/doctor-command.test.ts
@@ -3,6 +3,7 @@ import { expect, test } from "bun:test";
 import {
   buildDoctorRecoveryGuidance,
   buildRecoveryNextSteps,
+  buildRecoveryWorkflowLines,
 } from "../src/commands/recovery-guidance.ts";
 
 test("doctor guidance distinguishes restartable proxy drift from deeper repair", () => {
@@ -125,3 +126,32 @@ test("recovery next steps quote repo paths for copy-paste safety", () => {
     "If it still fails, run `hack crash-capture --path '/tmp/work repo'` again after the next repro.",
   ]);
 });
+
+test("recovery workflow lines scope repo-specific commands for doctor output", () => {
+  const lines = buildRecoveryWorkflowLines({
+    guidance: {
+      temporaryBreakage: ["hack restart"],
+      configurationRepair: ["hack doctor --fix"],
+      followUp: ["gateway tokens: No active tokens"],
+      verify: ["hack doctor"],
+      capture: ["hack crash-capture --path <repo>"],
+    },
+    projectRoot: "/tmp/work repo",
+    includeClassifyStep: true,
+  });
+
+  expect(lines).toEqual([
+    "1. Classify:",
+    "   - `hack doctor --path '/tmp/work repo'`",
+    "2. Temporary breakage:",
+    "   - `hack restart --path '/tmp/work repo'`",
+    "3. Configuration repair:",
+    "   - `hack doctor --fix --path '/tmp/work repo'`",
+    "4. Manual follow-up:",
+    "   - gateway tokens: No active tokens",
+    "5. Verify:",
+    "   - `hack doctor --path '/tmp/work repo'`",
+    "6. If it still fails:",
+    "   - `hack crash-capture --path '/tmp/work repo'`",
+  ]);
+});

From 1b1c083bcee881dbf524f8b80a46b86f65497f35 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 23:28:15 +0000
Subject: [PATCH 104/134] feat(tickets): use random ticket ids

---
 .hack/README.md                               |   4 +-
 README.md                                     |   2 +-
 docs/extensions.md                            |   8 +-
 src/agents/codex-skill.ts                     |   4 +-
 src/commands/linear.ts                        |   2 +-
 .../extensions/linear/commands.ts             |   2 +-
 .../extensions/tickets/agent-docs.ts          |   8 +-
 src/control-plane/extensions/tickets/store.ts |  31 +-
 .../extensions/tickets/tickets-git-channel.ts | 278 +++++++++++-------
 src/control-plane/extensions/tickets/util.ts  |  57 +++-
 src/mcp/agent-docs.ts                         |   4 +-
 src/mcp/server.ts                             |   5 +-
 tests/tickets-extension.test.ts               |  38 ++-
 tests/tickets-store.test.ts                   |  76 +++++
 tests/tickets-util.test.ts                    |  27 ++
 15 files changed, 384 insertions(+), 162 deletions(-)
 create mode 100644 tests/tickets-util.test.ts

diff --git a/.hack/README.md b/.hack/README.md
index 0d930ede5..74032c7e4 100644
--- a/.hack/README.md
+++ b/.hack/README.md
@@ -7,8 +7,8 @@ This repo is dogfooding the tickets extension.
   - `hack x tickets setup`
   - `hack x tickets create --title "..." --body-stdin`
   - `hack x tickets list`
-  - `hack x tickets show T-00001`
-  - `hack x tickets status T-00001 in_progress`
+  - `hack x tickets show T-AB12CD34EF`
+  - `hack x tickets status T-AB12CD34EF in_progress`
   - `hack x tickets sync`
 
 No services are required for this repo; `docker-compose.yml` is intentionally empty.
diff --git a/README.md b/README.md
index 31d64cc93..ed18eea4e 100644
--- a/README.md
+++ b/README.md
@@ -143,7 +143,7 @@ hack x tickets list
 hack x tickets tui
 
 # Update status
-hack x tickets status T-00001 in_progress
+hack x tickets status T-AB12CD34EF in_progress
 
 # Sync to remote
 hack x tickets sync
diff --git a/docs/extensions.md b/docs/extensions.md
index b4c8b0a81..c7ba36bf3 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -291,7 +291,7 @@ hack x linear project-bind --profile work --project-id "<linear-project-id>"
 
 # one-off syncs (manual by default)
 hack x linear sync-issue --from linear --issue ENG-123
-hack x linear sync-issue --from hack --ticket T-00001
+hack x linear sync-issue --from hack --ticket T-AB12CD34EF
 
 # bulk sync by project (still manual)
 hack x linear sync-project --from linear
@@ -504,6 +504,8 @@ Notes:
 
 A lightweight, git-backed ticket log stored in `.hack/tickets/` and syncable via a dedicated git ref (`refs/hack/tickets` hidden by default).
 
+New tickets use random `T-XXXXXXXXXX` ids. Existing legacy sequential ids such as `T-00001` remain valid for lookup and updates.
+
 Guide: `docs/guides/tickets.md`
 
 #### setup
@@ -512,11 +514,11 @@ Usage: `hack x tickets setup [--global] [--agents|--claude|--all] [--check|--rem
 
 #### create
 
-Usage: `hack x tickets create --title "..." [--body "..."] [--body-file <path>] [--body-stdin] [--depends-on "T-00001"] [--blocks "T-00002"] [--owner "hack|linear|..."] [--source "hack|linear|..."] [--tag "foo"] [--external-system "linear"] [--external-id "<id>"] [--external-key "ENG-123"] [--external-url "<url>"] [--external-project-id "<id>"] [--external-project-name "..."] [--external-team-id "<id>"] [--actor "..."] [--json]`
+Usage: `hack x tickets create --title "..." [--body "..."] [--body-file <path>] [--body-stdin] [--depends-on "T-AB12CD34EF"] [--blocks "T-ZX98NM12QR"] [--owner "hack|linear|..."] [--source "hack|linear|..."] [--tag "foo"] [--external-system "linear"] [--external-id "<id>"] [--external-key "ENG-123"] [--external-url "<url>"] [--external-project-id "<id>"] [--external-project-name "..."] [--external-team-id "<id>"] [--actor "..."] [--json]`
 
 #### update
 
-Usage: `hack x tickets update <ticket-id> [--title "..."] [--body "..."] [--body-file <path>] [--body-stdin] [--depends-on "T-00001"] [--blocks "T-00002"] [--clear-depends-on] [--clear-blocks] [--owner "..."] [--source "..."] [--tag "foo"] [--clear-tags] [--external-system "linear"] [--external-id "<id>"] [--external-key "ENG-123"] [--external-url "<url>"] [--external-project-id "<id>"] [--external-project-name "..."] [--external-team-id "<id>"] [--actor "..."] [--json]`
+Usage: `hack x tickets update <ticket-id> [--title "..."] [--body "..."] [--body-file <path>] [--body-stdin] [--depends-on "T-AB12CD34EF"] [--blocks "T-ZX98NM12QR"] [--clear-depends-on] [--clear-blocks] [--owner "..."] [--source "..."] [--tag "foo"] [--clear-tags] [--external-system "linear"] [--external-id "<id>"] [--external-key "ENG-123"] [--external-url "<url>"] [--external-project-id "<id>"] [--external-project-name "..."] [--external-team-id "<id>"] [--actor "..."] [--json]`
 
 #### list
 
diff --git a/src/agents/codex-skill.ts b/src/agents/codex-skill.ts
index fdf6424b6..70d4075e2 100644
--- a/src/agents/codex-skill.ts
+++ b/src/agents/codex-skill.ts
@@ -227,8 +227,8 @@ export function renderCodexSkill(): string {
     "## Tickets",
     "",
     '- Create: `hack tickets create --title "..." --body-stdin`',
-    "- List/show: `hack tickets list`, `hack tickets show T-00001`",
-    "- Status/sync: `hack tickets status T-00001 in_progress`, `hack tickets sync`",
+    "- List/show: `hack tickets list`, `hack tickets show T-AB12CD34EF`",
+    "- Status/sync: `hack tickets status T-AB12CD34EF in_progress`, `hack tickets sync`",
     "",
     "## Project Targeting",
     "",
diff --git a/src/commands/linear.ts b/src/commands/linear.ts
index 7c3426f9c..f3daecd6e 100644
--- a/src/commands/linear.ts
+++ b/src/commands/linear.ts
@@ -22,7 +22,7 @@ const linearSpec = defineCommand({
     "  hack linear oauth-connect --profile work --set-default",
     "  hack linear project-bind --project-id <linear-project-id>",
     "  hack linear sync-issue --from linear --issue ENG-123",
-    "  hack linear sync-issue --from hack --ticket T-00001",
+    "  hack linear sync-issue --from hack --ticket T-AB12CD34EF",
     "  hack linear sync-project --from linear --project-id <linear-project-id>",
     "",
     "Alias for `hack x linear <command>`. Requires extension enabled.",
diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index ebaf9b342..df0f770ea 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -1202,7 +1202,7 @@ export const LINEAR_COMMANDS: readonly ExtensionCommand[] = [
       const ticketInput = parsed.value.ticketId;
       if (!ticketInput) {
         ctx.logger.error({
-          message: "Missing --ticket <T-00001> for --from hack.",
+          message: "Missing --ticket <ticket-id> for --from hack.",
         });
         return 1;
       }
diff --git a/src/control-plane/extensions/tickets/agent-docs.ts b/src/control-plane/extensions/tickets/agent-docs.ts
index 45153c5c4..2cca52143 100644
--- a/src/control-plane/extensions/tickets/agent-docs.ts
+++ b/src/control-plane/extensions/tickets/agent-docs.ts
@@ -144,12 +144,12 @@ export function renderTicketsAgentDocsSnippet(): string {
     "This project uses `hack` tickets (extension: `dance.hack.tickets`).",
     "",
     "Common commands:",
-    '- Create: `hack tickets create --title "..." --body-stdin [--depends-on "T-00001"] [--blocks "T-00002"]`',
+    '- Create: `hack tickets create --title "..." --body-stdin [--depends-on "T-AB12CD34EF"] [--blocks "T-ZX98NM12QR"]`',
     "- List: `hack tickets list`",
     "- Tui: `hack tickets tui`",
-    "- Show: `hack tickets show T-00001`",
-    '- Update: `hack tickets update T-00001 [--title "..."] [--body "..."] [--depends-on "..."] [--blocks "..."]`',
-    "- Status: `hack tickets status T-00001 in_progress`",
+    "- Show: `hack tickets show T-AB12CD34EF`",
+    '- Update: `hack tickets update T-AB12CD34EF [--title "..."] [--body "..."] [--depends-on "..."] [--blocks "..."]`',
+    "- Status: `hack tickets status T-AB12CD34EF in_progress`",
     "- Sync: `hack tickets sync`",
     "",
     "Recommended body template (Markdown):",
diff --git a/src/control-plane/extensions/tickets/store.ts b/src/control-plane/extensions/tickets/store.ts
index cdf69ba2c..c5a75fa6e 100644
--- a/src/control-plane/extensions/tickets/store.ts
+++ b/src/control-plane/extensions/tickets/store.ts
@@ -7,9 +7,9 @@ import { isRecord } from "../../../lib/guards.ts";
 import type { ControlPlaneConfig } from "../../sdk/config.ts";
 import { createGitTicketsChannel } from "./tickets-git-channel.ts";
 import {
-  formatTicketId,
+  compareTicketIds,
+  generateTicketId,
   normalizeTicketRefs,
-  parseTicketNumber,
   unixSeconds,
 } from "./util.ts";
 
@@ -426,25 +426,14 @@ export function createTicketsStore(opts: {
     readonly tickets: Iterable<TicketSummary>;
   }): TicketSummary[] => {
     const out = [...input.tickets];
-    out.sort(
-      (a, b) =>
-        (parseTicketNumber(a.ticketId) ?? 0) -
-        (parseTicketNumber(b.ticketId) ?? 0)
-    );
-    return out;
-  };
-
-  const computeNextTicketId = async (): Promise<string> => {
-    const events = await readAllEvents();
-    const snapshot = materializeSnapshotFromEvents({ events });
-    let max = 0;
-    for (const ticketId of snapshot.tickets.keys()) {
-      const n = parseTicketNumber(ticketId);
-      if (n !== null && n > max) {
-        max = n;
+    out.sort((left, right) => {
+      const createdAt = left.createdAt.localeCompare(right.createdAt);
+      if (createdAt !== 0) {
+        return createdAt;
       }
-    }
-    return formatTicketId(max + 1);
+      return compareTicketIds(left.ticketId, right.ticketId);
+    });
+    return out;
   };
 
   const setStatus = async (input: {
@@ -472,7 +461,7 @@ export function createTicketsStore(opts: {
 
   return {
     createTicket: async (input) => {
-      const ticketId = await computeNextTicketId();
+      const ticketId = generateTicketId();
       const dependsOn = normalizeTicketRefs(input.dependsOn ?? []);
       const blocks = normalizeTicketRefs(input.blocks ?? []);
       const owner = normalizeOwnerOrSource({
diff --git a/src/control-plane/extensions/tickets/tickets-git-channel.ts b/src/control-plane/extensions/tickets/tickets-git-channel.ts
index 7517170e2..d78ae2ed2 100644
--- a/src/control-plane/extensions/tickets/tickets-git-channel.ts
+++ b/src/control-plane/extensions/tickets/tickets-git-channel.ts
@@ -1,4 +1,4 @@
-import { mkdir, readdir, rm, stat } from "node:fs/promises";
+import { mkdir, open, readdir, rm, stat, unlink } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
 import { isRecord } from "../../../lib/guards.ts";
@@ -7,6 +7,9 @@ import { stableStringify } from "./util.ts";
 
 const REFS_HEADS_PREFIX_PATTERN = /^refs\/heads\//;
 const REFS_PREFIX_PATTERN = /^refs\//;
+const MUTATION_LOCK_RETRY_MS = 100;
+const MUTATION_LOCK_STALE_MS = 30_000;
+const MUTATION_LOCK_TIMEOUT_MS = 10_000;
 
 export type TicketsGitChannel = {
   readonly ensureCheckedOut: () => Promise<string>;
@@ -85,6 +88,7 @@ export function createGitTicketsChannel(opts: {
     : null;
   const remoteName = gitEnabled ? (opts.config.remote ?? "origin").trim() : "";
   const bareIndexLockPath = resolve(bareDir, "index.lock");
+  const mutationLockPath = resolve(gitDir, ".mutation.lock");
 
   const resolvePushRefForCheckout = (input: {
     readonly checkoutRef: string;
@@ -166,6 +170,58 @@ export function createGitTicketsChannel(opts: {
     await mkdir(worktreeDir, { recursive: true });
   };
 
+  const withMutationLock = async <T>(fn: () => Promise<T>): Promise<T> => {
+    await acquireMutationLock();
+    try {
+      return await fn();
+    } finally {
+      await releaseMutationLock();
+    }
+  };
+
+  const acquireMutationLock = async (): Promise<void> => {
+    await mkdir(dirname(mutationLockPath), { recursive: true });
+    const start = Date.now();
+
+    while (true) {
+      try {
+        const file = await open(mutationLockPath, "wx");
+        await file.writeFile(`${process.pid}\n`);
+        await file.close();
+        return;
+      } catch (error: unknown) {
+        const code =
+          typeof error === "object" && error !== null && "code" in error
+            ? (error as { code?: string }).code
+            : undefined;
+        if (code !== "EEXIST") {
+          throw error;
+        }
+        if (await isMutationLockStale()) {
+          await unlink(mutationLockPath).catch(() => undefined);
+          continue;
+        }
+        if (Date.now() - start > MUTATION_LOCK_TIMEOUT_MS) {
+          throw new Error("Timed out waiting for tickets git mutation lock");
+        }
+        await Bun.sleep(MUTATION_LOCK_RETRY_MS);
+      }
+    }
+  };
+
+  const releaseMutationLock = async (): Promise<void> => {
+    await unlink(mutationLockPath).catch(() => undefined);
+  };
+
+  const isMutationLockStale = async (): Promise<boolean> => {
+    try {
+      const info = await stat(mutationLockPath);
+      return Date.now() - info.mtimeMs > MUTATION_LOCK_STALE_MS;
+    } catch {
+      return false;
+    }
+  };
+
   const ensureBareRepo = async () => {
     try {
       const st = await stat(bareDir);
@@ -951,76 +1007,78 @@ export function createGitTicketsChannel(opts: {
   const repair = async (input: {
     readonly pruneLegacyRef: boolean;
   }): Promise<TicketsGitRepairResult> => {
-    const checkedOut = await ensureCheckedOut();
-    if (!checkedOut.ok) {
-      return checkedOut;
-    }
+    return await withMutationLock(async () => {
+      const checkedOut = await ensureCheckedOut();
+      if (!checkedOut.ok) {
+        return checkedOut;
+      }
 
-    const repairBranch = `${branch}-repair`;
-    const orphan = await runGitDir({
-      args: ["checkout", "--orphan", repairBranch],
-    });
-    if (!orphan.ok) {
-      return {
-        ok: false,
-        error: `git checkout --orphan failed: ${orphan.stderr.trim()}`,
-      };
-    }
+      const repairBranch = `${branch}-repair`;
+      const orphan = await runGitDir({
+        args: ["checkout", "--orphan", repairBranch],
+      });
+      if (!orphan.ok) {
+        return {
+          ok: false,
+          error: `git checkout --orphan failed: ${orphan.stderr.trim()}`,
+        };
+      }
 
-    const pruned = await pruneWorktreeToTickets();
-    if (!pruned.ok) {
-      return pruned;
-    }
+      const pruned = await pruneWorktreeToTickets();
+      if (!pruned.ok) {
+        return pruned;
+      }
 
-    const renamed = await runGitDir({
-      args: ["branch", "-M", repairBranch, branch],
-    });
-    if (!renamed.ok) {
-      return {
-        ok: false,
-        error: `git branch -M failed: ${renamed.stderr.trim()}`,
-      };
-    }
+      const renamed = await runGitDir({
+        args: ["branch", "-M", repairBranch, branch],
+      });
+      if (!renamed.ok) {
+        return {
+          ok: false,
+          error: `git branch -M failed: ${renamed.stderr.trim()}`,
+        };
+      }
 
-    const committed = await commitAll("tickets: repair");
-    if (!committed.ok) {
-      return committed;
-    }
+      const committed = await commitAll("tickets: repair");
+      if (!committed.ok) {
+        return committed;
+      }
 
-    const pushed = await pushWithRetry({
-      remoteUrl: checkedOut.remoteUrl,
-      pushRef: checkedOut.pushRef,
-    });
-    if (!pushed.ok) {
-      return pushed;
-    }
+      const pushed = await pushWithRetry({
+        remoteUrl: checkedOut.remoteUrl,
+        pushRef: checkedOut.pushRef,
+      });
+      if (!pushed.ok) {
+        return pushed;
+      }
 
-    let didPruneLegacy = false;
-    let pruneError: string | undefined;
+      let didPruneLegacy = false;
+      let pruneError: string | undefined;
 
-    if (input.pruneLegacyRef && legacyRemoteRef && checkedOut.remoteUrl) {
-      const prunedLegacy = await runGitDir({
-        args: ["push", "origin", `:${legacyRemoteRef}`],
-      });
-      if (prunedLegacy.ok) {
-        didPruneLegacy = true;
-        if (legacyTrackingRef) {
-          await runGitDir({
-            args: ["update-ref", "-d", legacyTrackingRef],
-          });
+      if (input.pruneLegacyRef && legacyRemoteRef && checkedOut.remoteUrl) {
+        const prunedLegacy = await runGitDir({
+          args: ["push", "origin", `:${legacyRemoteRef}`],
+        });
+        if (prunedLegacy.ok) {
+          didPruneLegacy = true;
+          if (legacyTrackingRef) {
+            await runGitDir({
+              args: ["update-ref", "-d", legacyTrackingRef],
+            });
+          }
+        } else {
+          pruneError = `${prunedLegacy.stderr}\n${prunedLegacy.stdout}`.trim();
         }
-      } else {
-        pruneError = `${prunedLegacy.stderr}\n${prunedLegacy.stdout}`.trim();
       }
-    }
 
-    return {
-      ok: true,
-      didCommit: committed.didCommit,
-      didPush: pushed.didPush,
-      didPruneLegacy,
-      ...(pruneError ? { pruneError } : {}),
-    };
+      return {
+        ok: true,
+        didCommit: committed.didCommit,
+        didPush: pushed.didPush,
+        didPruneLegacy,
+        ...(pruneError ? { pruneError } : {}),
+      };
+    });
   };
 
   const appendEvents = async (input: {
@@ -1028,31 +1086,33 @@ export function createGitTicketsChannel(opts: {
   }): Promise<
     { readonly ok: true } | { readonly ok: false; readonly error: string }
   > => {
-    const checkedOut = await ensureCheckedOut();
-    if (!checkedOut.ok) {
-      return checkedOut;
-    }
+    return await withMutationLock(async () => {
+      const checkedOut = await ensureCheckedOut();
+      if (!checkedOut.ok) {
+        return checkedOut;
+      }
 
-    const wrote = await writeEvents({ events: input.events });
-    if (!wrote.ok) {
-      return wrote;
-    }
+      const wrote = await writeEvents({ events: input.events });
+      if (!wrote.ok) {
+        return wrote;
+      }
 
-    const committed = await commitAll("tickets: append events");
-    if (!committed.ok) {
-      return committed;
-    }
+      const committed = await commitAll("tickets: append events");
+      if (!committed.ok) {
+        return committed;
+      }
 
-    const pushed = await pushWithRetry({
-      remoteUrl: checkedOut.remoteUrl,
-      pushRef: checkedOut.pushRef,
-      pendingEvents: input.events,
-    });
-    if (!pushed.ok) {
-      return pushed;
-    }
+      const pushed = await pushWithRetry({
+        remoteUrl: checkedOut.remoteUrl,
+        pushRef: checkedOut.pushRef,
+        pendingEvents: input.events,
+      });
+      if (!pushed.ok) {
+        return pushed;
+      }
 
-    return { ok: true };
+      return { ok: true };
+    });
   };
 
   const sync = async (): Promise<
@@ -1065,36 +1125,38 @@ export function createGitTicketsChannel(opts: {
       }
     | { readonly ok: false; readonly error: string }
   > => {
-    const checkedOut = await ensureCheckedOut();
-    if (!checkedOut.ok) {
-      return checkedOut;
-    }
+    return await withMutationLock(async () => {
+      const checkedOut = await ensureCheckedOut();
+      if (!checkedOut.ok) {
+        return checkedOut;
+      }
 
-    const normalized = await normalizeLogs();
-    if (!normalized.ok) {
-      return normalized;
-    }
+      const normalized = await normalizeLogs();
+      if (!normalized.ok) {
+        return normalized;
+      }
 
-    const committed = await commitAll("tickets: sync");
-    if (!committed.ok) {
-      return committed;
-    }
+      const committed = await commitAll("tickets: sync");
+      if (!committed.ok) {
+        return committed;
+      }
 
-    const pushed = await pushWithRetry({
-      remoteUrl: checkedOut.remoteUrl,
-      pushRef: checkedOut.pushRef,
-    });
-    if (!pushed.ok) {
-      return pushed;
-    }
+      const pushed = await pushWithRetry({
+        remoteUrl: checkedOut.remoteUrl,
+        pushRef: checkedOut.pushRef,
+      });
+      if (!pushed.ok) {
+        return pushed;
+      }
 
-    return {
-      ok: true,
-      branch,
-      ...(checkedOut.remoteUrl ? { remote: remoteName } : {}),
-      didCommit: committed.didCommit,
-      didPush: pushed.didPush,
-    };
+      return {
+        ok: true,
+        branch,
+        ...(checkedOut.remoteUrl ? { remote: remoteName } : {}),
+        didCommit: committed.didCommit,
+        didPush: pushed.didPush,
+      };
+    });
   };
 
   return {
diff --git a/src/control-plane/extensions/tickets/util.ts b/src/control-plane/extensions/tickets/util.ts
index 1e4e3e981..5fc0ce825 100644
--- a/src/control-plane/extensions/tickets/util.ts
+++ b/src/control-plane/extensions/tickets/util.ts
@@ -1,4 +1,10 @@
+import { randomBytes } from "node:crypto";
+
 const DIGITS_ONLY_PATTERN = /^\d+$/;
+const LEGACY_TICKET_ID_PATTERN = /^T-(\d+)$/i;
+const RANDOM_TICKET_ID_PATTERN = /^T-([0-9A-Z]{10})$/i;
+const RANDOM_TICKET_ID_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const RANDOM_TICKET_ID_LENGTH = 10;
 
 export function unixSeconds(): number {
   return Math.floor(Date.now() / 1000);
@@ -18,17 +24,33 @@ export function formatTicketId(n: number): string {
 
 export function parseTicketNumber(ticketId: string): number | null {
   const trimmed = ticketId.trim();
-  if (!trimmed.startsWith("T-")) {
+  const match = LEGACY_TICKET_ID_PATTERN.exec(trimmed);
+  if (!match) {
     return null;
   }
-  const rest = trimmed.slice(2);
-  const n = Number(rest);
+  const n = Number(match[1]);
   if (!Number.isFinite(n)) {
     return null;
   }
   return Math.trunc(n);
 }
 
+export function generateTicketId(): string {
+  let suffix = "";
+  while (suffix.length < RANDOM_TICKET_ID_LENGTH) {
+    const chunk = randomBytes(RANDOM_TICKET_ID_LENGTH);
+    for (const byte of chunk) {
+      suffix +=
+        RANDOM_TICKET_ID_ALPHABET[byte % RANDOM_TICKET_ID_ALPHABET.length] ??
+        "";
+      if (suffix.length === RANDOM_TICKET_ID_LENGTH) {
+        break;
+      }
+    }
+  }
+  return `T-${suffix}`;
+}
+
 export function normalizeTicketRef(input: string): string | null {
   const trimmed = input.trim();
   if (!trimmed) {
@@ -41,7 +63,10 @@ export function normalizeTicketRef(input: string): string | null {
   const upper = raw.toUpperCase();
   if (upper.startsWith("T-")) {
     const n = parseTicketNumber(upper);
-    return n === null ? null : formatTicketId(n);
+    if (n !== null) {
+      return formatTicketId(n);
+    }
+    return RANDOM_TICKET_ID_PATTERN.test(upper) ? upper : null;
   }
   if (DIGITS_ONLY_PATTERN.test(raw)) {
     return formatTicketId(Number(raw));
@@ -49,6 +74,21 @@ export function normalizeTicketRef(input: string): string | null {
   return null;
 }
 
+export function compareTicketIds(left: string, right: string): number {
+  const leftNumber = parseTicketNumber(left);
+  const rightNumber = parseTicketNumber(right);
+  if (leftNumber !== null && rightNumber !== null) {
+    return leftNumber - rightNumber;
+  }
+  if (leftNumber !== null) {
+    return -1;
+  }
+  if (rightNumber !== null) {
+    return 1;
+  }
+  return left.localeCompare(right);
+}
+
 export function normalizeTicketRefs(inputs: readonly string[]): string[] {
   const seen = new Set<string>();
   const out: string[] = [];
@@ -60,14 +100,7 @@ export function normalizeTicketRefs(inputs: readonly string[]): string[] {
     seen.add(normalized);
     out.push(normalized);
   }
-  out.sort((a, b) => {
-    const an = parseTicketNumber(a) ?? 0;
-    const bn = parseTicketNumber(b) ?? 0;
-    if (an !== bn) {
-      return an - bn;
-    }
-    return a.localeCompare(b);
-  });
+  out.sort(compareTicketIds);
   return out;
 }
 
diff --git a/src/mcp/agent-docs.ts b/src/mcp/agent-docs.ts
index 11c2e4174..7ce05c40a 100644
--- a/src/mcp/agent-docs.ts
+++ b/src/mcp/agent-docs.ts
@@ -243,8 +243,8 @@ export function renderAgentDocsSnippet(): string {
     "",
     "Tickets (git-backed):",
     '- Create: `hack tickets create --title "..." --body-stdin`',
-    "- List/show: `hack tickets list`, `hack tickets show T-00001`",
-    "- Status/sync: `hack tickets status T-00001 in_progress`, `hack tickets sync`",
+    "- List/show: `hack tickets list`, `hack tickets show T-AB12CD34EF`",
+    "- Status/sync: `hack tickets status T-AB12CD34EF in_progress`, `hack tickets sync`",
     "",
     "Global infra:",
     "- Bootstrap once: `hack global install`",
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index 6a2724c38..ba984b6ed 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -929,7 +929,10 @@ function registerTools(opts: { readonly server: McpServer }): void {
           .string()
           .describe("Linear issue identifier (e.g. ENG-123)")
           .optional(),
-        ticket: z.string().describe("Hack ticket id (e.g. T-00001)").optional(),
+        ticket: z
+          .string()
+          .describe("Hack ticket id (e.g. T-AB12CD34EF)")
+          .optional(),
         ...linearCommonInput,
         projectId: z.string().describe("Linear project id override").optional(),
         teamId: z.string().describe("Linear team id override").optional(),
diff --git a/tests/tickets-extension.test.ts b/tests/tickets-extension.test.ts
index dc336da44..6300155c9 100644
--- a/tests/tickets-extension.test.ts
+++ b/tests/tickets-extension.test.ts
@@ -74,7 +74,34 @@ testIntegration(
     const createdJson = JSON.parse(created.stdout) as {
       ticket: { ticketId: string };
     };
-    expect(createdJson.ticket.ticketId).toMatch(/^T-\d{5}$/);
+    expect(createdJson.ticket.ticketId).toMatch(/^T-[0-9A-Z]{10}$/);
+
+    const updated = await runHack({
+      cwd: projectDir,
+      args: [
+        "tickets",
+        "update",
+        createdJson.ticket.ticketId,
+        "--title",
+        "Updated ticket title",
+        "--json",
+      ],
+    });
+    const updatedJson = JSON.parse(updated.stdout) as { ok: boolean };
+    expect(updatedJson.ok).toBe(true);
+
+    const status = await runHack({
+      cwd: projectDir,
+      args: [
+        "tickets",
+        "status",
+        createdJson.ticket.ticketId,
+        "in_progress",
+        "--json",
+      ],
+    });
+    const statusJson = JSON.parse(status.stdout) as { ok: boolean };
+    expect(statusJson.ok).toBe(true);
 
     const afterHead = (
       await run({
@@ -89,20 +116,23 @@ testIntegration(
       args: ["tickets", "list", "--json"],
     });
     const listJson = JSON.parse(listed.stdout) as {
-      tickets: { ticketId: string; title: string }[];
+      tickets: { ticketId: string; title: string; status: string }[];
     };
     expect(listJson.tickets.length).toBe(1);
-    expect(listJson.tickets[0]?.title).toBe("First ticket");
+    expect(listJson.tickets[0]?.title).toBe("Updated ticket title");
+    expect(listJson.tickets[0]?.status).toBe("in_progress");
 
     const shown = await runHack({
       cwd: projectDir,
       args: ["tickets", "show", createdJson.ticket.ticketId, "--json"],
     });
     const showJson = JSON.parse(shown.stdout) as {
-      ticket: { ticketId: string; title: string };
+      ticket: { ticketId: string; title: string; status: string };
       events: { type: string }[];
     };
     expect(showJson.ticket.ticketId).toBe(createdJson.ticket.ticketId);
+    expect(showJson.ticket.title).toBe("Updated ticket title");
+    expect(showJson.ticket.status).toBe("in_progress");
     expect(showJson.events.some((e) => e.type === "ticket.created")).toBe(true);
 
     const showRef = await runAllowFail({
diff --git a/tests/tickets-store.test.ts b/tests/tickets-store.test.ts
index 099e38e01..4b7e21365 100644
--- a/tests/tickets-store.test.ts
+++ b/tests/tickets-store.test.ts
@@ -10,6 +10,7 @@ import {
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { createTicketsStore } from "../src/control-plane/extensions/tickets/store.ts";
+import { createGitTicketsChannel } from "../src/control-plane/extensions/tickets/tickets-git-channel.ts";
 import { readControlPlaneConfig } from "../src/control-plane/sdk/config.ts";
 
 const originalGlobalConfigPath = process.env.HACK_GLOBAL_CONFIG_PATH;
@@ -340,6 +341,81 @@ test("tickets store recovers from a stale tickets bare repo index.lock", async (
   expect(tickets.map((ticket) => ticket.title)).toContain("Stale lock ticket");
 }, 20_000);
 
+test("tickets store creates non-sequential ids and keeps them unique under concurrent creates", async () => {
+  const projectRoot = await createTempGitProject({
+    prefix: "hack-cli-tickets-concurrent-create-",
+  });
+  const store = await createStore({ projectRoot });
+
+  const results = await Promise.all(
+    Array.from({ length: 16 }, (_value, index) =>
+      store.createTicket({
+        title: `Concurrent ticket ${index + 1}`,
+        owner: "hack",
+        source: "hack",
+        actor: `creator-${index}@hack`,
+      })
+    )
+  );
+
+  expect(results.every((result) => result.ok)).toBe(true);
+
+  const ticketIds = results.flatMap((result) =>
+    result.ok ? [result.ticket.ticketId] : []
+  );
+  expect(ticketIds).toHaveLength(16);
+  expect(new Set(ticketIds).size).toBe(ticketIds.length);
+
+  for (const ticketId of ticketIds) {
+    expect(ticketId).toMatch(/^T-[0-9A-Z]{10}$/);
+    expect(ticketId).not.toMatch(/^T-\d{5}$/);
+  }
+}, 20_000);
+
+test("tickets store continues to read and update legacy sequential ids", async () => {
+  const projectRoot = await createTempGitProject({
+    prefix: "hack-cli-tickets-legacy-id-",
+  });
+  const store = await createStore({ projectRoot });
+  const configResult = await readControlPlaneConfig({
+    projectDir: join(projectRoot, ".hack"),
+  });
+  const git = createGitTicketsChannel({
+    projectRoot,
+    config: configResult.config.tickets.git,
+    logger,
+  });
+
+  const legacyEvent = {
+    actor: "creator@hack",
+    eventId: "legacy-ticket-created",
+    payload: {
+      owner: "hack",
+      source: "hack",
+      title: "Legacy sequential ticket",
+    },
+    ticketId: "T-00001",
+    ts: 1_762_000_000,
+    tsIso: "2025-11-04T00:00:00.000Z",
+    type: "ticket.created",
+  };
+  const appended = await git.appendEvents({ events: [legacyEvent] });
+  expect(appended.ok).toBe(true);
+
+  const ticket = await store.getTicket({ ticketId: "T-00001" });
+  expect(ticket?.title).toBe("Legacy sequential ticket");
+
+  const updated = await store.updateTicket({
+    ticketId: "T-00001",
+    title: "Legacy sequential ticket updated",
+    actor: "updater@hack",
+  });
+  expect(updated.ok).toBe(true);
+
+  const updatedTicket = await store.getTicket({ ticketId: "T-00001" });
+  expect(updatedTicket?.title).toBe("Legacy sequential ticket updated");
+}, 20_000);
+
 async function createStore(opts: { readonly projectRoot: string }) {
   const configResult = await readControlPlaneConfig({
     projectDir: join(opts.projectRoot, ".hack"),
diff --git a/tests/tickets-util.test.ts b/tests/tickets-util.test.ts
new file mode 100644
index 000000000..3565cb488
--- /dev/null
+++ b/tests/tickets-util.test.ts
@@ -0,0 +1,27 @@
+import { expect, test } from "bun:test";
+
+import {
+  normalizeTicketRef,
+  normalizeTicketRefs,
+} from "../src/control-plane/extensions/tickets/util.ts";
+
+test("normalizeTicketRef preserves legacy numeric shorthand", () => {
+  expect(normalizeTicketRef("7")).toBe("T-00007");
+  expect(normalizeTicketRef("#42")).toBe("T-00042");
+  expect(normalizeTicketRef("t-00009")).toBe("T-00009");
+});
+
+test("normalizeTicketRef canonicalizes new-style ids with a T- prefix", () => {
+  expect(normalizeTicketRef("t-ab12cd34ef")).toBe("T-AB12CD34EF");
+  expect(normalizeTicketRef("T-AB12CD34EF")).toBe("T-AB12CD34EF");
+});
+
+test("normalizeTicketRef rejects unprefixed non-legacy ids", () => {
+  expect(normalizeTicketRef("ab12cd34ef")).toBeNull();
+});
+
+test("normalizeTicketRefs dedupes mixed legacy and new-style ids", () => {
+  expect(
+    normalizeTicketRefs(["7", "T-00007", "t-ab12cd34ef", "T-AB12CD34EF", "#7"])
+  ).toEqual(["T-00007", "T-AB12CD34EF"]);
+});

From 25aebd7f1c0bdad59761e27afee55c0ce824f233 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 15 Mar 2026 16:42:54 +0000
Subject: [PATCH 105/134] Change hack ticket ids to random IDs

---
 src/control-plane/extensions/tickets/store.ts | 139 +++++++++------
 .../extensions/tickets/tickets-git-channel.ts |  63 ++++++-
 src/control-plane/extensions/tickets/util.ts  |  40 +++--
 tests/tickets-id-generation.test.ts           | 162 ++++++++++++++++++
 tests/tickets-util-id-generation.test.ts      |  10 ++
 5 files changed, 349 insertions(+), 65 deletions(-)
 create mode 100644 tests/tickets-id-generation.test.ts
 create mode 100644 tests/tickets-util-id-generation.test.ts

diff --git a/src/control-plane/extensions/tickets/store.ts b/src/control-plane/extensions/tickets/store.ts
index c5a75fa6e..299dfc257 100644
--- a/src/control-plane/extensions/tickets/store.ts
+++ b/src/control-plane/extensions/tickets/store.ts
@@ -157,11 +157,14 @@ type MaterializedTicketState = {
   readonly conflictsByTicket: Map<string, TicketSyncConflict[]>;
 };
 
+const MAX_TICKET_ID_ALLOCATION_ATTEMPTS = 32;
+
 export function createTicketsStore(opts: {
   readonly projectRoot: string;
   readonly projectId?: string;
   readonly projectName?: string;
   readonly controlPlaneConfig: ControlPlaneConfig;
+  readonly generateTicketId?: () => string;
   readonly logger: {
     info: (input: { message: string }) => void;
     warn: (input: { message: string }) => void;
@@ -300,6 +303,7 @@ export function createTicketsStore(opts: {
     config: opts.controlPlaneConfig.tickets.git,
     logger: opts.logger,
   });
+  const allocateTicketId = opts.generateTicketId ?? generateTicketId;
   let eventSequence = 0;
 
   const resolveActor = (override?: string): string => {
@@ -336,7 +340,13 @@ export function createTicketsStore(opts: {
 
   const readAllEvents = async (): Promise<readonly TicketEvent[]> => {
     const root = await git.ensureCheckedOut();
-    const eventsDir = resolve(root, ".hack/tickets/events");
+    return await readEventsFromRoot({ root });
+  };
+
+  const readEventsFromRoot = async (opts: {
+    readonly root: string;
+  }): Promise<readonly TicketEvent[]> => {
+    const eventsDir = resolve(opts.root, ".hack/tickets/events");
 
     let entries: string[] = [];
     try {
@@ -461,7 +471,6 @@ export function createTicketsStore(opts: {
 
   return {
     createTicket: async (input) => {
-      const ticketId = generateTicketId();
       const dependsOn = normalizeTicketRefs(input.dependsOn ?? []);
       const blocks = normalizeTicketRefs(input.blocks ?? []);
       const owner = normalizeOwnerOrSource({
@@ -497,61 +506,89 @@ export function createTicketsStore(opts: {
       const externalTeamId = normalizeOptionalMetadataString({
         value: input.externalTeamId,
       });
-      const event = buildEvent({
-        ticketId,
-        type: "ticket.created",
-        payload: {
-          title: input.title,
-          ...(input.body ? { body: input.body } : {}),
-          ...(dependsOn.length > 0 ? { dependsOn } : {}),
-          ...(blocks.length > 0 ? { blocks } : {}),
-          owner,
-          source,
-          ...(assignee ? { assignee } : {}),
-          ...(tags.length > 0 ? { tags } : {}),
-          ...(externalSystem ? { externalSystem } : {}),
-          ...(externalId ? { externalId } : {}),
-          ...(externalKey ? { externalKey } : {}),
-          ...(externalUrl ? { externalUrl } : {}),
-          ...(externalProjectId ? { externalProjectId } : {}),
-          ...(externalProjectName ? { externalProjectName } : {}),
-          ...(externalTeamId ? { externalTeamId } : {}),
-          status: "open",
+      const wrote = await git.appendPreparedEvents({
+        prepare: async (root) => {
+          const events = await readEventsFromRoot({ root });
+          const snapshot = materializeSnapshotFromEvents({ events });
+
+          let ticketId: string | null = null;
+          for (
+            let attempt = 0;
+            attempt < MAX_TICKET_ID_ALLOCATION_ATTEMPTS;
+            attempt += 1
+          ) {
+            const candidate = allocateTicketId();
+            if (!snapshot.tickets.has(candidate)) {
+              ticketId = candidate;
+              break;
+            }
+          }
+
+          if (!ticketId) {
+            return {
+              ok: false,
+              error: "Failed to allocate a unique ticket id.",
+            };
+          }
+
+          const event = buildEvent({
+            ticketId,
+            type: "ticket.created",
+            payload: {
+              title: input.title,
+              ...(input.body ? { body: input.body } : {}),
+              ...(dependsOn.length > 0 ? { dependsOn } : {}),
+              ...(blocks.length > 0 ? { blocks } : {}),
+              owner,
+              source,
+              ...(assignee ? { assignee } : {}),
+              ...(tags.length > 0 ? { tags } : {}),
+              ...(externalSystem ? { externalSystem } : {}),
+              ...(externalId ? { externalId } : {}),
+              ...(externalKey ? { externalKey } : {}),
+              ...(externalUrl ? { externalUrl } : {}),
+              ...(externalProjectId ? { externalProjectId } : {}),
+              ...(externalProjectName ? { externalProjectName } : {}),
+              ...(externalTeamId ? { externalTeamId } : {}),
+              status: "open",
+            },
+            actor: input.actor,
+          });
+
+          return {
+            ok: true,
+            events: [event],
+            result: {
+              ticketId,
+              title: input.title,
+              ...(input.body ? { body: input.body } : {}),
+              status: "open" as const,
+              createdAt: event.tsIso,
+              updatedAt: event.tsIso,
+              dependsOn,
+              blocks,
+              owner,
+              source,
+              ...(assignee ? { assignee } : {}),
+              tags,
+              ...(externalSystem ? { externalSystem } : {}),
+              ...(externalId ? { externalId } : {}),
+              ...(externalKey ? { externalKey } : {}),
+              ...(externalUrl ? { externalUrl } : {}),
+              ...(externalProjectId ? { externalProjectId } : {}),
+              ...(externalProjectName ? { externalProjectName } : {}),
+              ...(externalTeamId ? { externalTeamId } : {}),
+              ...(opts.projectId ? { projectId: opts.projectId } : {}),
+              ...(opts.projectName ? { projectName: opts.projectName } : {}),
+            } satisfies TicketSummary,
+          };
         },
-        actor: input.actor,
       });
-
-      const wrote = await git.appendEvents({ events: [event] });
       if (!wrote.ok) {
         return wrote;
       }
 
-      return {
-        ok: true,
-        ticket: {
-          ticketId,
-          title: input.title,
-          ...(input.body ? { body: input.body } : {}),
-          status: "open",
-          createdAt: event.tsIso,
-          updatedAt: event.tsIso,
-          dependsOn,
-          blocks,
-          owner,
-          source,
-          ...(assignee ? { assignee } : {}),
-          tags,
-          ...(externalSystem ? { externalSystem } : {}),
-          ...(externalId ? { externalId } : {}),
-          ...(externalKey ? { externalKey } : {}),
-          ...(externalUrl ? { externalUrl } : {}),
-          ...(externalProjectId ? { externalProjectId } : {}),
-          ...(externalProjectName ? { externalProjectName } : {}),
-          ...(externalTeamId ? { externalTeamId } : {}),
-          ...(opts.projectId ? { projectId: opts.projectId } : {}),
-          ...(opts.projectName ? { projectName: opts.projectName } : {}),
-        },
-      };
+      return { ok: true, ticket: wrote.result };
     },
 
     updateTicket: async (input) => {
diff --git a/src/control-plane/extensions/tickets/tickets-git-channel.ts b/src/control-plane/extensions/tickets/tickets-git-channel.ts
index d78ae2ed2..2ca3236ce 100644
--- a/src/control-plane/extensions/tickets/tickets-git-channel.ts
+++ b/src/control-plane/extensions/tickets/tickets-git-channel.ts
@@ -9,7 +9,7 @@ const REFS_HEADS_PREFIX_PATTERN = /^refs\/heads\//;
 const REFS_PREFIX_PATTERN = /^refs\//;
 const MUTATION_LOCK_RETRY_MS = 100;
 const MUTATION_LOCK_STALE_MS = 30_000;
-const MUTATION_LOCK_TIMEOUT_MS = 10_000;
+const MUTATION_LOCK_TIMEOUT_MS = 30_000;
 
 export type TicketsGitChannel = {
   readonly ensureCheckedOut: () => Promise<string>;
@@ -18,6 +18,19 @@ export type TicketsGitChannel = {
   }) => Promise<
     { readonly ok: true } | { readonly ok: false; readonly error: string }
   >;
+  readonly appendPreparedEvents: <T>(input: {
+    readonly prepare: (root: string) => Promise<
+      | {
+          readonly ok: true;
+          readonly events: readonly Record<string, unknown>[];
+          readonly result: T;
+        }
+      | { readonly ok: false; readonly error: string }
+    >;
+  }) => Promise<
+    | { readonly ok: true; readonly result: T }
+    | { readonly ok: false; readonly error: string }
+  >;
   readonly inspect: () => Promise<TicketsGitInspectResult>;
   readonly repair: (input: {
     readonly pruneLegacyRef: boolean;
@@ -1115,6 +1128,53 @@ export function createGitTicketsChannel(opts: {
     });
   };
 
+  const appendPreparedEvents = async <T>(input: {
+    readonly prepare: (root: string) => Promise<
+      | {
+          readonly ok: true;
+          readonly events: readonly Record<string, unknown>[];
+          readonly result: T;
+        }
+      | { readonly ok: false; readonly error: string }
+    >;
+  }): Promise<
+    | { readonly ok: true; readonly result: T }
+    | { readonly ok: false; readonly error: string }
+  > => {
+    return await withMutationLock(async () => {
+      const checkedOut = await ensureCheckedOut();
+      if (!checkedOut.ok) {
+        return checkedOut;
+      }
+
+      const prepared = await input.prepare(worktreeDir);
+      if (!prepared.ok) {
+        return prepared;
+      }
+
+      const wrote = await writeEvents({ events: prepared.events });
+      if (!wrote.ok) {
+        return wrote;
+      }
+
+      const committed = await commitAll("tickets: append events");
+      if (!committed.ok) {
+        return committed;
+      }
+
+      const pushed = await pushWithRetry({
+        remoteUrl: checkedOut.remoteUrl,
+        pushRef: checkedOut.pushRef,
+        pendingEvents: prepared.events,
+      });
+      if (!pushed.ok) {
+        return pushed;
+      }
+
+      return { ok: true, result: prepared.result };
+    });
+  };
+
   const sync = async (): Promise<
     | {
         readonly ok: true;
@@ -1168,6 +1228,7 @@ export function createGitTicketsChannel(opts: {
       return worktreeDir;
     },
     appendEvents,
+    appendPreparedEvents,
     inspect,
     repair,
     sync,
diff --git a/src/control-plane/extensions/tickets/util.ts b/src/control-plane/extensions/tickets/util.ts
index 5fc0ce825..7efae8cac 100644
--- a/src/control-plane/extensions/tickets/util.ts
+++ b/src/control-plane/extensions/tickets/util.ts
@@ -4,6 +4,7 @@ const DIGITS_ONLY_PATTERN = /^\d+$/;
 const LEGACY_TICKET_ID_PATTERN = /^T-(\d+)$/i;
 const RANDOM_TICKET_ID_PATTERN = /^T-([0-9A-Z]{10})$/i;
 const RANDOM_TICKET_ID_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const RANDOM_TICKET_ID_PREFIX_ALPHABET = "ABCDEFGHJKMNPQRSTVWXYZ";
 const RANDOM_TICKET_ID_LENGTH = 10;
 
 export function unixSeconds(): number {
@@ -36,19 +37,15 @@ export function parseTicketNumber(ticketId: string): number | null {
 }
 
 export function generateTicketId(): string {
-  let suffix = "";
-  while (suffix.length < RANDOM_TICKET_ID_LENGTH) {
-    const chunk = randomBytes(RANDOM_TICKET_ID_LENGTH);
-    for (const byte of chunk) {
-      suffix +=
-        RANDOM_TICKET_ID_ALPHABET[byte % RANDOM_TICKET_ID_ALPHABET.length] ??
-        "";
-      if (suffix.length === RANDOM_TICKET_ID_LENGTH) {
-        break;
-      }
-    }
-  }
-  return `T-${suffix}`;
+  const prefix = generateRandomTicketIdChunk({
+    alphabet: RANDOM_TICKET_ID_PREFIX_ALPHABET,
+    length: 1,
+  });
+  const suffix = generateRandomTicketIdChunk({
+    alphabet: RANDOM_TICKET_ID_ALPHABET,
+    length: RANDOM_TICKET_ID_LENGTH - prefix.length,
+  });
+  return `T-${prefix}${suffix}`;
 }
 
 export function normalizeTicketRef(input: string): string | null {
@@ -122,3 +119,20 @@ function stableSort(value: unknown): unknown {
   }
   return value;
 }
+
+function generateRandomTicketIdChunk(opts: {
+  readonly alphabet: string;
+  readonly length: number;
+}): string {
+  let chunkText = "";
+  while (chunkText.length < opts.length) {
+    const chunk = randomBytes(opts.length);
+    for (const byte of chunk) {
+      chunkText += opts.alphabet[byte % opts.alphabet.length] ?? "";
+      if (chunkText.length === opts.length) {
+        break;
+      }
+    }
+  }
+  return chunkText;
+}
diff --git a/tests/tickets-id-generation.test.ts b/tests/tickets-id-generation.test.ts
new file mode 100644
index 000000000..02a81aee9
--- /dev/null
+++ b/tests/tickets-id-generation.test.ts
@@ -0,0 +1,162 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import {
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { createTicketsStore } from "../src/control-plane/extensions/tickets/store.ts";
+import { readControlPlaneConfig } from "../src/control-plane/sdk/config.ts";
+
+const originalGlobalConfigPath = process.env.HACK_GLOBAL_CONFIG_PATH;
+const generatedTicketIds: string[] = [];
+const logger = {
+  info: (_input: { message: string }) => {},
+  warn: (_input: { message: string }) => {},
+};
+
+let tempGlobalConfigPath: string | null = null;
+let tempRoots: string[] = [];
+
+beforeEach(() => {
+  generatedTicketIds.length = 0;
+  tempGlobalConfigPath = join(
+    tmpdir(),
+    `hack-global-config-${Date.now()}-${Math.random()}.json`
+  );
+  process.env.HACK_GLOBAL_CONFIG_PATH = tempGlobalConfigPath;
+});
+
+afterEach(async () => {
+  for (const root of tempRoots) {
+    await rm(root, { recursive: true, force: true });
+  }
+  tempRoots = [];
+
+  if (tempGlobalConfigPath) {
+    await rm(tempGlobalConfigPath, { force: true });
+    tempGlobalConfigPath = null;
+  }
+
+  if (originalGlobalConfigPath === undefined) {
+    process.env.HACK_GLOBAL_CONFIG_PATH = undefined;
+  } else {
+    process.env.HACK_GLOBAL_CONFIG_PATH = originalGlobalConfigPath;
+  }
+});
+
+test("tickets store retries generated ids that collide during concurrent creates", async () => {
+  generatedTicketIds.push("T-AAAAAAAAAA", "T-AAAAAAAAAA", "T-BBBBBBBBBB");
+
+  const projectRoot = await createTempGitProject({
+    prefix: "hack-cli-tickets-id-collision-",
+  });
+  const store = await createStore({ projectRoot });
+
+  const results = await Promise.all([
+    store.createTicket({
+      title: "First concurrent ticket",
+      owner: "hack",
+      source: "hack",
+      actor: "creator-1@hack",
+    }),
+    store.createTicket({
+      title: "Second concurrent ticket",
+      owner: "hack",
+      source: "hack",
+      actor: "creator-2@hack",
+    }),
+  ]);
+
+  expect(results.every((result) => result.ok)).toBe(true);
+
+  const ticketIds = results.flatMap((result) =>
+    result.ok ? [result.ticket.ticketId] : []
+  );
+  expect(ticketIds).toHaveLength(2);
+  expect(new Set(ticketIds)).toEqual(new Set(["T-AAAAAAAAAA", "T-BBBBBBBBBB"]));
+
+  const tickets = await store.listTickets();
+  expect(tickets.map((ticket) => ticket.ticketId)).toEqual([
+    "T-AAAAAAAAAA",
+    "T-BBBBBBBBBB",
+  ]);
+}, 20_000);
+
+async function createStore(opts: { readonly projectRoot: string }) {
+  const configResult = await readControlPlaneConfig({
+    projectDir: join(opts.projectRoot, ".hack"),
+  });
+  return createTicketsStore({
+    projectRoot: opts.projectRoot,
+    controlPlaneConfig: configResult.config,
+    generateTicketId: () => generatedTicketIds.shift() ?? "T-ZZZZZZZZZZ",
+    logger,
+  });
+}
+
+async function createTempGitProject(opts: {
+  readonly prefix: string;
+}): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), opts.prefix));
+  tempRoots.push(root);
+  await copyDir({
+    from: resolve(import.meta.dir, "../examples/tickets"),
+    to: root,
+  });
+  await run({ cwd: root, cmd: ["git", "init"] });
+  await run({ cwd: root, cmd: ["git", "config", "user.email", "tests@hack"] });
+  await run({
+    cwd: root,
+    cmd: ["git", "config", "user.name", "hack-cli-tests"],
+  });
+  await run({ cwd: root, cmd: ["git", "add", "-A"] });
+  await run({ cwd: root, cmd: ["git", "commit", "-m", "init"] });
+  return root;
+}
+
+async function run(opts: {
+  readonly cwd: string;
+  readonly cmd: readonly string[];
+}) {
+  const proc = Bun.spawn([...opts.cmd], {
+    cwd: opts.cwd,
+    env: process.env,
+    stderr: "pipe",
+    stdin: "ignore",
+    stdout: "pipe",
+  });
+
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    throw new Error(
+      `Command failed (${exitCode}): ${opts.cmd.join(" ")}\n${stderr || stdout}`
+    );
+  }
+}
+
+async function copyDir(opts: {
+  readonly from: string;
+  readonly to: string;
+}): Promise<void> {
+  await mkdir(opts.to, { recursive: true });
+  const entries = await readdir(opts.from, { withFileTypes: true });
+  for (const entry of entries) {
+    const fromPath = join(opts.from, entry.name);
+    const toPath = join(opts.to, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir({ from: fromPath, to: toPath });
+    } else if (entry.isFile()) {
+      const data = await readFile(fromPath);
+      await writeFile(toPath, data);
+    }
+  }
+}
diff --git a/tests/tickets-util-id-generation.test.ts b/tests/tickets-util-id-generation.test.ts
new file mode 100644
index 000000000..0b45258c4
--- /dev/null
+++ b/tests/tickets-util-id-generation.test.ts
@@ -0,0 +1,10 @@
+import { expect, test } from "bun:test";
+
+import { generateTicketId } from "../src/control-plane/extensions/tickets/util.ts";
+
+test("generateTicketId never emits an all-digit suffix", () => {
+  const ticketId = generateTicketId();
+
+  expect(ticketId).toMatch(/^T-[0-9A-Z]{10}$/);
+  expect(ticketId).not.toMatch(/^T-\d{10}$/);
+});

From e06fbd4523fb7ed11eb1ff53b14e3091e2a4abdb Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 15:10:02 +0000
Subject: [PATCH 106/134] fix(tickets): retry prepared event pushes safely

---
 .../extensions/tickets/tickets-git-channel.ts | 161 ++++++++++++++---
 tests/tickets-git-channel.test.ts             | 167 +++++++++++++++++-
 tests/tickets-id-generation.test.ts           |  73 +++++++-
 3 files changed, 372 insertions(+), 29 deletions(-)

diff --git a/src/control-plane/extensions/tickets/tickets-git-channel.ts b/src/control-plane/extensions/tickets/tickets-git-channel.ts
index 2ca3236ce..d3b8fd22d 100644
--- a/src/control-plane/extensions/tickets/tickets-git-channel.ts
+++ b/src/control-plane/extensions/tickets/tickets-git-channel.ts
@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { mkdir, open, readdir, rm, stat, unlink } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
@@ -7,9 +8,10 @@ import { stableStringify } from "./util.ts";
 
 const REFS_HEADS_PREFIX_PATTERN = /^refs\/heads\//;
 const REFS_PREFIX_PATTERN = /^refs\//;
-const MUTATION_LOCK_RETRY_MS = 100;
-const MUTATION_LOCK_STALE_MS = 30_000;
-const MUTATION_LOCK_TIMEOUT_MS = 30_000;
+const DEFAULT_MUTATION_LOCK_HEARTBEAT_MS = 1000;
+const DEFAULT_MUTATION_LOCK_RETRY_MS = 100;
+const DEFAULT_MUTATION_LOCK_STALE_MS = 30_000;
+const DEFAULT_MUTATION_LOCK_TIMEOUT_MS = 30_000;
 
 export type TicketsGitChannel = {
   readonly ensureCheckedOut: () => Promise<string>;
@@ -82,6 +84,12 @@ export function createGitTicketsChannel(opts: {
     info: (input: { message: string }) => void;
     warn: (input: { message: string }) => void;
   };
+  readonly testOverrides?: {
+    readonly mutationLockHeartbeatMs?: number;
+    readonly mutationLockRetryMs?: number;
+    readonly mutationLockStaleMs?: number;
+    readonly mutationLockTimeoutMs?: number;
+  };
 }): TicketsGitChannel {
   const ticketsDir = resolve(opts.projectRoot, ".hack/tickets");
   const gitDir = resolve(ticketsDir, "git");
@@ -102,6 +110,16 @@ export function createGitTicketsChannel(opts: {
   const remoteName = gitEnabled ? (opts.config.remote ?? "origin").trim() : "";
   const bareIndexLockPath = resolve(bareDir, "index.lock");
   const mutationLockPath = resolve(gitDir, ".mutation.lock");
+  const mutationLockHeartbeatMs =
+    opts.testOverrides?.mutationLockHeartbeatMs ??
+    DEFAULT_MUTATION_LOCK_HEARTBEAT_MS;
+  const mutationLockRetryMs =
+    opts.testOverrides?.mutationLockRetryMs ?? DEFAULT_MUTATION_LOCK_RETRY_MS;
+  const mutationLockStaleMs =
+    opts.testOverrides?.mutationLockStaleMs ?? DEFAULT_MUTATION_LOCK_STALE_MS;
+  const mutationLockTimeoutMs =
+    opts.testOverrides?.mutationLockTimeoutMs ??
+    DEFAULT_MUTATION_LOCK_TIMEOUT_MS;
 
   const resolvePushRefForCheckout = (input: {
     readonly checkoutRef: string;
@@ -183,53 +201,126 @@ export function createGitTicketsChannel(opts: {
     await mkdir(worktreeDir, { recursive: true });
   };
 
+  type MutationLockHandle = {
+    readonly ownerToken: string;
+    readonly heartbeatTimer: ReturnType<typeof setInterval>;
+  };
+
   const withMutationLock = async <T>(fn: () => Promise<T>): Promise<T> => {
-    await acquireMutationLock();
+    const lockHandle = await acquireMutationLock();
     try {
       return await fn();
     } finally {
-      await releaseMutationLock();
+      await releaseMutationLock(lockHandle);
     }
   };
 
-  const acquireMutationLock = async (): Promise<void> => {
-    await mkdir(dirname(mutationLockPath), { recursive: true });
-    const start = Date.now();
+  const readMutationLockOwner = async (): Promise<string | null> => {
+    const ownerToken = (
+      await Bun.file(mutationLockPath)
+        .text()
+        .catch(() => "")
+    )
+      .split("\n")[0]
+      ?.trim();
+    return ownerToken ? ownerToken : null;
+  };
 
-    while (true) {
+  const writeMutationLockOwner = async (ownerToken: string): Promise<void> => {
+    await Bun.write(mutationLockPath, `${ownerToken}\n`);
+  };
+
+  const refreshMutationLock = async (
+    input: Pick<MutationLockHandle, "ownerToken">
+  ): Promise<void> => {
+    if ((await readMutationLockOwner()) !== input.ownerToken) {
+      return;
+    }
+    await writeMutationLockOwner(input.ownerToken);
+  };
+
+  const clearStaleMutationLock = async (): Promise<void> => {
+    const ownerToken = await readMutationLockOwner();
+    if (!ownerToken) {
+      await unlink(mutationLockPath).catch(() => undefined);
+      return;
+    }
+    if (!(await isMutationLockStale())) {
+      return;
+    }
+    if ((await readMutationLockOwner()) !== ownerToken) {
+      return;
+    }
+    await unlink(mutationLockPath).catch(() => undefined);
+  };
+
+  const startMutationLockHeartbeat = (
+    ownerToken: string
+  ): MutationLockHandle["heartbeatTimer"] => {
+    const heartbeatTimer = setInterval(() => {
+      void refreshMutationLock({ ownerToken });
+    }, mutationLockHeartbeatMs);
+    heartbeatTimer.unref?.();
+    return heartbeatTimer;
+  };
+
+  const tryAcquireMutationLock =
+    async (): Promise<MutationLockHandle | null> => {
+      const ownerToken = randomUUID();
       try {
         const file = await open(mutationLockPath, "wx");
-        await file.writeFile(`${process.pid}\n`);
+        await file.writeFile(`${ownerToken}\n`);
         await file.close();
-        return;
+        return {
+          ownerToken,
+          heartbeatTimer: startMutationLockHeartbeat(ownerToken),
+        };
       } catch (error: unknown) {
         const code =
           typeof error === "object" && error !== null && "code" in error
             ? (error as { code?: string }).code
             : undefined;
-        if (code !== "EEXIST") {
-          throw error;
-        }
-        if (await isMutationLockStale()) {
-          await unlink(mutationLockPath).catch(() => undefined);
-          continue;
-        }
-        if (Date.now() - start > MUTATION_LOCK_TIMEOUT_MS) {
-          throw new Error("Timed out waiting for tickets git mutation lock");
+        if (code === "EEXIST") {
+          return null;
         }
-        await Bun.sleep(MUTATION_LOCK_RETRY_MS);
+        throw error;
       }
+    };
+
+  const acquireMutationLock = async (): Promise<MutationLockHandle> => {
+    await mkdir(dirname(mutationLockPath), { recursive: true });
+    const start = Date.now();
+
+    while (true) {
+      const lockHandle = await tryAcquireMutationLock();
+      if (lockHandle) {
+        return lockHandle;
+      }
+      if (await isMutationLockStale()) {
+        await clearStaleMutationLock();
+        continue;
+      }
+      if (Date.now() - start > mutationLockTimeoutMs) {
+        throw new Error("Timed out waiting for tickets git mutation lock");
+      }
+      await Bun.sleep(mutationLockRetryMs);
     }
   };
 
-  const releaseMutationLock = async (): Promise<void> => {
+  const releaseMutationLock = async (
+    input: MutationLockHandle
+  ): Promise<void> => {
+    clearInterval(input.heartbeatTimer);
+    if ((await readMutationLockOwner()) !== input.ownerToken) {
+      return;
+    }
     await unlink(mutationLockPath).catch(() => undefined);
   };
 
   const isMutationLockStale = async (): Promise<boolean> => {
     try {
       const info = await stat(mutationLockPath);
-      return Date.now() - info.mtimeMs > MUTATION_LOCK_STALE_MS;
+      return Date.now() - info.mtimeMs > mutationLockStaleMs;
     } catch {
       return false;
     }
@@ -826,6 +917,9 @@ export function createGitTicketsChannel(opts: {
     readonly remoteUrl: string | null;
     readonly pushRef: string;
     readonly pendingEvents?: readonly Record<string, unknown>[];
+    readonly replayPendingEvents?: () => Promise<
+      { readonly ok: true } | { readonly ok: false; readonly error: string }
+    >;
   }): Promise<
     | { readonly ok: true; readonly didPush: boolean }
     | { readonly ok: false; readonly error: string }
@@ -858,7 +952,12 @@ export function createGitTicketsChannel(opts: {
       return checkedOut;
     }
 
-    if (input.pendingEvents && input.pendingEvents.length > 0) {
+    if (input.replayPendingEvents) {
+      const replayed = await input.replayPendingEvents();
+      if (!replayed.ok) {
+        return replayed;
+      }
+    } else if (input.pendingEvents && input.pendingEvents.length > 0) {
       const wrote = await writeEvents({ events: input.pendingEvents });
       if (!wrote.ok) {
         return wrote;
@@ -1152,6 +1251,8 @@ export function createGitTicketsChannel(opts: {
         return prepared;
       }
 
+      let preparedResult = prepared.result;
+
       const wrote = await writeEvents({ events: prepared.events });
       if (!wrote.ok) {
         return wrote;
@@ -1165,13 +1266,20 @@ export function createGitTicketsChannel(opts: {
       const pushed = await pushWithRetry({
         remoteUrl: checkedOut.remoteUrl,
         pushRef: checkedOut.pushRef,
-        pendingEvents: prepared.events,
+        replayPendingEvents: async () => {
+          const replayed = await input.prepare(worktreeDir);
+          if (!replayed.ok) {
+            return replayed;
+          }
+          preparedResult = replayed.result;
+          return await writeEvents({ events: replayed.events });
+        },
       });
       if (!pushed.ok) {
         return pushed;
       }
 
-      return { ok: true, result: prepared.result };
+      return { ok: true, result: preparedResult };
     });
   };
 
@@ -1401,6 +1509,7 @@ function isGitIndexLockError(message: string): boolean {
 }
 
 export const __testOnly = {
+  createGitTicketsChannel,
   mergeTicketEventLogs,
   resolvePushRefForCheckoutRef,
 };
diff --git a/tests/tickets-git-channel.test.ts b/tests/tickets-git-channel.test.ts
index c93f8419f..1d0ced949 100644
--- a/tests/tickets-git-channel.test.ts
+++ b/tests/tickets-git-channel.test.ts
@@ -1,7 +1,26 @@
-import { expect, test } from "bun:test";
+import { afterEach, expect, test } from "bun:test";
+import {
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 
 import { __testOnly } from "../src/control-plane/extensions/tickets/tickets-git-channel.ts";
 
+const tempRoots: string[] = [];
+
+afterEach(async () => {
+  for (const root of tempRoots) {
+    await rm(root, { recursive: true, force: true });
+  }
+  tempRoots.length = 0;
+});
+
 test("mergeTicketEventLogs dedupes by event id and preserves chronological order", () => {
   const merged = __testOnly.mergeTicketEventLogs({
     existing: [
@@ -73,3 +92,149 @@ test("resolvePushRefForCheckoutRef keeps hidden ref when checkout came from hidd
 
   expect(pushRef).toBe("refs/hack/tickets");
 });
+
+test("mutation lock heartbeat prevents overlapping prepared mutations past stale threshold", async () => {
+  const projectRoot = await createTempGitProject({
+    prefix: "hack-cli-tickets-git-lock-",
+  });
+  const channel = __testOnly.createGitTicketsChannel({
+    projectRoot,
+    config: {
+      enabled: true,
+      branch: "hack/tickets",
+      refMode: "hidden",
+      remote: "",
+    },
+    logger: {
+      info: (_input: { message: string }) => {},
+      warn: (_input: { message: string }) => {},
+    },
+    testOverrides: {
+      mutationLockRetryMs: 5,
+      mutationLockStaleMs: 40,
+      mutationLockTimeoutMs: 2000,
+      mutationLockHeartbeatMs: 10,
+    },
+  });
+
+  let activeCount = 0;
+  let maxActiveCount = 0;
+
+  const firstMutation = channel.appendPreparedEvents({
+    prepare: async () => {
+      activeCount += 1;
+      maxActiveCount = Math.max(maxActiveCount, activeCount);
+      await Bun.sleep(120);
+      activeCount -= 1;
+      return {
+        ok: true,
+        events: [
+          {
+            actor: "creator-1@hack",
+            eventId: "event-1",
+            payload: { title: "first" },
+            ticketId: "T-AAAAAAA111",
+            ts: 1,
+            tsIso: "2025-11-04T00:00:00.000Z",
+            type: "ticket.created",
+          },
+        ],
+        result: "first",
+      } as const;
+    },
+  });
+
+  await Bun.sleep(60);
+
+  const secondMutation = channel.appendPreparedEvents({
+    prepare: async () => {
+      activeCount += 1;
+      maxActiveCount = Math.max(maxActiveCount, activeCount);
+      activeCount -= 1;
+      return {
+        ok: true,
+        events: [
+          {
+            actor: "creator-2@hack",
+            eventId: "event-2",
+            payload: { title: "second" },
+            ticketId: "T-BBBBBBB222",
+            ts: 2,
+            tsIso: "2025-11-04T00:00:01.000Z",
+            type: "ticket.created",
+          },
+        ],
+        result: "second",
+      } as const;
+    },
+  });
+
+  const results = await Promise.all([firstMutation, secondMutation]);
+
+  expect(results).toEqual([
+    { ok: true, result: "first" },
+    { ok: true, result: "second" },
+  ]);
+  expect(maxActiveCount).toBe(1);
+});
+
+async function createTempGitProject(opts: {
+  readonly prefix: string;
+}): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), opts.prefix));
+  tempRoots.push(root);
+  await copyDir({
+    from: resolve(import.meta.dir, "../examples/tickets"),
+    to: root,
+  });
+  await run({ cwd: root, cmd: ["git", "init"] });
+  await run({ cwd: root, cmd: ["git", "config", "user.email", "tests@hack"] });
+  await run({
+    cwd: root,
+    cmd: ["git", "config", "user.name", "hack-cli-tests"],
+  });
+  await run({ cwd: root, cmd: ["git", "add", "-A"] });
+  await run({ cwd: root, cmd: ["git", "commit", "-m", "init"] });
+  return root;
+}
+
+async function run(opts: {
+  readonly cwd: string;
+  readonly cmd: readonly string[];
+}) {
+  const proc = Bun.spawn([...opts.cmd], {
+    cwd: opts.cwd,
+    env: process.env,
+    stderr: "pipe",
+    stdin: "ignore",
+    stdout: "pipe",
+  });
+
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    throw new Error(
+      `Command failed (${exitCode}): ${opts.cmd.join(" ")}\n${stderr || stdout}`
+    );
+  }
+}
+
+async function copyDir(opts: {
+  readonly from: string;
+  readonly to: string;
+}): Promise<void> {
+  await mkdir(opts.to, { recursive: true });
+  const entries = await readdir(opts.from, { withFileTypes: true });
+  for (const entry of entries) {
+    const fromPath = join(opts.from, entry.name);
+    const toPath = join(opts.to, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir({ from: fromPath, to: toPath });
+    } else if (entry.isFile()) {
+      const data = await readFile(fromPath);
+      await writeFile(toPath, data);
+    }
+  }
+}
diff --git a/tests/tickets-id-generation.test.ts b/tests/tickets-id-generation.test.ts
index 02a81aee9..99beae3c5 100644
--- a/tests/tickets-id-generation.test.ts
+++ b/tests/tickets-id-generation.test.ts
@@ -88,20 +88,83 @@ test("tickets store retries generated ids that collide during concurrent creates
   ]);
 }, 20_000);
 
-async function createStore(opts: { readonly projectRoot: string }) {
+test("tickets store reallocates ticket ids after a push retry sees a remote collision", async () => {
+  const remoteRoot = await mkdtemp(join(tmpdir(), "hack-cli-tickets-remote-"));
+  tempRoots.push(remoteRoot);
+  await run({ cwd: remoteRoot, cmd: ["git", "init", "--bare"] });
+
+  const projectRootA = await createTempGitProject({
+    prefix: "hack-cli-tickets-remote-a-",
+    remoteRoot,
+  });
+  const projectRootB = await createTempGitProject({
+    prefix: "hack-cli-tickets-remote-b-",
+    remoteRoot,
+  });
+
+  const storeA = await createStore({
+    projectRoot: projectRootA,
+    generateTicketId: () => "T-AAAAAAAAAA",
+  });
+  const storeB = await createStore({
+    projectRoot: projectRootB,
+    generateTicketId: (() => {
+      const generatedIds = ["T-AAAAAAAAAA", "T-BBBBBBBBBB"];
+      return () => generatedIds.shift() ?? "T-CCCCCCCCCC";
+    })(),
+  });
+
+  expect(await storeB.listTickets()).toEqual([]);
+
+  const createdA = await storeA.createTicket({
+    title: "First repo ticket",
+    owner: "hack",
+    source: "hack",
+    actor: "creator-a@hack",
+  });
+  expect(createdA.ok).toBe(true);
+
+  const createdB = await storeB.createTicket({
+    title: "Second repo ticket",
+    owner: "hack",
+    source: "hack",
+    actor: "creator-b@hack",
+  });
+  expect(createdB.ok).toBe(true);
+  if (!(createdA.ok && createdB.ok)) {
+    throw new Error("Expected both ticket creates to succeed");
+  }
+
+  expect(createdA.ticket.ticketId).toBe("T-AAAAAAAAAA");
+  expect(createdB.ticket.ticketId).toBe("T-BBBBBBBBBB");
+
+  const tickets = await storeB.listTickets();
+  expect(tickets.map((ticket) => ticket.ticketId)).toEqual([
+    "T-AAAAAAAAAA",
+    "T-BBBBBBBBBB",
+  ]);
+}, 20_000);
+
+async function createStore(opts: {
+  readonly projectRoot: string;
+  readonly generateTicketId?: () => string;
+}) {
   const configResult = await readControlPlaneConfig({
     projectDir: join(opts.projectRoot, ".hack"),
   });
   return createTicketsStore({
     projectRoot: opts.projectRoot,
     controlPlaneConfig: configResult.config,
-    generateTicketId: () => generatedTicketIds.shift() ?? "T-ZZZZZZZZZZ",
+    generateTicketId:
+      opts.generateTicketId ??
+      (() => generatedTicketIds.shift() ?? "T-ZZZZZZZZZZ"),
     logger,
   });
 }
 
 async function createTempGitProject(opts: {
   readonly prefix: string;
+  readonly remoteRoot?: string;
 }): Promise<string> {
   const root = await mkdtemp(join(tmpdir(), opts.prefix));
   tempRoots.push(root);
@@ -117,6 +180,12 @@ async function createTempGitProject(opts: {
   });
   await run({ cwd: root, cmd: ["git", "add", "-A"] });
   await run({ cwd: root, cmd: ["git", "commit", "-m", "init"] });
+  if (opts.remoteRoot) {
+    await run({
+      cwd: root,
+      cmd: ["git", "remote", "add", "origin", opts.remoteRoot],
+    });
+  }
   return root;
 }
 

From 749fbad95f4d6f7347eb10ed9ea622a416dc07eb Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:26:28 +0000
Subject: [PATCH 107/134] chore(symphony): checkpoint HACK-430 before
 integration

---
 ...26-03-13-cli-ux-and-guided-setup-design.md | 412 ++++++++++++++++
 ...2026-03-13-cli-ux-and-guided-setup-plan.md | 446 ++++++++++++++++++
 2 files changed, 858 insertions(+)
 create mode 100644 docs/plans/2026-03-13-cli-ux-and-guided-setup-design.md
 create mode 100644 docs/plans/2026-03-13-cli-ux-and-guided-setup-plan.md

diff --git a/docs/plans/2026-03-13-cli-ux-and-guided-setup-design.md b/docs/plans/2026-03-13-cli-ux-and-guided-setup-design.md
new file mode 100644
index 000000000..44fc8b266
--- /dev/null
+++ b/docs/plans/2026-03-13-cli-ux-and-guided-setup-design.md
@@ -0,0 +1,412 @@
+# CLI UX And Guided Setup Design
+
+## Context
+
+Hack already exposes most of the underlying capability needed for setup, repair, and provider auth:
+
+- `hack doctor` checks many machine prerequisites and already suggests `hack doctor --fix` for several failures.
+- `hack setup` manages agent/editor integrations.
+- `hack auth` provides a first-class Hack account flow.
+- `hack linear` exists as a top-level alias over the Linear extension.
+- `hack tickets` exists as a top-level alias over the tickets extension.
+- `hack x` remains the generic extension dispatcher.
+
+The problem is not missing raw capability. The problem is that prerequisite detection, next-step routing, and status language are still fragmented across commands, extensions, and transport-specific error strings.
+
+Today a user can still hit all of these failure classes:
+
+- missing runtime prerequisites discovered only after a command fails
+- mux/session failures that surface as backend absence rather than setup guidance
+- GitHub flows that remain extension-centric and token-centric
+- Linear broker flows that depend on Hack auth, local profile config, and project routing, but do not always explain which layer is missing
+- help output that explains commands, but not the setup state required to use them
+
+This stream defines the UX contract for first-run and repair behavior without requiring every child issue to invent its own interception language.
+
+## Goals
+
+- Make missing prerequisites discoverable from CLI output alone.
+- Route users to the right setup or repair flow automatically.
+- Define consistent top-level semantics for built-in commands, top-level aliases, and `hack x`.
+- Normalize how status/help/error output describes auth, profiles, teams, and project routing.
+- Break the stream into child issues that are independently executable.
+
+## Non-Goals
+
+- Do not redesign the full visual style of every command output.
+- Do not collapse all extension commands into the root CLI in one pass.
+- Do not replace provider-specific logic with one giant generic setup engine.
+- Do not move existing local-only workflows behind mandatory Hack sign-in.
+- Do not implement every child issue in this stream from this program ticket.
+
+## Approaches Considered
+
+### 1. Program-level UX contract first, then targeted child implementation
+
+Define one shared prerequisite matrix, interception model, command taxonomy, and status vocabulary. Land that as docs plus child issue decomposition, then let each child issue implement one part.
+
+Pros:
+
+- Matches the acceptance criteria for this stream issue.
+- Prevents runtime, mux, GitHub, and Linear work from drifting apart.
+- Makes future code review objective because the contract is explicit.
+
+Cons:
+
+- Does not immediately change runtime behavior by itself.
+
+### 2. Incrementally patch each command family directly
+
+Fix `doctor`, `session`, GitHub auth, Linear auth, and help output one by one without a formal shared contract.
+
+Pros:
+
+- Faster short-term shipping on one surface at a time.
+
+Cons:
+
+- High risk of inconsistent messages and overlapping repair flows.
+- Makes later cleanup harder because semantics drift.
+
+### 3. Centralize all setup detection in one universal setup command
+
+Create a single setup wizard that owns all prerequisite detection and recovery.
+
+Pros:
+
+- Conceptually simple entry point.
+
+Cons:
+
+- Too large for this stream.
+- Conflicts with Hack’s existing command-oriented workflow.
+- Still would not address provider-specific interception needs cleanly.
+
+## Recommended Direction
+
+Use approach 1.
+
+This stream should land the product contract for guided setup and repair, then delegate execution to child issues focused on runtime/mux, command semantics, GitHub auth/setup, and Linear auth/setup.
+
+## Current Surface Summary
+
+The current codebase implies the following shape:
+
+- runtime/global infra health lives primarily under `hack doctor`
+- project lifecycle lives under root commands like `hack up`, `hack logs`, and `hack open`
+- Hack account auth lives under `hack auth`
+- Linear already has a root alias: `hack linear`
+- tickets already has a root alias: `hack tickets`
+- GitHub is still extension-only under `hack x github`
+- extension enablement is handled separately from provider auth
+
+This means the new UX contract should not pretend the CLI is fully flattened already. It should explicitly define which commands stay root-level, which commands remain extension-level for now, and how the CLI explains that split.
+
+## Approved UX Contract
+
+### 1. Prerequisites are grouped by capability, not by implementation detail
+
+The CLI should reason about four user-facing capability groups:
+
+- runtime
+- mux sessions
+- GitHub integration
+- Linear integration
+
+Each group has a small prerequisite matrix with:
+
+- what the user is trying to do
+- what must exist
+- how the CLI checks it
+- what command repairs it
+- whether the CLI can auto-intercept and route
+
+### 2. Every missing prerequisite maps to one next step
+
+When a command fails because a prerequisite is missing, the user should see:
+
+- what is missing
+- why this command needs it
+- the exact next command to run
+- whether rerunning the original command should work afterward
+
+Avoid vague guidance like:
+
+- "not configured"
+- "missing context"
+- "extension disabled"
+
+unless the output also names the corrective action.
+
+### 3. Root commands are intent-first; `hack x` is the escape hatch
+
+The command taxonomy should be:
+
+- `hack <root-command>` for built-in product workflows and high-frequency integrated flows
+- `hack <alias>` for promoted extensions with stable UX contracts
+- `hack x <namespace> ...` for advanced or not-yet-promoted extension workflows
+
+For this stream, the intended top-level shape is:
+
+- keep `hack auth`
+- keep `hack linear`
+- keep `hack tickets`
+- keep `hack setup`
+- keep `hack doctor`
+- keep `hack x` as the generic dispatcher
+- add a first-class decision on whether GitHub remains `hack x github` or is promoted to `hack github`
+
+### 4. Interception should happen at the command entry point closest to intent
+
+The CLI should intercept at the first command the user naturally runs, not after multiple opaque transport failures.
+
+Examples:
+
+- `hack up` should intercept missing global/runtime health and send the user to `hack doctor` or `hack doctor --fix`
+- `hack session start` should intercept missing mux backend and explain how to enable tmux/zellij or choose no-mux mode
+- `hack x github ...` or `hack github ...` should intercept missing `gh`, missing stored profile state, and missing Hack auth only when the chosen flow actually requires it
+- `hack linear ...` should intercept missing Hack auth, missing broker-backed profile access, missing local token/profile state, or missing project binding distinctly
+
+### 5. Status output must separate these concepts consistently
+
+Human-facing and JSON output should use stable language for:
+
+- Hack account session
+- provider connection
+- selected profile
+- selected organization/team
+- project binding/routing
+- local access versus broker-owned access
+
+The CLI should not force users to infer which layer failed from an error string.
+
+## Prerequisite Detection Matrix
+
+### Runtime
+
+| Capability | Required state | Existing check surface | Expected interception |
+| --- | --- | --- | --- |
+| `hack up`, `hack open`, `hack logs`, `hack ps` | bun installed, docker available, docker daemon reachable, global networking healthy enough for routed features | mostly `hack doctor`, partial command-local checks in project commands | commands route to `hack doctor` / `hack doctor --fix` with targeted explanation |
+| routed HTTPS hosts | caddy/global infra, DNS resolver, trust state | `hack doctor`, project command warnings | command explains whether routing is degraded vs fully blocked |
+| mutagen-backed workflows | mutagen binary/agent availability | `hack doctor`, mutagen helpers | repair points to `hack doctor --fix` or explicit mutagen path override |
+
+### Mux Sessions
+
+| Capability | Required state | Existing check surface | Expected interception |
+| --- | --- | --- | --- |
+| `hack session`, `hack session start` | chosen mux mode resolves to available tmux/zellij backend, or explicit no-mux mode | mux resolver + backend availability checks | session command explains missing backend and setup choice instead of acting like zero sessions exist |
+| attach/exec/capture | backend installed and target session exists | session commands | command distinguishes "backend missing" from "session missing" |
+
+### GitHub Integration
+
+| Capability | Required state | Existing check surface | Expected interception |
+| --- | --- | --- | --- |
+| GitHub status/connect/profile workflows | extension enabled, selected profile resolved, local token/app installation state available | GitHub extension auth/commands | user sees promoted command semantics and exact repair path |
+| broker-owned/shared GitHub features | valid Hack auth session plus authorized broker access | provider-specific auth flows | output distinguishes Hack account login from GitHub provider connection |
+| PR/remote bootstrap workflows | `gh` installed when flow depends on GitHub CLI | GitHub commands | command offers install/setup guidance before failing deeper |
+
+### Linear Integration
+
+| Capability | Required state | Existing check surface | Expected interception |
+| --- | --- | --- | --- |
+| local profile/token flows | extension enabled, selected profile resolved, local token saved or provided | Linear command parsing/auth helpers | output explains profile selection and storage source clearly |
+| broker-owned connection/autosync flows | Hack auth session, broker management token, permitted profile/team/project access | Linear auth/session helpers | command states whether user needs `hack auth login`, reconnect, or different profile/team |
+| project sync/routing flows | project context present, project binding present, route scope known | Linear commands + project config | output names bound project/team/profile and what is missing |
+
+## Interception Rules
+
+### Root runtime commands
+
+For `hack up`, `hack open`, `hack logs`, and related project commands:
+
+- preflight only the prerequisites relevant to the requested behavior
+- distinguish hard blockers from degraded modes
+- point to `hack doctor` or `hack doctor --fix` when a shared runtime issue is the root cause
+- preserve the original command in the message so the user knows what to retry
+
+### Session commands
+
+For `hack session`:
+
+- if mux mode is `auto` and no backend is available, explain the decision tree: install tmux, install zellij, or set mux mode to `none`
+- if a backend exists but session name is missing, show normal session guidance
+- do not silently treat missing backend as an empty session list
+
+### Extension promotion and dispatch
+
+For promoted namespaces:
+
+- root alias and `hack x` behavior should stay functionally aligned
+- root help should explain when a workflow is promoted
+- `hack x` help should describe itself as the advanced/escape-hatch path
+
+For unpromoted namespaces:
+
+- `hack x <namespace>` remains canonical until promotion is approved
+
+### Provider auth flows
+
+For GitHub and Linear:
+
+- first explain whether the missing layer is Hack account auth, provider auth, or project/profile selection
+- do not say "not authorized" without naming the identity boundary
+- show active profile/team/project bindings in status output when they affect the requested command
+
+## Status And Help Vocabulary
+
+The CLI should standardize these phrases:
+
+- `Hack account`: the Better Auth session used for broker-owned resources
+- `Provider profile`: the selected GitHub or Linear profile
+- `Local access`: provider token/profile state stored on this machine
+- `Broker access`: remote access owned by the Hack account/org/team
+- `Project binding`: the project-level route to a provider profile/project/team
+- `Repair`: a recoverable path where the CLI knows the next command
+
+Avoid mixing these into ambiguous phrases like:
+
+- `connected` with no scope
+- `authorized` with no subject
+- `default` with no mention of profile vs team vs project binding
+
+## Child Issue Breakdown
+
+This stream should break into the following child issues.
+These are already recorded in the repo-local `hack` tickets ref as `T-00001` through `T-00006`.
+
+### 1. Runtime prerequisite detection and guided repair (`T-00002`)
+
+Scope:
+
+- define command-level runtime preflight helpers
+- align `hack up`/`open`/`logs` with `hack doctor`
+- normalize degraded-vs-blocked messaging
+
+Primary files:
+
+- `src/commands/project.ts`
+- `src/commands/doctor.ts`
+- shared runtime helper modules under `src/lib/` or `src/commands/`
+
+### 2. Mux/session prerequisite interception (`T-00003`)
+
+Scope:
+
+- make missing tmux/zellij explicit
+- surface mux mode and repair actions in `hack session`
+- distinguish backend absence from missing sessions
+
+Primary files:
+
+- `src/commands/session.ts`
+- `src/mux/mux-resolver.ts`
+- `src/mux/*.ts`
+
+### 3. Top-level command semantics and help cleanup (`T-00001`)
+
+Scope:
+
+- define promotion rules for root aliases vs `hack x`
+- decide GitHub root alias promotion
+- improve root help and dispatcher help copy
+- make extension-disabled messaging intent-first
+
+Primary files:
+
+- `src/cli/help.ts`
+- `src/cli/spec.ts`
+- `src/commands/x.ts`
+- command alias files such as `src/commands/linear.ts`, `src/commands/tickets.ts`
+
+### 4. GitHub setup and auth guidance cleanup (`T-00005`)
+
+Scope:
+
+- clarify setup/auth/status output for GitHub profiles
+- intercept missing `gh`, missing local auth, and broker-auth requirements
+- align any promoted root alias with extension behavior
+
+Primary files:
+
+- `src/control-plane/extensions/github/commands.ts`
+- `src/control-plane/extensions/github/auth.ts`
+- related GitHub tests
+
+### 5. Linear setup and broker/local access guidance cleanup (`T-00006`)
+
+Scope:
+
+- clarify Hack auth vs Linear auth vs project binding failures
+- standardize status output around profile/team/project context
+- improve repair routing for broker-backed access and local repair flows
+
+Primary files:
+
+- `src/control-plane/extensions/linear/commands.ts`
+- `src/control-plane/extensions/linear/auth.ts`
+- related Linear tests
+
+### 6. Shared status payload vocabulary (`T-00004`)
+
+Scope:
+
+- define shared JSON fields and human phrasing for auth/profile/routing status
+- align provider and root status commands on that vocabulary
+
+Primary files:
+
+- auth/provider command implementations
+- any shared status rendering helpers
+- command tests asserting payload shape and text
+
+## Testing Strategy
+
+This stream’s child work should bias toward command-level tests that assert:
+
+- the right interception occurs before deep failure
+- output names the missing prerequisite explicitly
+- output names the exact next command
+- JSON output exposes the same state model as human output
+
+Use focused Bun tests for:
+
+- command parsing
+- command handlers with mocked fetch/process state
+- status payload rendering
+- help output snapshots where needed
+
+## Acceptance Mapping
+
+### A user can discover and fix missing setup from CLI output alone
+
+Covered by:
+
+- prerequisite matrix
+- interception rules
+- repair vocabulary
+
+### Core workflows route users into the correct setup or repair flow automatically
+
+Covered by:
+
+- root runtime command interception
+- session interception
+- provider auth flow interception
+
+### Integration commands explain active bindings and missing context clearly
+
+Covered by:
+
+- status/help vocabulary
+- provider-specific guidance rules
+- shared status payload contract
+
+### The child issues in this stream are sufficient to implement the new UX contract
+
+Covered by:
+
+- six-child breakdown across runtime, mux, semantics, GitHub, Linear, and shared status payloads
+
+## Recommended Next Step
+
+Write an implementation plan that converts this contract into small tasks and create local child tickets mirroring the issue breakdown above.
diff --git a/docs/plans/2026-03-13-cli-ux-and-guided-setup-plan.md b/docs/plans/2026-03-13-cli-ux-and-guided-setup-plan.md
new file mode 100644
index 000000000..2b38d407a
--- /dev/null
+++ b/docs/plans/2026-03-13-cli-ux-and-guided-setup-plan.md
@@ -0,0 +1,446 @@
+# CLI UX And Guided Setup Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Establish and implement a consistent guided-setup and repair contract across runtime, mux, GitHub, Linear, and top-level command semantics so users can recover from missing setup directly from CLI output.
+
+**Architecture:** Keep Hack’s command-oriented structure, but add a shared prerequisite/interception vocabulary that root commands, promoted aliases, and extension commands all use consistently. Treat `hack doctor` as the runtime repair authority, `hack auth` as the Hack-account authority, provider commands as provider-specific repair surfaces, and `hack x` as the advanced dispatcher instead of the default user journey.
+
+**Tech Stack:** Bun, TypeScript, Hack CLI command framework, extension command surfaces, Bun tests.
+
+## Execution Notes
+
+- Implement this stream through child issues rather than as one giant branch.
+- Favor command-level tests that assert the user-visible next step.
+- Keep JSON payloads and human output aligned.
+- Reuse existing helpers before adding new shared layers.
+- Repo-local ticket mapping:
+  `T-00001` top-level semantics, `T-00002` runtime repair, `T-00003` mux/session repair,
+  `T-00004` shared status vocabulary, `T-00005` GitHub guidance, `T-00006` Linear guidance.
+
+---
+
+### Task 1: Introduce a shared prerequisite result model
+
+**Files:**
+
+- Create: `src/cli/prereq.ts`
+- Modify: `src/commands/project.ts`
+- Modify: `src/commands/session.ts`
+- Test: `tests/cli-prereq.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for a minimal prerequisite result model that can represent:
+
+- `ok`
+- `degraded`
+- `blocked`
+- exact repair command
+- retryable original command
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/cli-prereq.test.ts
+```
+
+Expected: FAIL because the shared prerequisite model does not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Add a small shared type/helper layer for prerequisite checks and repair messages. Keep it presentation-focused rather than building a large framework.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/cli-prereq.test.ts
+```
+
+Expected: PASS
+
+### Task 2: Align runtime commands with guided doctor repair
+
+**Files:**
+
+- Modify: `src/commands/project.ts`
+- Modify: `src/commands/doctor.ts`
+- Test: `tests/project-up-command.test.ts`
+- Test: `tests/daemon-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add focused tests showing that runtime failures route users to:
+
+- `hack doctor`
+- `hack doctor --fix`
+- degraded-mode explanations when routing or trust is unavailable but the command can still partially work
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/project-up-command.test.ts tests/daemon-command.test.ts
+```
+
+Expected: FAIL after adding the new expectations.
+
+**Step 3: Write minimal implementation**
+
+Use the shared prerequisite model to standardize runtime repair messages in project commands. Reuse doctor checks where practical instead of duplicating raw diagnostics.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/project-up-command.test.ts tests/daemon-command.test.ts
+```
+
+Expected: PASS
+
+### Task 3: Make mux/session repair intent-first
+
+**Files:**
+
+- Modify: `src/commands/session.ts`
+- Modify: `src/mux/mux-resolver.ts`
+- Modify: `src/mux/tmux-backend.ts`
+- Modify: `src/mux/zellij-backend.ts`
+- Test: `tests/session-utils.test.ts`
+- Create: `tests/session-command-guidance.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+
+- auto mux mode with no available backend
+- explicit tmux mode with tmux missing
+- explicit zellij mode with zellij missing
+- existing backend but missing named session
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/session-command-guidance.test.ts tests/session-utils.test.ts
+```
+
+Expected: FAIL because session guidance does not yet distinguish backend setup from missing sessions clearly.
+
+**Step 3: Write minimal implementation**
+
+Return structured prerequisite failures from session entry points and render repair options:
+
+- install tmux
+- install zellij
+- configure mux mode to `none`
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/session-command-guidance.test.ts tests/session-utils.test.ts
+```
+
+Expected: PASS
+
+### Task 4: Clean up root help and dispatcher semantics
+
+**Files:**
+
+- Modify: `src/cli/help.ts`
+- Modify: `src/cli/spec.ts`
+- Modify: `src/commands/x.ts`
+- Modify: `src/commands/linear.ts`
+- Modify: `src/commands/tickets.ts`
+- Test: `tests/cli-command.test.ts`
+- Create: `tests/help-output.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+
+- root help surfacing promoted workflows clearly
+- `hack x` help framing itself as advanced/dispatcher behavior
+- extension-disabled output naming the exact promoted or extension entry point
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts tests/help-output.test.ts
+```
+
+Expected: FAIL with current help/dispatcher messaging.
+
+**Step 3: Write minimal implementation**
+
+Update root help and dispatcher copy to:
+
+- explain promoted aliases
+- explain when `hack x` is still canonical
+- make disabled-extension output intent-first rather than namespace-first
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts tests/help-output.test.ts
+```
+
+Expected: PASS
+
+### Task 5: Decide and implement GitHub top-level semantics
+
+**Files:**
+
+- Modify: `src/cli/spec.ts`
+- Create or modify: `src/commands/github.ts`
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Test: `tests/github-commands.test.ts`
+- Create: `tests/github-command-alias.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for the approved GitHub entry-point decision:
+
+- if promoted: `hack github ...` mirrors `hack x github ...`
+- if not promoted: help/repair output consistently points users to `hack x github`
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/github-commands.test.ts tests/github-command-alias.test.ts
+```
+
+Expected: FAIL because the chosen semantics are not implemented yet.
+
+**Step 3: Write minimal implementation**
+
+Implement the approved path only. Do not redesign GitHub auth in the same step.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/github-commands.test.ts tests/github-command-alias.test.ts
+```
+
+Expected: PASS
+
+### Task 6: Improve GitHub prerequisite interception
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/github/commands.ts`
+- Modify: `src/control-plane/extensions/github/auth.ts`
+- Test: `tests/github-commands.test.ts`
+- Test: `tests/github-auth.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+
+- missing `gh`
+- missing selected GitHub profile
+- missing local token/app installation state
+- broker-owned flow requiring Hack auth
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/github-commands.test.ts tests/github-auth.test.ts
+```
+
+Expected: FAIL after adding new guidance expectations.
+
+**Step 3: Write minimal implementation**
+
+Make GitHub commands report the missing layer explicitly and name the next command to run.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/github-commands.test.ts tests/github-auth.test.ts
+```
+
+Expected: PASS
+
+### Task 7: Improve Linear prerequisite interception and routing clarity
+
+**Files:**
+
+- Modify: `src/control-plane/extensions/linear/commands.ts`
+- Modify: `src/control-plane/extensions/linear/auth.ts`
+- Test: `tests/linear-commands.test.ts`
+- Test: `tests/linear-auth.test.ts`
+- Test: `tests/auth-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+
+- missing Hack auth for broker-owned Linear access
+- stale broker token vs missing broker token
+- missing local profile/token state
+- missing project binding when running sync/project-scoped commands
+- status output including profile/team/project context clearly
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/linear-commands.test.ts tests/linear-auth.test.ts tests/auth-command.test.ts
+```
+
+Expected: FAIL after new expectations are added.
+
+**Step 3: Write minimal implementation**
+
+Standardize Linear repair output around four layers:
+
+- Hack account session
+- broker permission/profile ownership
+- local profile/token access
+- project binding/routing
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/linear-commands.test.ts tests/linear-auth.test.ts tests/auth-command.test.ts
+```
+
+Expected: PASS
+
+### Task 8: Standardize shared status vocabulary and payloads
+
+**Files:**
+
+- Modify: `src/commands/auth.ts`
+- Modify: provider status commands under `src/control-plane/extensions/*/commands.ts`
+- Create: `src/ui/status-contract.ts`
+- Test: `tests/auth-command.test.ts`
+- Test: `tests/github-commands.test.ts`
+- Test: `tests/linear-commands.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests asserting stable human/JSON vocabulary for:
+
+- Hack account
+- provider profile
+- local access
+- broker access
+- project binding
+- repair next step
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/auth-command.test.ts tests/github-commands.test.ts tests/linear-commands.test.ts
+```
+
+Expected: FAIL because the shared vocabulary layer does not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Add a small shared status helper and adopt it in status-oriented commands.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/auth-command.test.ts tests/github-commands.test.ts tests/linear-commands.test.ts
+```
+
+Expected: PASS
+
+### Task 9: Create and sync child tickets for the stream
+
+**Files:**
+
+- Verify only in git-backed tickets store
+
+**Step 1: Create child tickets**
+
+Create tickets for:
+
+- runtime prerequisite repair
+- mux/session interception
+- root help and command semantics
+- GitHub setup/auth guidance
+- Linear setup/auth guidance
+- shared status vocabulary
+
+Current status: these tickets already exist in the repo-local hidden ref as `T-00001` through
+`T-00006`.
+
+**Step 2: Mark dependencies**
+
+Model dependencies so shared vocabulary and command semantics can support the provider-specific work without blocking unrelated runtime fixes.
+
+**Step 3: Sync tickets**
+
+Run:
+
+```bash
+bun index.ts x tickets sync
+```
+
+Expected: tickets ref updates successfully once the workspace is bootstrapped.
+
+### Task 10: Final verification
+
+**Files:**
+
+- Verify only
+
+**Step 1: Run focused tests for changed slices**
+
+Run the relevant focused `bun test ...` commands from the child issue being implemented.
+
+**Step 2: Run repo quality gates**
+
+Run:
+
+```bash
+bun run check
+bun run typecheck
+bun run test
+```
+
+Expected: PASS
+
+**Step 3: Verify ticket state and handoff context**
+
+Run:
+
+```bash
+bun index.ts x tickets list
+git status --short
+```
+
+Expected: new docs and ticket artifacts are present, and remaining work is captured in child tickets.

From 67004c402382d6ddf896d29cd2e821e6758cd523 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:26:32 +0000
Subject: [PATCH 108/134] chore(symphony): checkpoint HACK-465 before
 integration

---
 .cursor/rules/hack.mdc | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/.cursor/rules/hack.mdc b/.cursor/rules/hack.mdc
index 835164c17..8f55277b3 100644
--- a/.cursor/rules/hack.mdc
+++ b/.cursor/rules/hack.mdc
@@ -37,6 +37,12 @@ hack down
 hack global status
 hack session
 hack tickets list
+hack node list
+hack node status --watch
+hack node ssh setup --node <id>
+hack node routes status
+hack node routes repair
+hack dispatch run --project <name|id> --node default --branch <branch> --runner generic -- "pwd"
 hack internal extra-hosts list
 hack internal extra-hosts set <hostname> <target>
 hack internal extra-hosts unset <hostname>

From 64e7af625e8e4d48c9d21e736dcfa4e81ba3c692 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:26:36 +0000
Subject: [PATCH 109/134] chore(symphony): checkpoint HACK-436 before
 integration

---
 .hack/hack.config.json              |  5 ---
 src/lib/project.ts                  | 17 ++++++++-
 tests/project-config.test.ts        | 54 ++++++++++++++++++++++++++++-
 tests/project-owner-command.test.ts | 51 +++++++++++++++++++++++++++
 4 files changed, 120 insertions(+), 7 deletions(-)

diff --git a/.hack/hack.config.json b/.hack/hack.config.json
index fd4279595..43867b9e4 100644
--- a/.hack/hack.config.json
+++ b/.hack/hack.config.json
@@ -11,11 +11,6 @@
         "enabled": true
       }
     },
-    "tickets": {
-      "git": {
-        "enabled": false
-      }
-    },
     "gateway": {
       "enabled": true
     }
diff --git a/src/lib/project.ts b/src/lib/project.ts
index 74ec35264..6cc8c9a7e 100644
--- a/src/lib/project.ts
+++ b/src/lib/project.ts
@@ -420,6 +420,13 @@ function parseProjectOwnership(value: unknown): ParsedProjectOwnership {
         "Project ownership.owner_type must be 'user', 'team', or 'organization'.",
     };
   }
+  if (ownerType === "user") {
+    return {
+      ownership: defaultProjectOwnership(),
+      parseError:
+        "Project shared ownership.owner_type must be 'team' or 'organization'.",
+    };
+  }
 
   const ownerIdValue = value.owner_id;
   if (
@@ -432,12 +439,20 @@ function parseProjectOwnership(value: unknown): ParsedProjectOwnership {
       parseError: "Project ownership.owner_id must be a string when provided.",
     };
   }
+  const ownerId = normalizeProjectOwnerId(ownerIdValue);
+  if (ownerId === null) {
+    return {
+      ownership: defaultProjectOwnership(),
+      parseError:
+        "Project shared ownership.owner_id must be a non-empty string.",
+    };
+  }
 
   return {
     ownership: {
       mode: "shared",
       ownerType,
-      ownerId: normalizeProjectOwnerId(ownerIdValue),
+      ownerId,
       managedBy: "broker",
     },
   };
diff --git a/tests/project-config.test.ts b/tests/project-config.test.ts
index 2dbe044a2..ecea5cfc9 100644
--- a/tests/project-config.test.ts
+++ b/tests/project-config.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, expect, test } from "bun:test";
+import { afterEach, beforeEach, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -13,12 +13,24 @@ import {
 } from "../src/lib/project.ts";
 
 let tempDir: string | null = null;
+let originalSetupSyncMode: string | undefined;
+
+beforeEach(() => {
+  originalSetupSyncMode = process.env.HACK_SETUP_SYNC_MODE;
+  process.env.HACK_SETUP_SYNC_MODE = "off";
+});
 
 afterEach(async () => {
   if (tempDir) {
     await rm(tempDir, { recursive: true, force: true });
     tempDir = null;
   }
+
+  if (originalSetupSyncMode !== undefined) {
+    process.env.HACK_SETUP_SYNC_MODE = originalSetupSyncMode;
+  } else {
+    process.env.HACK_SETUP_SYNC_MODE = undefined;
+  }
 });
 
 async function createProjectDir(): Promise<{
@@ -155,6 +167,46 @@ test("readProjectConfig rejects ownership fields without an explicit mode", asyn
   );
 });
 
+test("readProjectConfig rejects shared ownership without a non-user owner", async () => {
+  const ctx = await createProjectDir();
+  await writeFile(
+    ctx.configFile,
+    JSON.stringify({
+      ownership: {
+        mode: "shared",
+        owner_type: "user",
+        owner_id: "user_123",
+      },
+    })
+  );
+
+  const cfg = await readProjectConfig(ctx);
+
+  expect(cfg.parseError).toBe(
+    "Project shared ownership.owner_type must be 'team' or 'organization'."
+  );
+});
+
+test("readProjectConfig rejects shared ownership without a concrete owner id", async () => {
+  const ctx = await createProjectDir();
+  await writeFile(
+    ctx.configFile,
+    JSON.stringify({
+      ownership: {
+        mode: "shared",
+        owner_type: "team",
+        owner_id: "   ",
+      },
+    })
+  );
+
+  const cfg = await readProjectConfig(ctx);
+
+  expect(cfg.parseError).toBe(
+    "Project shared ownership.owner_id must be a non-empty string."
+  );
+});
+
 test("readProjectConfig defaults ownership to local user scope", async () => {
   const ctx = await createProjectDir();
 
diff --git a/tests/project-owner-command.test.ts b/tests/project-owner-command.test.ts
index c820d5bd4..26da8c259 100644
--- a/tests/project-owner-command.test.ts
+++ b/tests/project-owner-command.test.ts
@@ -164,6 +164,57 @@ test("project owner show fails when ownership fields omit mode", async () => {
   );
 });
 
+test("project owner show fails when shared ownership uses a user owner", async () => {
+  const projectRoot = await createHackProject({
+    rawConfig: JSON.stringify({
+      ownership: {
+        mode: "shared",
+        owner_type: "user",
+        owner_id: "user_123",
+      },
+    }),
+  });
+
+  const result = await runCliWithCapturedOutput([
+    "project",
+    "owner",
+    "show",
+    "--path",
+    projectRoot,
+    "--json",
+  ]);
+
+  expect(result.exitCode).toBe(1);
+  expect(`${result.stdout}\n${result.stderr}`).toContain(
+    "Project shared ownership.owner_type must be 'team' or 'organization'."
+  );
+});
+
+test("project owner show fails when shared ownership omits owner id", async () => {
+  const projectRoot = await createHackProject({
+    rawConfig: JSON.stringify({
+      ownership: {
+        mode: "shared",
+        owner_type: "team",
+      },
+    }),
+  });
+
+  const result = await runCliWithCapturedOutput([
+    "project",
+    "owner",
+    "show",
+    "--path",
+    projectRoot,
+    "--json",
+  ]);
+
+  expect(result.exitCode).toBe(1);
+  expect(`${result.stdout}\n${result.stderr}`).toContain(
+    "Project shared ownership.owner_id must be a non-empty string."
+  );
+});
+
 async function createHackProject(opts?: {
   readonly ownership?: {
     readonly mode: "local" | "shared";

From 1a0d9a2a71b24ec2765eb583841dda82c755c3be Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:31:04 +0000
Subject: [PATCH 110/134] docs: add integrations overview

---
 README.md      | 24 ++++++++++++++++++++++++
 docs/README.md | 21 +++++++++++++++++++++
 docs/cli.md    |  8 ++++----
 3 files changed, 49 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 31d64cc93..42f436247 100644
--- a/README.md
+++ b/README.md
@@ -113,6 +113,30 @@ If anything fails, use `hack logs --pretty` and summarize next steps.
 
 If the agent cannot run shell commands, use MCP instead: `hack setup mcp` and `hack mcp serve`.
 
+## Adjacent capabilities at a glance
+
+Not every repo needs every `hack` capability on day one. These are the common adjacent tools people run
+into after `hack init`, `hack up`, and `hack open` are already working:
+
+- **GitHub**: Connect GitHub when you want `hack` to help with pull requests and branch handoff from the
+  same place you run local work. It becomes relevant once you are ready to open, update, or share PRs.
+  Docs: [`docs/extensions.md`](docs/extensions.md)
+- **Linear**: Connect Linear when your team plans work there and you want Hack to bridge repo work with
+  project and issue tracking. It becomes relevant when a repo maps to a Linear project or when you want
+  sync between Linear issues and repo-local work. Docs: [`docs/extensions.md`](docs/extensions.md)
+- **Tickets**: Use tickets when you want lightweight task tracking that stays with the repo and works
+  well for solo work, small teams, or agents. It becomes relevant as soon as you want to capture work
+  items without pushing everyone into a separate tracker. Docs:
+  [`docs/guides/tickets.md`](docs/guides/tickets.md)
+- **Sessions**: Use sessions when you want a terminal workspace you can come back to, share over SSH,
+  or hand off to an agent without rebuilding context. It becomes relevant when you keep long-running
+  shells, multiple projects, or multiple branches alive at once. Docs:
+  [`docs/sessions.md`](docs/sessions.md)
+- **Env**: Use env when a project needs local configuration like API keys, database URLs, or per-service
+  settings that should be explicit instead of tribal knowledge. It becomes relevant as soon as `hack up`,
+  `hack run`, or remote workflows depend on values that should not be hardcoded into the repo. Docs:
+  [`docs/env.md`](docs/env.md)
+
 ### Remote node runtime image (multi-node)
 
 Use the prebuilt node-runtime container to bootstrap remote nodes quickly (Linux/macOS hosts with Docker):
diff --git a/docs/README.md b/docs/README.md
index e493be242..bac23a3bd 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,6 +2,27 @@
 
 This directory contains the public documentation for hack. Specs remain in `SPECS/` (working notes).
 
+## Adjacent capabilities at a glance
+
+These docs cover a few capabilities that usually appear right after the core `init/up/open/logs` loop.
+You do not need all of them to start using `hack`.
+
+- **GitHub**: Connect GitHub when you want `hack` to help open or update pull requests from the same
+  workflow you use locally. Relevant once your local branch is ready to share or review. Start in
+  [`extensions.md`](extensions.md).
+- **Linear**: Connect Linear when your team tracks delivery there and you want project or issue sync
+  tied to the repo. Relevant when a repo should map cleanly to a Linear project or issue workflow.
+  Start in [`extensions.md`](extensions.md).
+- **Tickets**: Use tickets for lightweight repo-local work tracking that stays close to the code and is
+  easy for agents to update. Relevant when you want task tracking without depending on an external
+  tracker. Start in [`guides/tickets.md`](guides/tickets.md).
+- **Sessions**: Use sessions to keep terminal workspaces alive across SSH, restarts, and agent handoff.
+  Relevant when you want persistent shells instead of recreating project context each time. Start in
+  [`sessions.md`](sessions.md).
+- **Env**: Use env to declare which local config and secrets a project actually needs. Relevant when
+  teammates, automation, or remote runs need a repeatable way to resolve project settings. Start in
+  [`env.md`](env.md).
+
 ## Core docs
 
 - [CLI reference](cli.md)
diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..b24c10d74 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -28,12 +28,12 @@ Run `hack help` or `hack help <command>` for interactive help.
 | `hack open` | Open a URL for the project (default: https://<project>.hack) | Project |
 | `hack tui` | Open the project TUI (services + logs) | Project |
 | `hack branch` | Manage branch aliases for a project | Project |
-| `hack linear` | Linear account connection and ticket sync | Project |
+| `hack linear` | Connect Linear and sync repo work with Linear projects/issues | Project |
 | `hack config` | Read/write hack.config.json values | Project |
-| `hack env` | Manage project environment variables and secrets | Project |
-| `hack session` | Manage terminal sessions for hack projects | Project |
+| `hack env` | Set project env vars and local secrets | Project |
+| `hack session` | Keep reusable terminal workspaces alive | Project |
 | `hack ssh` | Show SSH connection info for remote access | Project |
-| `hack tickets` | Git-backed ticket management | Project |
+| `hack tickets` | Track repo-local work without leaving git | Project |
 | `hack internal` | Manage hack-managed internal overrides | Internal |
 | `hack gateway` | Manage gateway enablement | Extensions |
 | `hack node` | Manage remote execution nodes | Extensions |

From 4511a33ca8a6ab3f1f5c65073cf8c132933862ad Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:33:01 +0000
Subject: [PATCH 111/134] docs: reposition github setup around workflows

---
 README.md                                     |  13 ++
 docs/README.md                                |   1 +
 docs/cli.md                                   |   3 +
 docs/extensions.md                            |  34 +++++-
 docs/guides/github-workflows.md               | 113 ++++++++++++++++++
 docs/guides/remote-node-laptop-e2e.md         |   4 +
 docs/guides/remote-node-quickstart.md         |  15 +++
 .../extensions/github/commands.ts             |   4 +-
 8 files changed, 182 insertions(+), 5 deletions(-)
 create mode 100644 docs/guides/github-workflows.md

diff --git a/README.md b/README.md
index 31d64cc93..fb6bb1983 100644
--- a/README.md
+++ b/README.md
@@ -123,6 +123,19 @@ bun run build:node-runtime-image --tag hack-node-runtime:dev
 
 Full operator guide: [`docs/guides/remote-node-container.md`](docs/guides/remote-node-container.md)
 
+### GitHub workflows (optional)
+
+Connect GitHub only when you want Hack to do GitHub work for you. Today that mainly means:
+
+- creating or updating PRs from `hack dispatch run --pr` or `hack x github pr-upsert`
+- helping the controller bootstrap a private GitHub repo onto a remote node when the node cannot
+  already clone it
+
+You do not need GitHub for local `hack init/up/open`, logs, tickets, or remote runs against public
+repos.
+
+Guide: [`docs/guides/github-workflows.md`](docs/guides/github-workflows.md)
+
 ### Tickets (optional, git-backed issue tracking)
 
 `hack` includes a lightweight, git-backed ticket system for tracking work without leaving your repo. Tickets are stored in a hidden git ref (`refs/hack/tickets`) so they sync with your code but don't clutter your branch list.
diff --git a/docs/README.md b/docs/README.md
index e493be242..a834927f2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -34,6 +34,7 @@ Quick diagnostics:
 - Remote setup (one command): `hack remote setup`
 - [Initialize a project](guides/init-project.md)
 - [Global settings](guides/global-settings.md)
+- [GitHub workflows](guides/github-workflows.md)
 - [Tickets (git-backed)](guides/tickets.md)
 - [Expose the gateway over SSH](guides/remote-ssh.md)
 - [Expose the gateway with Cloudflare](guides/remote-cloudflare.md)
diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..3d70d93b2 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -959,6 +959,9 @@ GitHub profile precedence for `--pr`:
 2. Project `controlPlane.routing.overrides.github.profile`.
 3. Global `controlPlane.extensions["dance.hack.github"].config.defaultProfile`.
 
+`--pr` requires GitHub auth to resolve for the selected profile. Set that up with
+`hack x github oauth-connect` or `hack x github connect` before using PR automation.
+
 #### hack dispatch status
 
 Usage: `hack dispatch status <run-id> [--json]`
diff --git a/docs/extensions.md b/docs/extensions.md
index b4c8b0a81..044c1af97 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -198,6 +198,36 @@ Options:
 
 ### GitHub extension (`hack x github`)
 
+Use GitHub when you want Hack to do GitHub work for you. GitHub is optional for core Hack setup
+and day-to-day local orchestration.
+
+GitHub currently unlocks:
+
+- PR automation from `hack dispatch run --pr` or `hack x github pr-upsert`
+- private GitHub repo bootstrap fallback for remote nodes when the node cannot clone on its own
+- explicit GitHub profile routing across Hack Desktop and the CLI
+
+You do not need GitHub for `hack init`, `hack up`, `hack open`, logs, tickets, or remote workflows
+against public repos.
+
+GitHub becomes required when:
+
+- you want Hack to create or update a GitHub PR
+- you want the controller to supply private GitHub clone credentials during remote bootstrap
+
+`Connect GitHub integration` is also separate from `Sign in to Hack with GitHub`. The first gives
+Hack a GitHub identity for GitHub-specific workflows. The second is only about Hack account auth.
+
+For the workflow-first guide, see [GitHub workflows](guides/github-workflows.md).
+
+Fastest setup paths:
+
+Interactive browser auth + installation picker:
+
+```bash
+hack x github oauth-connect --profile personal --set-default
+```
+
 Connect or update a profile directly from token input:
 
 ```bash
@@ -225,11 +255,9 @@ printf "%s" "$GITHUB_APP_PRIVATE_KEY" | hack x github connect \
   --private-key-auth-ref github.app.private_key.default
 ```
 
-One-click browser OAuth bootstrap (via `gh`) + installation picker:
+Optional non-interactive installation bind with browser OAuth:
 
 ```bash
-hack x github oauth-connect --profile personal --set-default
-# optional non-interactive installation bind:
 hack x github oauth-connect --profile personal --installation-id 12345678
 ```
 
diff --git a/docs/guides/github-workflows.md b/docs/guides/github-workflows.md
new file mode 100644
index 000000000..c3d7aab69
--- /dev/null
+++ b/docs/guides/github-workflows.md
@@ -0,0 +1,113 @@
+# GitHub Workflows
+
+Use GitHub when you want Hack to do GitHub work for you.
+
+GitHub is not part of the base Hack setup. You do not need it for `hack init`, `hack up`,
+`hack open`, logs, local sessions, tickets, or public-repo remote workflows.
+
+GitHub currently unlocks three things:
+
+1. PR automation from Hack.
+2. Private GitHub repo bootstrap on remote nodes when the node cannot already clone the repo.
+3. A named GitHub profile that Hack Desktop and the CLI can route explicitly.
+
+This is also separate from signing in to Hack with GitHub. `Sign in to Hack` controls your Hack
+account. `Connect GitHub integration` gives Hack a GitHub identity it can use for GitHub-specific
+workflows.
+
+## When GitHub Is Optional
+
+Leave GitHub disconnected if you are only using Hack for:
+
+- local orchestration
+- project routing and HTTPS
+- logs and diagnostics
+- tickets or Linear workflows
+- remote execution against public repos
+- remote execution where the node already has working Git credentials
+
+## When GitHub Is Required
+
+Connect GitHub when you want either of these workflows:
+
+- `hack dispatch run --pr` or `hack x github pr-upsert`
+- controller-assisted clone fallback for a private GitHub repo on a remote node
+
+If the remote node can already clone the repo on its own, GitHub stays optional even for remote
+execution.
+
+## Fastest Setup By Goal
+
+### 1. Interactive setup for a person using Hack
+
+Use browser auth and pick an installation:
+
+```bash
+hack x github oauth-connect --profile personal --set-default
+```
+
+Use this when you want the simplest path to PR automation or private-repo fallback.
+
+### 2. Bring an existing token
+
+Use this when you already manage a token outside Hack:
+
+```bash
+hack x github connect --profile default --token-env HACK_GITHUB_APP_TOKEN
+
+# or:
+printf "%s" "$HACK_GITHUB_APP_TOKEN" | hack x github connect --profile default --stdin
+```
+
+### 3. Use GitHub App credentials for least privilege
+
+Use this when you want installation-scoped auth that can refresh automatically:
+
+```bash
+hack x github connect \
+  --profile work \
+  --set-default \
+  --app-id 12345 \
+  --installation-id 67890 \
+  --private-key-env HACK_GITHUB_APP_PRIVATE_KEY
+```
+
+## Common Commands
+
+```bash
+hack x github profiles
+hack x github use --profile work
+hack x github status --profile work
+hack x github disconnect --profile work
+```
+
+PR creation/update:
+
+```bash
+hack x github pr-upsert \
+  --profile work \
+  --repo owner/repo \
+  --head my-branch \
+  --base main \
+  --title "My PR" \
+  --body "Details"
+```
+
+## Profile Selection
+
+Hack resolves the GitHub profile in this order:
+
+1. `--profile`
+2. `controlPlane.routing.overrides.github.profile`
+3. `controlPlane.extensions["dance.hack.github"].config.defaultProfile`
+
+Use separate profiles when you need different GitHub identities for different repos or automations.
+
+## Browser Auth Requirements
+
+`hack x github oauth-connect` needs the GitHub OAuth app config in global Hack config:
+
+- `controlPlane.extensions["dance.hack.github"].config.oauthClientId`
+- `controlPlane.extensions["dance.hack.github"].config.oauthClientSecretAuthRef`
+
+The referenced secret is stored in the OS keychain under service `hack-github-auth`.
diff --git a/docs/guides/remote-node-laptop-e2e.md b/docs/guides/remote-node-laptop-e2e.md
index 0ff9c3864..da26c2de3 100644
--- a/docs/guides/remote-node-laptop-e2e.md
+++ b/docs/guides/remote-node-laptop-e2e.md
@@ -129,6 +129,10 @@ Expected:
 
 ### Private repo bootstrap behavior (default, no manual copy)
 
+GitHub is optional for public repos or for private repos when the remote machine already has working
+Git credentials. It becomes required only when Hack needs to supply controller-side credentials for
+private GitHub clone fallback.
+
 Workspace bootstrap now uses this order automatically:
 1. Attempt clone with the remote machine's existing Git credentials.
 2. If clone fails and origin is GitHub, retry with controller GitHub token auth (from `hack x github connect` or `HACK_GITHUB_APP_TOKEN`).
diff --git a/docs/guides/remote-node-quickstart.md b/docs/guides/remote-node-quickstart.md
index d4af4bc71..946d4b19a 100644
--- a/docs/guides/remote-node-quickstart.md
+++ b/docs/guides/remote-node-quickstart.md
@@ -9,6 +9,9 @@ Use this guide to connect one remote machine as a `hack` execution node and run
 3. SSH access from host to remote (`user@host`).
 4. A reachable gateway endpoint on the remote (`http://<host>:7788` or tailnet URL).
 
+GitHub is optional here. You only need it if the repo is private on GitHub and the remote machine
+cannot already clone it with its own credentials.
+
 ## Step 1: prepare the remote machine
 
 Run on the remote machine:
@@ -70,6 +73,15 @@ hack dispatch run \
   -- "pwd"
 ```
 
+If this project is a private GitHub repo and the remote node cannot clone it directly, connect
+GitHub on the controller first:
+
+```bash
+hack x github oauth-connect --profile work --set-default
+```
+
+See [GitHub workflows](github-workflows.md) for the full optional-vs-required breakdown.
+
 Optional remote check:
 
 ```bash
@@ -102,3 +114,6 @@ You can do the same flow in Hack Desktop:
 4. Local project URL fails after remote dispatch (`https://<project>.hack`):
    - run `hack node routes status` then `hack node routes repair`.
    - if global proxy is down, run `hack global up` and retry.
+5. Remote bootstrap fails on a private GitHub repo:
+   - connect GitHub on the controller so Hack can retry clone with controller credentials.
+   - run `hack x github oauth-connect --profile work --set-default` and retry.
diff --git a/src/control-plane/extensions/github/commands.ts b/src/control-plane/extensions/github/commands.ts
index e554ded30..22a9e7f91 100644
--- a/src/control-plane/extensions/github/commands.ts
+++ b/src/control-plane/extensions/github/commands.ts
@@ -102,7 +102,7 @@ export const GITHUB_COMMANDS: readonly ExtensionCommand[] = [
   {
     name: "connect",
     summary:
-      "Store a GitHub token in keychain and persist profile config (direct or App exchange)",
+      "Connect GitHub for PR automation or remote repo bootstrap (token or App)",
     scope: "global",
     handler: async ({ ctx, args }) => {
       const parsed = parseConnectArgs({ args });
@@ -181,7 +181,7 @@ export const GITHUB_COMMANDS: readonly ExtensionCommand[] = [
   {
     name: "oauth-connect",
     summary:
-      "Open browser GitHub auth via gh CLI, import token, and bind selected profile",
+      "Connect GitHub in a browser and import a profile for Hack workflows",
     scope: "global",
     handler: async ({ ctx, args }) =>
       await handleGitHubOAuthConnectCommand({

From efd104bfbbfb7462f91e1adf9985b5a126fa9774 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:33:27 +0000
Subject: [PATCH 112/134] docs: split docs into core beta and reference paths

---
 README.md                   | 10 ++--
 docs/README.md              | 95 ++++++++++++++++++++-----------------
 docs/beta.md                | 33 +++++++++++++
 docs/cli.md                 |  4 ++
 docs/core.md                | 36 ++++++++++++++
 docs/extensions.md          |  4 ++
 docs/gateway-api.md         |  3 ++
 docs/gateway.md             |  3 ++
 docs/guides/init-project.md |  4 ++
 docs/reference.md           | 30 ++++++++++++
 docs/supervisor.md          |  4 ++
 11 files changed, 178 insertions(+), 48 deletions(-)
 create mode 100644 docs/beta.md
 create mode 100644 docs/core.md
 create mode 100644 docs/reference.md

diff --git a/README.md b/README.md
index 31d64cc93..fa851952a 100644
--- a/README.md
+++ b/README.md
@@ -388,11 +388,11 @@ Docs: `docs/supervisor.md`.
 
 ## Docs
 
-Start here:
-- `docs/README.md` (index)
-- `docs/architecture.md`
-- `docs/gateway.md`
-- `docs/extensions.md`
+Docs are split into three paths:
+- `docs/README.md` - hub
+- `docs/core.md` - default local product story
+- `docs/beta.md` - remote and control-plane workflows
+- `docs/reference.md` - extensions, commands, and API reference
 
 ## Agent setup (CLI-first)
 
diff --git a/docs/README.md b/docs/README.md
index e493be242..e18aa532e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,45 +1,54 @@
 # Docs
 
-This directory contains the public documentation for hack. Specs remain in `SPECS/` (working notes).
-
-## Core docs
-
-- [CLI reference](cli.md)
-- [Architecture](architecture.md)
-- [Sessions](sessions.md) - mux session management (tmux or zellij) + API
-- [Env & secrets](env.md) - env contract + `.hack/.env` + OS keychain secrets
-- [Lifecycle](lifecycle.md) - project startup hooks + managed host processes
-- [Gateway overview](gateway.md)
-- [Gateway API](gateway-api.md)
-- [Supervisor](supervisor.md)
-- [Extensions](extensions.md)
-- [Control-plane SDK](sdk.md)
-
-Monorepo note:
-- Root scripts orchestrate workspace tasks through Turbo.
-- Package-local commands remain available via `bun run --cwd <workspace> <script>`.
-
-Quick diagnostics:
-- `hack usage` (resource usage across running projects)
-- `hack usage --watch` (live resource trends)
-- `hack node routes status` (controller-side remote route bridge state)
-- `hack node routes repair` (re-apply persisted remote route bridge routes)
-
-## Guides
-
-- Start here (first remote node in ~10 minutes):
-  - [Remote node quickstart](guides/remote-node-quickstart.md)
-  - [Run laptop-to-laptop node pairing e2e](guides/remote-node-laptop-e2e.md)
-  - [Bootstrap a remote node on Railway](guides/remote-node-railway.md)
-- Remote setup (one command): `hack remote setup`
-- [Initialize a project](guides/init-project.md)
-- [Global settings](guides/global-settings.md)
-- [Tickets (git-backed)](guides/tickets.md)
-- [Expose the gateway over SSH](guides/remote-ssh.md)
-- [Expose the gateway with Cloudflare](guides/remote-cloudflare.md)
-- [Expose the gateway with Tailscale](guides/remote-tailscale.md)
-- [Run remote supervisor jobs](guides/remote-supervisor.md)
-- [Run a remote node via container image](guides/remote-node-container.md)
-- [Bootstrap a remote node on Railway](guides/remote-node-railway.md)
-- [Bootstrap auth-broker with Neon + Railway](guides/auth-broker-neon-bootstrap.md)
-- [Create a new extension](guides/create-extension.md)
+This directory contains the public documentation for `hack`.
+
+The docs are split into three areas so the default path stays on core local workflows.
+
+## Choose a path
+
+### [Core docs](core.md)
+
+Use this path for the main product story:
+
+- local project setup
+- isolated runtime orchestration
+- stable local hostnames
+- env and secret management
+- lifecycle hooks
+- persistent sessions
+
+Start here if you want to understand and use `hack` without remote or beta complexity by default.
+
+### [Beta workflows](beta.md)
+
+Use this path when you intentionally want remote and control-plane features:
+
+- gateway exposure
+- remote nodes
+- remote execution
+- remote supervisor jobs
+
+Beta material stays accessible, but it is explicitly labeled and separated from the default path.
+
+### [Extensions & reference](reference.md)
+
+Use this path for:
+
+- full command reference
+- extension configuration and authoring
+- tickets and integrations
+- gateway API and SDK details
+
+This section is easy to find, but it does not lead the product story.
+
+## Quick links
+
+- New to `hack`: [Core docs](core.md)
+- Ready for remote workflows: [Beta workflows](beta.md)
+- Looking for command or API details: [Extensions & reference](reference.md)
+
+## Repo notes
+
+- Specs remain in `SPECS/` as working notes
+- Root scripts orchestrate workspace tasks through Turbo
+- Package-local commands remain available via `bun run --cwd <workspace> <script>`
diff --git a/docs/beta.md b/docs/beta.md
new file mode 100644
index 000000000..d8d7321f7
--- /dev/null
+++ b/docs/beta.md
@@ -0,0 +1,33 @@
+# Beta Workflows
+
+This section holds remote and control-plane features that are still evolving.
+
+Start in [Core docs](core.md) first if you are new to `hack`. Beta workflows build on the core
+local model instead of replacing it.
+
+## Beta entry points
+
+- [Gateway overview](gateway.md)
+- [Remote node quickstart](guides/remote-node-quickstart.md)
+- [Run laptop-to-laptop node pairing e2e](guides/remote-node-laptop-e2e.md)
+- [Bootstrap a remote node on Railway](guides/remote-node-railway.md)
+- [Run a remote node via container image](guides/remote-node-container.md)
+- [Expose the gateway over SSH](guides/remote-ssh.md)
+- [Expose the gateway with Cloudflare](guides/remote-cloudflare.md)
+- [Expose the gateway with Tailscale](guides/remote-tailscale.md)
+- [Run remote supervisor jobs](guides/remote-supervisor.md)
+
+## Before you start
+
+- Keep your local project flow working first: `hack init`, `hack up --detach`, `hack open`
+- Treat remote exposure and node orchestration as opt-in
+- Expect some pages here to be marked experimental while the surface is still settling
+
+## Need lower-level detail?
+
+Use [Extensions & reference](reference.md) for:
+
+- [Gateway API](gateway-api.md)
+- [Supervisor](supervisor.md)
+- [Control-plane SDK](sdk.md)
+- [CLI reference](cli.md)
diff --git a/docs/cli.md b/docs/cli.md
index d46d6c85c..d07382e2c 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -3,6 +3,10 @@
 This reference mirrors the CLI spec in `src/cli/spec.ts`.
 Run `hack help` or `hack help <command>` for interactive help.
 
+This is the full command reference, including beta and extension surfaces.
+If you are new to `hack`, start with [Core docs](core.md) and come back here when you need
+command-level detail.
+
 ## Conventions
 
 - Commands that accept both `--path` and `--project` treat them as mutually exclusive.
diff --git a/docs/core.md b/docs/core.md
new file mode 100644
index 000000000..00b6f5608
--- /dev/null
+++ b/docs/core.md
@@ -0,0 +1,36 @@
+# Core Docs
+
+Core docs are the default path through `hack`.
+
+This section stays focused on local project orchestration: initialize a repo, run it on an isolated
+network, reach it on stable local hostnames, manage env and lifecycle, and keep working sessions
+alive. You do not need gateway, remote nodes, or extension setup to use this path.
+
+## Start here
+
+- [Initialize a project](guides/init-project.md)
+- [Architecture](architecture.md)
+- [Env & secrets](env.md)
+- [Lifecycle](lifecycle.md)
+- [Sessions](sessions.md)
+
+## Day-to-day core workflows
+
+- Install + quick start: [root README](../README.md)
+- Local runtime checks:
+  - `hack up --detach`
+  - `hack open`
+  - `hack logs --pretty`
+  - `hack status`
+
+## When to leave core
+
+Move to [Beta workflows](beta.md) when you intentionally want:
+
+- gateway exposure
+- remote nodes
+- remote execution
+- remote supervisor jobs
+
+Move to [Extensions & reference](reference.md) when you need the full command table, extension
+authoring details, or API-level reference material.
diff --git a/docs/extensions.md b/docs/extensions.md
index b4c8b0a81..869f2c86d 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -3,6 +3,10 @@
 This doc defines the extension surface area for `hack` and how extension commands are authored,
 configured, and dispatched.
 
+This is reference material, not the default onboarding path.
+Start with [Core docs](core.md) if you are learning `hack`, or use [Beta workflows](beta.md) if
+you are intentionally enabling remote/control-plane features.
+
 ## Quick start (one command)
 
 If you just want remote access working, start here:
diff --git a/docs/gateway-api.md b/docs/gateway-api.md
index bbe4cd563..ed2239199 100644
--- a/docs/gateway-api.md
+++ b/docs/gateway-api.md
@@ -4,6 +4,9 @@ The gateway exposes a small, authenticated HTTP/WS surface for remote orchestrat
 designed for structured workflows (jobs + log streaming + shells) and keeps write access
 opt-in with explicit guardrails.
 
+This is reference for the beta remote surface. Use [Beta workflows](beta.md) for the guided path
+and [Core docs](core.md) for the default local product story.
+
 > ⚠️ Experimental: remote exposure steps are still being validated end-to-end.
 
 ## Security model (read this first)
diff --git a/docs/gateway.md b/docs/gateway.md
index 9a367e2a0..246f42a1d 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -4,6 +4,9 @@ The gateway exposes a small HTTP/WS surface on top of `hackd` so you can orchest
 logs, and open shells remotely. It is disabled by default and binds to `127.0.0.1` unless you
 explicitly expose it through SSH, Cloudflare, or Tailscale.
 
+This is a beta workflow. Start with [Core docs](core.md) if you are new to `hack`, and use
+[Beta workflows](beta.md) for the rest of the remote path.
+
 > ⚠️ Experimental: the remote exposure guides below are still being validated end-to-end.
 
 ## Concepts
diff --git a/docs/guides/init-project.md b/docs/guides/init-project.md
index d91282b81..13622d3e0 100644
--- a/docs/guides/init-project.md
+++ b/docs/guides/init-project.md
@@ -25,3 +25,7 @@ Note:
 - Inside containers, `localhost` points at the container itself. Update any `localhost:PORT` references to:
   - HTTP services via `https://*.hack` hostnames (matching your Caddy labels)
   - non-HTTP services via Compose service hostnames (e.g. `db`, `redis`)
+
+When the local path is working and you intentionally want remote execution or gateway exposure, move
+to [Beta workflows](../beta.md). For full command lookup and extension docs, use
+[Extensions & reference](../reference.md).
diff --git a/docs/reference.md b/docs/reference.md
new file mode 100644
index 000000000..8376d3c67
--- /dev/null
+++ b/docs/reference.md
@@ -0,0 +1,30 @@
+# Extensions & Reference
+
+This section is for command lookup, extension surfaces, APIs, and implementation-oriented docs.
+
+It is intentionally separate from the primary product story so command tables and optional surfaces
+do not compete with the default `hack` onboarding path.
+
+## Command and operator reference
+
+- [CLI reference](cli.md)
+- [Global settings](guides/global-settings.md)
+
+## Extensions and integrations
+
+- [Extensions](extensions.md)
+- [Tickets (git-backed)](guides/tickets.md)
+- [Create a new extension](guides/create-extension.md)
+- [Linear integration architecture](guides/linear-integration-architecture.md)
+- [Auth broker Neon bootstrap](guides/auth-broker-neon-bootstrap.md)
+
+## Remote APIs and SDKs
+
+- [Gateway API](gateway-api.md)
+- [Supervisor](supervisor.md)
+- [Control-plane SDK](sdk.md)
+
+## Choose a different path
+
+- If you are setting up or learning `hack`, start with [Core docs](core.md)
+- If you are intentionally enabling remote execution or exposure, go to [Beta workflows](beta.md)
diff --git a/docs/supervisor.md b/docs/supervisor.md
index 559ba4db0..0edc9c15b 100644
--- a/docs/supervisor.md
+++ b/docs/supervisor.md
@@ -4,6 +4,10 @@ The supervisor is the execution engine behind remote workflows. It can run comma
 stream logs/events, and host PTY-backed shells. The CLI exposes it locally via `hack x supervisor`
 and remotely through the gateway API.
 
+This page documents a beta-adjacent execution surface.
+Use [Beta workflows](beta.md) for the guided remote path and [Extensions & reference](reference.md)
+for the rest of the command and API material.
+
 ## Local usage
 
 ```bash

From 263d75669f6d4ebdc52c9f1e315d70947adefe63 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:33:48 +0000
Subject: [PATCH 113/134] docs: add agent-native runtime requirements

---
 ...gent-native-runtime-requirements-design.md | 258 ++++++++++++++++++
 1 file changed, 258 insertions(+)
 create mode 100644 docs/plans/2026-03-22-agent-native-runtime-requirements-design.md

diff --git a/docs/plans/2026-03-22-agent-native-runtime-requirements-design.md b/docs/plans/2026-03-22-agent-native-runtime-requirements-design.md
new file mode 100644
index 000000000..5b5eaa3cf
--- /dev/null
+++ b/docs/plans/2026-03-22-agent-native-runtime-requirements-design.md
@@ -0,0 +1,258 @@
+# Agent-Native Runtime Requirements For Hack
+
+## Context
+
+Hack already supports the workflows that the future runtime has to serve:
+
+- branch-scoped local environments with `hack up --branch <name>`
+- isolated agent sessions with `hack session start <project> --new --name agent-1`
+- managed host lifecycle processes declared in `.hack/hack.config.json`
+- gateway and supervisor jobs/shells for remote control-plane access
+- controller-to-node execution with workspace bootstrap, branch ensure, route bridging, and optional Mutagen sync
+- remote devcontainer startup on node workspaces
+
+The runtime question is not whether Hack needs containers in the abstract. It is whether the runtime can preserve these workflows without pushing users back toward ad hoc Docker, tmux, SSH, port-forwarding, and one-off bootstrap scripts.
+
+The linked Linear spec was not retrievable anonymously during this session, so this requirements set is derived from the current repo docs and command surface.
+
+## Source Workflows
+
+These are the concrete workflows the runtime must satisfy.
+
+### WF-1: Parallel branch environments on one machine
+
+One repo can run multiple branch instances at once. Each instance needs separate routing, service state, logs, and cleanup while still feeling like the same Hack project.
+
+Examples:
+
+- `hack up --branch feature-a --detach`
+- `hack open --branch feature-a`
+- `hack logs --branch feature-a`
+- `hack down --branch feature-a`
+
+### WF-2: Agent-heavy local work with isolated sessions
+
+Agents need durable PTYs that outlive one CLI invocation. They also need cheap, isolated session creation so a main agent and several subagents can work in parallel without sharing one terminal or stomping on each other.
+
+Examples:
+
+- `hack session start <project>`
+- `hack session start <project> --new --name agent-1`
+- `hack session exec <session> "bun test"`
+- `hack session capture <session>`
+
+### WF-3: Host-side helpers managed as part of project runtime
+
+Many projects need host-native helpers that are not container workloads: auth bootstrap, local tunnels, proxies, and credential refresh loops. Hack treats these as part of runtime, not as separate user-managed tabs.
+
+Examples:
+
+- `lifecycle.up.before`
+- `lifecycle.processes`
+- `hack logs <lifecycle-process>`
+
+### WF-4: Remote control-plane execution
+
+Remote clients, desktop surfaces, and agents need a stable API for jobs, shells, sessions, env resolution, and project discovery. This has to keep working when the caller is not on the same machine as the repo checkout.
+
+Examples:
+
+- `GET /v1/projects`
+- `POST /control-plane/projects/:projectId/jobs`
+- `WS /control-plane/projects/:projectId/jobs/:jobId/stream`
+- `POST /control-plane/projects/:projectId/shells`
+
+### WF-5: Controller local-edit, remote-run
+
+Hack can run a project on a remote node while the developer edits locally. That means the runtime has to support workspace bootstrap, branch ensure, local-to-remote sync, and local route bridging back to the remote project.
+
+Examples:
+
+- `hack up --target auto`
+- `hack dispatch run --project <name|id> --node default --branch <branch> --runner generic -- "pwd"`
+- `POST /v1/node/workspaces/ensure`
+- `hack node routes status`
+
+### WF-6: Fresh-node bootstrap and devcontainers
+
+Hack can bring up a new node, clone a repo, enable gateway access, and optionally start a devcontainer in the resolved workspace. The runtime cannot assume the workspace already exists or that bootstrap is manual.
+
+Examples:
+
+- container bootstrap via `hackdance/hack:latest`
+- `POST /v1/node/devcontainers/up`
+- `hack node devcontainer up --node <node-id> --project <project> --branch <branch>`
+
+## Mandatory Requirements
+
+These are architecture gates. If an option cannot satisfy them, it is the wrong runtime for Hack.
+
+### 1. Project Instance Isolation
+
+- The runtime unit must be a Hack project instance, not just a raw container.
+- A project instance must be addressable by at least:
+  - project id or name
+  - workspace root
+  - branch instance identity
+- Two branch instances of the same project must be able to run concurrently on one machine without host-port collisions, network alias collisions, log collisions, or teardown ambiguity.
+- Cleanup must be instance-scoped. `hack down --branch foo` must not disturb the base instance or other branches.
+- Runtime-generated names, mounts, and caches must be deterministic enough for Hack to rediscover and manage them after CLI or daemon restart.
+
+Why this is Hack-specific:
+Hack already exposes branch instances as a user-facing concept. The runtime has to preserve that abstraction instead of flattening everything into one mutable project.
+
+### 2. First-Class Hack Networking
+
+- Each project instance must be routable through Hack hostnames without manual per-service port management.
+- The runtime must support the equivalent of Hack’s current label-driven ingress model so `hack open`, browser access, and OAuth callback flows keep using stable hostnames.
+- Containers and host-managed helpers must be able to resolve and trust the same Hack URLs from inside the runtime.
+- Dynamic route repair is mandatory. If proxy IP, runtime identity, or bridge state changes, Hack must be able to detect drift and reconcile it.
+- Local bridge routes for remote execution are mandatory. A controller machine must be able to keep `https://<project>.hack` working while the actual service runs on a remote node.
+
+Why this is Hack-specific:
+Hack is not just starting services. It is creating a stable local domain model that spans browser access, container-to-container calls, host helpers, and remote-node bridge routes.
+
+### 3. Sessions As Runtime Objects
+
+- Persistent sessions must remain first-class even if the container runtime changes.
+- The runtime must support durable named execution homes for:
+  - human terminals
+  - agent shells
+  - lifecycle-owned host processes
+- Sessions need create, list, exec, capture, tail, input, and stop operations through Hack’s local API surface.
+- Session identity must survive CLI disconnects and be discoverable after daemon restart.
+- Long-lived PTYs and one-shot jobs must be separate primitives. Hack needs both.
+
+Why this is Hack-specific:
+Hack is explicitly agent-native. Durable PTYs are part of the product surface, not a debugging convenience.
+
+### 4. Cheap Concurrent Execution For Subagents
+
+- The runtime must make it cheap to create multiple isolated execution contexts under the same project instance.
+- Subagents need isolated cwd, env, and terminal state even when they share the same branch workspace.
+- The runtime must support both:
+  - short-lived command jobs with streamed output and exit status
+  - long-lived interactive shells
+- Runs need stable ids plus persisted metadata such as project, branch, runner, ticket, and timestamps.
+- Cancellation must be explicit and reliable. Orphaned jobs or zombie shells are not acceptable.
+
+Why this is Hack-specific:
+Hack is trying to coordinate real multi-agent work, not just a single foreground shell.
+
+### 5. Host-Native Lifecycle Integration
+
+- The runtime must treat host-native helper processes as part of project runtime state.
+- Hack must be able to start, monitor, log, and stop lifecycle processes using the same project instance model as services.
+- Lifecycle failure must participate in startup correctness. If a required hook fails, runtime startup must fail clearly.
+- Lifecycle teardown must be deterministic and scoped to the relevant branch or project instance.
+
+Why this is Hack-specific:
+Projects regularly need host-only auth, tunnel, and proxy processes. A runtime that only models containers would force users back to unmanaged terminal tabs.
+
+### 6. Remote Workspace Bootstrap And Branch Ensure
+
+- Given only project identity plus bootstrap hints, a remote node must be able to:
+  - resolve or create a workspace
+  - clone the repo if needed
+  - ensure the requested branch
+  - register the workspace back into Hack’s project map
+- Bootstrap must be idempotent and diagnosable. Failures need machine-readable reasons such as auth source, clone failure, or origin mismatch.
+- The runtime must support controller local-edit, remote-run flows without assuming manual SSH setup beyond Hack’s pairing/bootstrap path.
+- Workspace identity on the node must remain stable enough for later dispatch, session reuse, and devcontainer startup.
+
+Why this is Hack-specific:
+Hack treats remote nodes as an extension of local development, not as generic CI workers.
+
+### 7. Control-Plane Native Runtime Introspection
+
+- The runtime must expose enough local state for Hack to answer:
+  - what projects and instances exist
+  - which services, sessions, jobs, and lifecycle processes are active
+  - how to attach or stream into them
+  - whether the runtime is healthy, stale, or degraded
+- This data must be available through a local API that the CLI, desktop app, and remote gateway can share.
+- The gateway must continue to enforce project opt-in, token scopes, and write gating on top of the runtime.
+- Runtime operations that mutate state must remain auditable.
+
+Why this is Hack-specific:
+Hack’s control plane is already part of the product architecture. The runtime has to be legible to that control plane, not hidden behind opaque shell-outs.
+
+### 8. Recovery As A First-Class Capability
+
+- The runtime must detect identity drift and reset conditions instead of silently failing.
+- Hack must be able to distinguish:
+  - runtime unavailable
+  - runtime reset
+  - stale cached state
+  - incompatible daemon or control-plane state
+- Jobs, shells, sessions, and route bridges must support reconnect or repair by stable id where possible.
+- Recovery must prefer safe auto-repair for stale local state and explicit guidance for unsafe cases.
+- A daemon restart must not make active project instances undiscoverable.
+
+Why this is Hack-specific:
+Hack already has daemon fallback, remote bridging, and session semantics. Recovery failures here are visible product failures, not just operator inconvenience.
+
+## Nice-To-Have Requirements
+
+These materially improve the runtime, but they should not block initial architecture selection.
+
+### 1. First-Class Devcontainer Tracking
+
+- Model node devcontainers as tracked runtime objects rather than opaque shell commands.
+- Preserve attach hints and lifecycle metadata so IDE handoff is deterministic.
+
+### 2. Policy-Aware Placement
+
+- Let Hack choose between local runtime, remote node, and provider bootstrap using labels, profiles, or policy without changing the project abstraction.
+
+### 3. Resource Accounting Per Project Instance
+
+- Expose CPU, memory, disk, and network attribution per project instance and branch instance.
+- Surface quota and pressure signals to CLI and desktop.
+
+### 4. Warm Snapshot Or Fast Resume
+
+- Support pausing and resuming branch instances or remote workspaces faster than full cold boot.
+- This is valuable for agent-heavy workflows but not required to prove correctness.
+
+### 5. Better Cross-Machine State Portability
+
+- Make it easier to move project runtime state, env contracts, and workspace metadata between controller and node without rebuilding everything from scratch.
+
+## Explicit Non-Requirements
+
+These should not distort the architecture discussion.
+
+- Hack does not need a general multi-tenant cluster scheduler.
+- Hack does not need Kubernetes compatibility as a goal by itself.
+- Hack does not need to replace tmux/zellij semantics with an entirely different UX if the current session model already works.
+- Hack does not need a runtime that only optimizes container startup while breaking hostname stability, session durability, or remote-node bootstrap.
+
+## Architecture Evaluation Scorecard
+
+A candidate runtime should be evaluated against these questions before implementation work starts.
+
+### Reject If Any Answer Is No
+
+1. Can it run multiple branch instances of one project concurrently with deterministic routing and cleanup?
+2. Can Hack continue to present stable `*.hack` hostnames locally, inside services, and through remote route bridges?
+3. Can it host durable named sessions and interactive shells that survive CLI disconnects?
+4. Can it support many concurrent subagent jobs and shells without shared-terminal interference?
+5. Can it model host-native lifecycle processes as part of project runtime state?
+6. Can a remote node bootstrap a missing workspace, ensure a branch, and expose it back through the control plane?
+7. Can Hack observe runtime state through a local API instead of best-effort scraping only?
+8. Can it recover cleanly from runtime resets, stale state, and daemon restarts without losing project identity?
+
+### Strong Preference Questions
+
+1. Does the design reduce the amount of Docker-specific glue Hack has to maintain today?
+2. Does it make remote-node and local-runtime code paths more uniform instead of more divergent?
+3. Does it reduce the amount of ad hoc state that lives outside Hack’s project and control-plane models?
+4. Does it make job, shell, session, and lifecycle logging more coherent?
+5. Does it make architecture simpler for the desktop app, CLI, and gateway consumers?
+
+## Recommendation For Option Evaluation
+
+When comparing runtime architectures, score them against the mandatory set first and only discuss performance, implementation language, or operator simplicity after that gate passes.
+
+The main mistake to avoid is choosing a runtime that is good at generic container orchestration but weak at Hack’s actual product surface: branch instances, agent sessions, host helpers, remote-node bootstrap, and control-plane-visible recovery.

From 92af1872a011383cc4663d43d13d79eabb760c25 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:33:55 +0000
Subject: [PATCH 114/134] docs(tickets): define git portability contract

---
 docs/guides/tickets.md                        |  28 +++
 ...-tickets-storage-git-portability-design.md | 221 ++++++++++++++++++
 2 files changed, 249 insertions(+)
 create mode 100644 docs/plans/2026-03-22-tickets-storage-git-portability-design.md

diff --git a/docs/guides/tickets.md b/docs/guides/tickets.md
index 279f60a02..78caf0340 100644
--- a/docs/guides/tickets.md
+++ b/docs/guides/tickets.md
@@ -138,6 +138,34 @@ In your project repo:
 - `.hack/tickets/git/bare.git` — a bare repo used to manage the tickets ref
 - `.hack/tickets/git/worktree` — a worktree used for reading/writing ticket data
 
+### Durability and portability
+
+The durable portable layer is the event log in the tickets ref.
+
+- `.hack/tickets/events/*.jsonl` is the source of truth
+- `list`, `show`, and related views are rebuilt by replaying the event log
+- deleting local projection state must not lose ticket history
+
+Rebuildable local state includes:
+
+- `.hack/tickets/git/bare.git`
+- `.hack/tickets/git/worktree`
+- `.hack/tickets/create.lock`
+
+These paths exist to coordinate sync and local writes. They can be recreated from the repo and the tickets ref.
+
+### Hidden refs and legacy branch compatibility
+
+By default, tickets sync to the hidden ref `refs/hack/tickets`.
+
+Compatibility rules:
+
+- the CLI fetches the hidden ref first
+- if the hidden ref is missing, it falls back to the legacy branch ref `refs/heads/hack/tickets`
+- when legacy ref data is imported, event logs are deduped by `eventId` and normalized before the next push
+
+If your remote rejects hidden refs, set `controlPlane.tickets.git.refMode` to `heads` and use `refs/heads/hack/tickets` instead.
+
 ## Configuration
 
 Tickets git configuration lives under `controlPlane.tickets.git`.
diff --git a/docs/plans/2026-03-22-tickets-storage-git-portability-design.md b/docs/plans/2026-03-22-tickets-storage-git-portability-design.md
new file mode 100644
index 000000000..25a4b0144
--- /dev/null
+++ b/docs/plans/2026-03-22-tickets-storage-git-portability-design.md
@@ -0,0 +1,221 @@
+# Tickets Storage Git Portability Design
+
+## Context
+
+Tickets already rely on git as the durable transport layer:
+
+- the canonical ticket history is an append-only event log stored under `.hack/tickets/events`
+- sync uses a dedicated tickets ref, hidden by default as `refs/hack/tickets`
+- the local store rebuilds ticket summaries, comments, review notes, checkpoints, and conflicts by replaying the event log
+
+The normalization work adds a clearer distinction between a durable journal and derived projection state. That split must not weaken the reasons tickets are useful today:
+
+- a repo can be cloned and moved between machines without losing ticket history
+- ticket work continues offline
+- hidden-ref sync remains viable for existing users and existing remotes
+
+The relevant current implementation lives in:
+
+- `src/control-plane/extensions/tickets/store.ts`
+- `src/control-plane/extensions/tickets/tickets-git-channel.ts`
+- `tests/tickets-store.test.ts`
+- `tests/tickets-git-channel.test.ts`
+
+I could not access the linked Linear spec from this workspace, so this design is anchored to the current repository behavior and the acceptance criteria in `HACK-451`.
+
+## Goals
+
+- Keep git as the durable, portable layer for tickets.
+- Make the durable-vs-derived boundary explicit for the normalized storage model.
+- Ensure projection state can be rebuilt on any machine from portable data.
+- Preserve the existing hidden-ref workflow and legacy branch compatibility.
+
+## Non-Goals
+
+- Changing the default ref name or removing hidden refs.
+- Making projection snapshots authoritative.
+- Requiring users to commit local caches or git plumbing.
+- Breaking existing `refs/heads/hack/tickets` users during migration.
+
+## Portability Contract
+
+### Durable and portable through git
+
+The tickets ref remains the canonical portable payload. It should contain only data that must survive machine changes and offline work:
+
+- the append-only journal
+- durable metadata required to interpret the journal
+  - storage schema version
+  - projection format version
+  - migration markers when needed
+- durable artifacts that cannot be recreated from the journal alone
+
+For the current implementation, the journal is the existing monthly JSONL event log under `.hack/tickets/events/events-YYYY-MM.jsonl`.
+
+For the normalized model, the journal may move or be segmented differently, but it keeps the same contract:
+
+- append-only
+- idempotent merge by stable entry identity
+- sufficient to rebuild user-visible ticket history
+
+### Rebuildable local state
+
+Anything that can be deterministically recreated from the durable layer is local state, not portable state. This includes:
+
+- normalized projections
+- lookup indexes
+- caches
+- lock files
+- the tickets bare repo and tickets worktree used for sync plumbing
+
+In the current implementation that means:
+
+- `.hack/tickets/git/bare.git` is rebuildable git plumbing
+- `.hack/tickets/git/worktree` is rebuildable checkout state
+- `.hack/tickets/create.lock` is transient concurrency control
+
+In the normalized model, projection files may exist on disk for startup performance, but they remain disposable. Deleting them must never lose history.
+
+## Journal and Projection Rules
+
+### Canonical source of truth
+
+The journal is the only authoritative history.
+
+Projection state is authoritative for nothing. It exists to accelerate reads and to simplify queries, but every projected record must be traceable to journal entries.
+
+### Rebuild guarantee
+
+A machine with only:
+
+- the git repo
+- the tickets ref contents
+- the current CLI version
+
+must be able to rebuild ticket state without network access.
+
+That rebuild must recover:
+
+- ticket summaries
+- comments
+- review notes
+- sync checkpoints
+- sync conflicts and their resolutions
+
+### Projection invalidation
+
+Projection state must be discarded and rebuilt when any of the following changes:
+
+- journal contents change
+- storage schema version changes
+- projection format version changes
+- repair detects corruption or partial local state
+
+The rebuild path should prefer correctness over incremental cleverness. If validity is uncertain, replay the journal again.
+
+## Hidden-Ref Sync Contract
+
+### Default transport
+
+The default portable ref remains:
+
+- hidden mode: `refs/hack/tickets`
+- heads mode fallback: `refs/heads/hack/tickets`
+
+The remote tickets ref continues to carry only the portable tickets payload, not local caches or unrelated repo files.
+
+### Compatibility with existing users
+
+Current behavior should remain the migration baseline:
+
+1. Fetch `refs/hack/tickets` first.
+2. If it does not exist, fall back to `refs/heads/hack/tickets`.
+3. If legacy branch data is present, merge it into the current local tickets state by journal identity, then normalize.
+4. Push back to the ref that matches the checked-out source until repair or explicit config changes move the repo to the hidden ref.
+
+This preserves portability for users who already have:
+
+- hidden refs on the remote
+- legacy branch refs on the remote
+- local clones that have seen one form but not the other
+
+### Merge semantics
+
+Sync merges journal data, not projections.
+
+That means:
+
+- dedupe by stable journal entry id
+- keep deterministic ordering
+- rebuild projections after merge
+
+Projections should never be merged line-by-line across machines. Replaying the merged journal is the conflict-resolution mechanism for derived state.
+
+### Offline behavior
+
+Offline writes append to the local journal and update local projections.
+
+When connectivity returns:
+
+- fetch remote journal state
+- merge by journal identity
+- rebuild projections locally
+- push the merged journal to the configured tickets ref
+
+This preserves local-first behavior without requiring a central service or always-on connectivity.
+
+## Ref Contents and Repo Hygiene
+
+The tickets ref should remain narrow and reviewable.
+
+Allowed durable contents:
+
+- journal files
+- storage manifests needed to interpret journal files
+- non-rebuildable ticket artifacts, if the storage model introduces them
+
+Disallowed contents:
+
+- projection caches
+- bare git internals
+- transient locks
+- unrelated files outside `.hack/tickets`
+
+The existing inspect and repair workflow already points in this direction by detecting non-ticket files and rebuilding a clean tickets-only ref. The normalized model should keep that invariant.
+
+## Migration Guidance
+
+### From current event logs
+
+Existing `.hack/tickets/events/*.jsonl` files remain valid durable journal input during migration.
+
+If the normalized model introduces a different journal layout, migration must:
+
+- preserve the old event history exactly
+- write enough metadata to identify the migrated schema
+- allow rebuild without needing the pre-migration local projection
+
+### From legacy branch refs
+
+Legacy `refs/heads/hack/tickets` remotes remain supported during migration.
+
+The migration-safe order is:
+
+1. fetch hidden ref
+2. fetch legacy ref when present
+3. merge journal entries idempotently
+4. rebuild projections
+5. optionally prune the legacy ref only after the hidden ref contains the same durable history
+
+## Validation
+
+- Clone a repo to a fresh machine, delete all local projection state, and verify ticket state rebuilds from the tickets ref alone.
+- Create local-only ticket mutations offline, then reconnect and verify merged journal history is preserved after sync.
+- Verify hidden-ref users continue to push and fetch `refs/hack/tickets`.
+- Verify legacy branch users still sync successfully before repair.
+- Verify repair can rebuild a tickets-only ref without losing journal history.
+- Verify no projection-only files are required to render `tickets list` or `tickets show`.
+
+## Decision
+
+The normalized tickets model keeps git portability by treating the journal as the only durable portable layer and projection state as rebuildable local state. Hidden-ref sync continues to transport the durable layer, with legacy branch compatibility preserved until users explicitly repair or reconfigure their repo.

From 2110ab9e2630cbe0a69a39f4ec9ab63937e4bf74 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:35:05 +0000
Subject: [PATCH 115/134] docs: align github cli summaries with workflow story

---
 src/control-plane/extensions/github/commands.ts  | 8 ++++----
 src/control-plane/extensions/github/extension.ts | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/control-plane/extensions/github/commands.ts b/src/control-plane/extensions/github/commands.ts
index 22a9e7f91..8c7e0fb1d 100644
--- a/src/control-plane/extensions/github/commands.ts
+++ b/src/control-plane/extensions/github/commands.ts
@@ -192,7 +192,7 @@ export const GITHUB_COMMANDS: readonly ExtensionCommand[] = [
   },
   {
     name: "disconnect",
-    summary: "Remove stored GitHub token from keychain",
+    summary: "Disconnect a GitHub profile from Hack",
     scope: "global",
     handler: async ({ ctx, args }) => {
       const parsed = parseDisconnectArgs({ args });
@@ -225,7 +225,7 @@ export const GITHUB_COMMANDS: readonly ExtensionCommand[] = [
   },
   {
     name: "status",
-    summary: "Show GitHub profile/config status",
+    summary: "Show which GitHub profile and auth Hack will use",
     scope: "global",
     handler: async ({ ctx, args }) =>
       await handleGitHubStatusCommand({
@@ -236,7 +236,7 @@ export const GITHUB_COMMANDS: readonly ExtensionCommand[] = [
   },
   {
     name: "profiles",
-    summary: "List configured GitHub auth profiles",
+    summary: "List available GitHub profiles and the active selection",
     scope: "global",
     handler: async ({ ctx, args }) => {
       const parsed = parseProfilesArgs({ args });
@@ -269,7 +269,7 @@ export const GITHUB_COMMANDS: readonly ExtensionCommand[] = [
   },
   {
     name: "use",
-    summary: "Set global default GitHub profile",
+    summary: "Set the default GitHub profile for Hack workflows",
     scope: "global",
     handler: async ({ ctx, args }) => {
       const parsed = parseProfileUseArgs({ args });
diff --git a/src/control-plane/extensions/github/extension.ts b/src/control-plane/extensions/github/extension.ts
index 16f06a1df..af6640fb9 100644
--- a/src/control-plane/extensions/github/extension.ts
+++ b/src/control-plane/extensions/github/extension.ts
@@ -7,7 +7,7 @@ export const GITHUB_EXTENSION: ExtensionDefinition = {
     version: "0.1.0",
     scopes: ["global", "project"],
     cliNamespace: "github",
-    summary: "GitHub App SCM integration for dispatch and PR automation",
+    summary: "Optional GitHub capability for PR automation and private repo bootstrap",
   },
   commands: GITHUB_COMMANDS,
 };

From 9cc075c2b10fbe5cf13f6aac0ee995c81f05a6e8 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:35:07 +0000
Subject: [PATCH 116/134] docs: align integration summaries with cli help

---
 docs/extensions.md      | 12 ++++++++++++
 src/commands/env.ts     |  2 +-
 src/commands/linear.ts  |  2 +-
 src/commands/session.ts |  2 +-
 src/commands/tickets.ts |  2 +-
 5 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/docs/extensions.md b/docs/extensions.md
index b4c8b0a81..9d338b31c 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -198,6 +198,10 @@ Options:
 
 ### GitHub extension (`hack x github`)
 
+Use GitHub when you want `hack` to help with branch sharing and pull request workflows from the same
+place you run local work. It becomes relevant once a branch is ready to open, update, or hand off for
+review.
+
 Connect or update a profile directly from token input:
 
 ```bash
@@ -275,6 +279,10 @@ Notes:
 
 ### Linear extension (`hack x linear`)
 
+Use Linear when your team plans work there and you want repo work to stay connected to Linear projects
+or issues. It becomes relevant when a repo should map to a Linear project or when you want manual sync
+between Linear and repo-local tickets.
+
 Linear integration supports multiple auth profiles, project-level binding, and manual sync in both
 directions between Linear issues and hack tickets.
 
@@ -502,6 +510,10 @@ Notes:
 
 ### Tickets extension (`hack x tickets`)
 
+Use tickets when you want lightweight work tracking that stays with the repo and is easy for agents or
+small teams to update. It becomes relevant as soon as you want to capture follow-up work without
+depending on a separate tracker.
+
 A lightweight, git-backed ticket log stored in `.hack/tickets/` and syncable via a dedicated git ref (`refs/hack/tickets` hidden by default).
 
 Guide: `docs/guides/tickets.md`
diff --git a/src/commands/env.ts b/src/commands/env.ts
index 844d0f8da..2676257e0 100644
--- a/src/commands/env.ts
+++ b/src/commands/env.ts
@@ -620,7 +620,7 @@ async function resolveEnvValue(opts: {
 
 export const envCommand = defineCommand({
   name: "env",
-  summary: "Manage project environment variables and secrets",
+  summary: "Set project env vars and local secrets",
   group: "Project",
   expandInRootHelp: true,
   options: [],
diff --git a/src/commands/linear.ts b/src/commands/linear.ts
index 7c3426f9c..e3806f629 100644
--- a/src/commands/linear.ts
+++ b/src/commands/linear.ts
@@ -13,7 +13,7 @@ import { logger } from "../ui/logger.ts";
  */
 const linearSpec = defineCommand({
   name: "linear",
-  summary: "Linear account connection and ticket sync",
+  summary: "Connect Linear and sync repo work with Linear projects/issues",
   description: [
     "Usage:",
     "  hack linear status",
diff --git a/src/commands/session.ts b/src/commands/session.ts
index 5d1a7a717..249e722e2 100644
--- a/src/commands/session.ts
+++ b/src/commands/session.ts
@@ -793,7 +793,7 @@ const handleTail = async ({
 
 export const sessionCommand = defineCommand({
   name: "session",
-  summary: "Manage tmux sessions for hack projects",
+  summary: "Keep reusable terminal workspaces alive",
   group: "Project",
   options: [],
   positionals: [],
diff --git a/src/commands/tickets.ts b/src/commands/tickets.ts
index 8e0d691fc..fa9971ebd 100644
--- a/src/commands/tickets.ts
+++ b/src/commands/tickets.ts
@@ -14,7 +14,7 @@ import { logger } from "../ui/logger.ts";
  */
 const ticketsSpec = defineCommand({
   name: "tickets",
-  summary: "Git-backed ticket management",
+  summary: "Track repo-local work without leaving git",
   description: [
     "Usage:",
     "  hack tickets list",

From 159c4fedfb94239044e36069b9e04f65f61efc8a Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:35:26 +0000
Subject: [PATCH 117/134] Define normalized Linear sync semantics

---
 .../guides/linear-integration-architecture.md |  15 +-
 ...linear-normalized-sync-semantics-design.md | 317 ++++++++++++++++++
 .../extensions/linear/commands.ts             |  49 +--
 tests/linear-commands.test.ts                 |  86 ++++-
 4 files changed, 421 insertions(+), 46 deletions(-)
 create mode 100644 docs/plans/2026-03-22-linear-normalized-sync-semantics-design.md

diff --git a/docs/guides/linear-integration-architecture.md b/docs/guides/linear-integration-architecture.md
index 02f3db9bd..34aeeca05 100644
--- a/docs/guides/linear-integration-architecture.md
+++ b/docs/guides/linear-integration-architecture.md
@@ -2,12 +2,15 @@
 
 This architecture keeps hack tickets lightweight while supporting bidirectional sync with Linear.
 
+The detailed field, authority, and conflict rules now live in
+`docs/plans/2026-03-22-linear-normalized-sync-semantics-design.md`.
+
 ## Goals
 
 1. Support multiple Linear accounts/profiles.
 2. Bind each hack project to a default Linear profile + project/team.
 3. Keep sync manual by default (`sync-issue`, `sync-project`) before enabling autosync.
-4. Preserve source-of-truth metadata (`owner`, `source`, `external*`, `tags`) on every synced ticket.
+4. Preserve normalized provenance metadata (`owner`, `source`, `external*`, `tags`) on every synced ticket.
 5. Support dependency translation (Linear parent/sub-issue -> hack `dependsOn`).
 
 ## Surfaces
@@ -28,8 +31,8 @@ This architecture keeps hack tickets lightweight while supporting bidirectional
 
 Synced tickets always carry explicit ownership and lineage metadata:
 
-1. `owner`: `hack` | `linear` (or both mode for selection during bulk sync).
-2. `source`: original system (`hack` or `linear`).
+1. `source`: immutable origin system (`hack` or `linear`); this is the authority signal.
+2. `owner`: current working-side affinity (`hack` or `linear`); useful for selection and review, but not authority.
 3. `tags`: optional label/category parity (when label sync enabled).
 4. `externalSystem`, `externalId`, `externalKey`, `externalUrl`, `externalProjectId`, `externalProjectName`, `externalTeamId`.
 
@@ -41,10 +44,14 @@ This guarantees filtering by local-only, Linear-only, or mixed sets without ambi
    - Linear `completed`/`canceled` -> hack `done`
    - Linear `started` -> hack `in_progress`
    - Linear `unstarted` -> hack `open`
+   - Hack `blocked` projects to the nearest Linear `started` state and should be treated as a lossy compatible mapping, not a perpetual conflict.
 2. Dependencies:
-   - Linear parent/sub-issue links map to hack `dependsOn` when dependency sync is enabled.
+   - Linear parent/sub-issue links map to the primary hack `dependsOn` entry when dependency sync is enabled.
 3. Labels:
    - Optional (`sync.labels=false` by default) to keep tickets lightweight until needed.
+4. Authority:
+   - `source` decides whether Hack or Linear owns authoritative fields after link.
+   - `owner` does not override `source`.
 
 ## Config
 
diff --git a/docs/plans/2026-03-22-linear-normalized-sync-semantics-design.md b/docs/plans/2026-03-22-linear-normalized-sync-semantics-design.md
new file mode 100644
index 000000000..f1f5fd283
--- /dev/null
+++ b/docs/plans/2026-03-22-linear-normalized-sync-semantics-design.md
@@ -0,0 +1,317 @@
+# Linear Normalized Sync Semantics Design
+
+## Goal
+
+Define the canonical two-way sync semantics between Linear and the normalized Hack Tickets core so future manual sync, autosync, and dogfooding work share one model.
+
+## Scope
+
+This document covers:
+
+- field translation between Linear issues and normalized Hack ticket records
+- authority and conflict behavior for two-way sync
+- the boundary between synced state, repo-shared local state, and operator-only repair
+
+This document does not cover:
+
+- OAuth and broker connection setup
+- desktop-specific presentation details
+- a new ticket storage model outside the normalized tickets event log
+
+## Normalized Hack Ticket Contract
+
+Linear sync targets the normalized ticket model already exposed by the tickets store:
+
+- `TicketSummary`
+  - `ticketId`, `title`, `body`, `status`
+  - `dependsOn`, `blocks`
+  - `owner`, `source`, `assignee`, `tags`
+  - `externalSystem`, `externalId`, `externalKey`, `externalUrl`
+  - `externalProjectId`, `externalProjectName`, `externalTeamId`
+  - `projectId`, `projectName`
+- `TicketComment`
+- `TicketReviewNote`
+- `TicketSyncCheckpoint`
+- `TicketSyncConflict`
+
+Two-way sync must mutate that model directly. It must not introduce a separate Linear-shaped shadow record that later gets reinterpreted into tickets.
+
+## Canonical Identity And Provenance
+
+### 1. Local identity
+
+- `ticketId` is the stable Hack-local identifier.
+- Linear never owns `ticketId`.
+- Sync may create a ticket, but after creation all subsequent sync resolves against the existing `ticketId`.
+
+### 2. Remote link identity
+
+- A ticket is fully linked to Linear only when:
+  - `externalSystem == "linear"`
+  - `externalId` is present
+- `externalId` is the authoritative remote identity.
+- `externalKey` is a human-facing lookup key and fallback repair handle.
+- `externalUrl` is convenience metadata only.
+
+If `externalSystem` is `linear` but `externalId` is missing, the ticket is in a repairable partial-link state. Manual repair is required before autosync may treat it as durable.
+
+### 3. Provenance fields
+
+- `source` is the immutable origin system for the ticket.
+  - `hack` means the ticket originated in Hack.
+  - `linear` means the ticket originated in Linear.
+- `owner` is the current working-side affinity for selection, filtering, and operator intent.
+  - It defaults to `source` on initial create/import.
+  - It may change later through explicit operator action or selection flows.
+  - It does not redefine authoritative field ownership.
+
+The key rule is simple: `source` decides authority; `owner` does not.
+
+If `owner` and `source` diverge, the ticket remains valid but should surface a review hint because best-effort fields may now need human confirmation.
+
+## Field Classes
+
+### Authoritative mirrored fields
+
+These fields sync in both directions, but only the origin side is authoritative after link:
+
+| Hack field | Linear field | Rule |
+| --- | --- | --- |
+| `title` | `issue.title` | Mirror both ways. After link, `source` decides authority. |
+| `body` | `issue.description` | Mirror both ways. Imported Linear bodies may include a local footer for provenance display; conflict comparison must ignore that footer. |
+| `status` | `issue.state.type` | Mirror both ways through the normalized mapping below. `source` decides authority. |
+
+### Best-effort merged fields
+
+These fields sync when enabled, but never silently win by provenance alone:
+
+| Hack field | Linear field | Rule |
+| --- | --- | --- |
+| `assignee` | `issue.assignee` | Best-effort mapping. If resolution is ambiguous, keep current value and record conflict. |
+| `tags` | `issue.labels` | Best-effort when label sync is enabled. Missing labels should not destroy unrelated local provenance tags without explicit policy. |
+| `dependsOn` | `issue.parentId` / parent issue | Best-effort only for the primary parent relationship. Unresolvable parents require conflict or deferred repair. |
+
+### Linkage and routing snapshot fields
+
+These fields describe the Linear link and should refresh from the latest successful Linear response:
+
+| Hack field | Source | Rule |
+| --- | --- | --- |
+| `externalSystem` | constant | Set to `linear` once the ticket is linked. |
+| `externalId` | Linear issue id | Authoritative remote identity. |
+| `externalKey` | Linear issue identifier | Human-facing key. |
+| `externalUrl` | Linear issue url | Convenience metadata. |
+| `externalProjectId` | Linear project id | Remote placement snapshot. |
+| `externalProjectName` | Linear project name | Remote placement snapshot. |
+| `externalTeamId` | Linear team id | Remote routing snapshot. |
+
+### Hack-local fields
+
+These fields never round-trip to Linear:
+
+| Hack field | Rule |
+| --- | --- |
+| `ticketId` | Local identity only. |
+| `owner` | Local workflow affinity only. |
+| `source` | Local provenance only. |
+| `projectId`, `projectName` | Hack-local project placement. Chosen at local create/import time, not overwritten by Linear project moves. |
+| `blocks` | Hack-local reverse adjacency projection. Do not sync independently. |
+| `TicketReviewNote` | Repo-shared review/audit state only. Never posts to Linear. |
+| `TicketSyncCheckpoint` | Repo-shared sync ledger only. |
+| `TicketSyncConflict` | Repo-shared review ledger only. |
+
+## Translation Rules
+
+### Status mapping
+
+Linear to Hack:
+
+- `completed` or `canceled` -> `done`
+- `started` -> `in_progress`
+- `unstarted` -> `open`
+
+Hack to Linear:
+
+- `done` -> nearest `completed` state
+- `in_progress` -> nearest `started` state
+- `blocked` -> nearest `started` state
+- `open` -> nearest `unstarted` state
+
+`blocked` is a lossy Hack-local refinement. A pull from Linear cannot reconstruct it. Autosync and conflict comparison must treat `blocked` vs a synced Linear `started` state as compatible unless another authoritative status change happened.
+
+### Dependency mapping
+
+- Linear parent/sub-issue maps to the first entry in `dependsOn`.
+- Extra Hack dependencies remain local-only until the normalized model grows a representable multi-edge remote mapping.
+- `blocks` stays derived from Hack-local graph state and is never pushed to Linear as a separate concept.
+
+### Assignee mapping
+
+Resolution order for Hack to Linear:
+
+1. explicit assignee mapping for the selected profile and team
+2. exact email match
+3. exact display-name match
+4. exact username/name match
+
+If none or more than one safe match exists:
+
+- do not overwrite the current Linear assignee
+- record a sync conflict or review-needed state
+- require operator intervention
+
+Linear to Hack may set `assignee` from the best available remote display value, but unresolved remote identity must not fabricate a stronger local mapping than the upstream data actually provides.
+
+### Body rendering
+
+When Linear creates or updates a Hack ticket, Hack may append a local provenance footer such as the Linear key and URL to the body rendering. That footer is a local convenience artifact, not part of the remote authoritative description. Conflict comparison and Hack-to-Linear pushes must compare against the logical body, not the rendered footer.
+
+### Comment mapping
+
+- Comments are append-only in both systems.
+- Comment edit and delete are out of scope.
+- Remote comment identity should use `externalId` when present.
+- Fallback dedupe may use normalized body text only as a best-effort secondary check.
+- If dedupe is not confident, stop and require operator review rather than risk duplicate reposts.
+
+### Review notes
+
+- Review notes are repo-shared Hack events.
+- They are never mirrored to Linear comments.
+- They are the canonical place to explain manual resolutions and sync decisions.
+
+## Two-Way Sync Behavior
+
+### Linear -> Hack create
+
+When no linked ticket exists for a Linear issue:
+
+- create a new Hack ticket
+- set `source = "linear"`
+- set `owner = "linear"` by default
+- populate authoritative mirrored fields from the Linear issue
+- populate best-effort fields when safely representable
+- populate `external*` linkage metadata
+- place the new ticket into the current Hack project context without treating the Linear project as the Hack project identity
+
+### Linear -> Hack update
+
+When a linked ticket already exists:
+
+- refresh `external*` linkage metadata from Linear
+- append newly discovered remote comments
+- apply authoritative fields only if `source == "linear"`
+- leave authoritative fields unchanged if `source == "hack"`, but record divergence for review
+- update best-effort merged fields only when the translation is safe
+- record a `TicketSyncCheckpoint`
+
+### Hack -> Linear create
+
+When a Hack ticket is not yet linked and outbound create is allowed:
+
+- create a Linear issue in the explicitly selected or bound Linear project/team
+- preserve `source = "hack"`
+- preserve `owner` unless the operator explicitly changes it
+- write back `external*` linkage metadata from the create response
+- record a `TicketSyncCheckpoint`
+
+### Hack -> Linear update
+
+When a linked Linear issue already exists:
+
+- resolve the current remote issue by `externalId`, falling back to `externalKey` only for repair
+- push authoritative fields only if `source == "hack"`
+- if `source == "linear"`, keep the remote authoritative fields intact and record divergence instead of overwriting
+- push safe best-effort merged fields when enabled
+- append newly created local comments that are not already mirrored
+- refresh `external*` linkage metadata from the update response
+- record a `TicketSyncCheckpoint`
+
+## Authority And Conflicts
+
+### Authoritative fields
+
+The authoritative field group is:
+
+- `title`
+- `body`
+- `status`
+
+Project routing needs a split rule:
+
+- `projectId` and `projectName` are Hack-local and are not Linear-authoritative
+- `externalProjectId`, `externalProjectName`, and `externalTeamId` are Linear snapshots and are refreshed from Linear
+
+That avoids a false equivalence between local Hack placement and remote Linear project placement.
+
+### Conflict detection
+
+Record a sync conflict when:
+
+- a non-authoritative side changed an authoritative field since the last compatible checkpoint
+- assignee resolution is ambiguous or missing
+- a dependency target cannot be resolved safely
+- comment dedupe is uncertain
+- the ticket is partially linked and identity repair is required
+
+Conflict records should capture:
+
+- provider
+- field or category
+- local value summary
+- remote value summary
+- expected authority
+- created/updated timestamps
+
+### Conflict resolution behavior
+
+Allowed normalized resolutions:
+
+- `accept_local`
+- `accept_remote`
+- `merged`
+- `ignore`
+
+Resolving a conflict updates the conflict ledger. It does not retroactively rewrite provenance.
+
+### Operator intervention boundary
+
+Manual intervention is required for:
+
+- partial links without `externalId`
+- ambiguous assignee mapping
+- non-representable dependency topology
+- uncertain comment dedupe
+- any resolution that would change `source`
+
+Autosync must stop short of those cases and leave durable review state behind.
+
+## Autosync Safety Rules
+
+Autosync may apply without prompting only when all of the following are true:
+
+- the ticket is fully linked by `externalId`
+- the project/profile route is known
+- authoritative comparison is unambiguous
+- best-effort fields resolve safely
+- comment dedupe is confident
+
+Autosync must never:
+
+- change `source`
+- treat `owner` as authority
+- post review notes to Linear
+- silently clear unrepresentable dependencies
+- silently overwrite open conflicts
+
+## Implementation Consequences
+
+The sync engine and UI should converge on these rules:
+
+- authority is derived from `source`
+- `owner` remains useful for selection and operator intent, not source-of-truth override
+- `externalId` is the durable remote key
+- local Hack project placement is not the same field as Linear project placement
+- lossy status translation for `blocked` must not create noisy perpetual conflicts
+
+That gives future autosync work a predictable boundary: authoritative fields stay origin-owned, best-effort fields stay mergeable, and uncertain cases leave durable review artifacts instead of silent data drift.
diff --git a/src/control-plane/extensions/linear/commands.ts b/src/control-plane/extensions/linear/commands.ts
index ebaf9b342..2a46abe6b 100644
--- a/src/control-plane/extensions/linear/commands.ts
+++ b/src/control-plane/extensions/linear/commands.ts
@@ -2904,9 +2904,8 @@ type LinearDeliverySummary = {
 function resolveTicketAuthority(input: {
   readonly ticket: TicketSummary;
 }): "hack" | "linear" {
-  const owner = input.ticket.owner.trim().toLowerCase();
   const source = input.ticket.source.trim().toLowerCase();
-  if (owner === "linear" || source === "linear") {
+  if (source === "linear") {
     return "linear";
   }
   return "hack";
@@ -2927,21 +2926,6 @@ function normalizeCommentBody(input: { readonly body: string }): string {
   return input.body.trim().replaceAll("\r\n", "\n");
 }
 
-function normalizeProjectValue(input: {
-  readonly projectId?: string;
-  readonly projectName?: string;
-}): TicketMetadataValue | undefined {
-  const projectId = readOptionalString(input.projectId);
-  const projectName = readOptionalString(input.projectName);
-  if (!(projectId || projectName)) {
-    return undefined;
-  }
-  return {
-    ...(projectId ? { projectId } : {}),
-    ...(projectName ? { projectName } : {}),
-  };
-}
-
 function detectAuthoritativeFieldConflicts(input: {
   readonly authority: "hack" | "linear";
   readonly ticket: TicketSummary;
@@ -2980,7 +2964,14 @@ function detectAuthoritativeFieldConflicts(input: {
     });
   }
 
-  if (input.ticket.status !== input.remoteProjection.status) {
+  const lossyBlockedProjection =
+    input.authority === "hack" &&
+    input.ticket.status === "blocked" &&
+    input.remoteProjection.status === "in_progress";
+  if (
+    !lossyBlockedProjection &&
+    input.ticket.status !== input.remoteProjection.status
+  ) {
     conflicts.push({
       field: "status",
       authority: input.authority,
@@ -2990,27 +2981,6 @@ function detectAuthoritativeFieldConflicts(input: {
     });
   }
 
-  const localProject = normalizeProjectValue({
-    projectId: input.ticket.projectId,
-    projectName: input.ticket.projectName,
-  });
-  const remoteProject = normalizeProjectValue({
-    projectId: input.issue.projectId,
-    projectName: input.issue.projectName,
-  });
-  if (
-    JSON.stringify(localProject ?? null) !==
-    JSON.stringify(remoteProject ?? null)
-  ) {
-    conflicts.push({
-      field: "project",
-      authority: input.authority,
-      summary: `Authoritative ${input.authority} project routing diverged from the other side.`,
-      ...(localProject !== undefined ? { localValue: localProject } : {}),
-      ...(remoteProject !== undefined ? { remoteValue: remoteProject } : {}),
-    });
-  }
-
   return conflicts;
 }
 
@@ -8330,6 +8300,7 @@ export const __testOnly = {
   resolveProjectLinearBinding,
   resolveProjectPullTargets,
   resolveOAuthBrokerRuntimeConfig,
+  resolveTicketAuthority,
   resolveTicketAssigneeForLinear,
   parseSetupArgs,
   parseStatusArgs,
diff --git a/tests/linear-commands.test.ts b/tests/linear-commands.test.ts
index 75eee414b..3cbceefec 100644
--- a/tests/linear-commands.test.ts
+++ b/tests/linear-commands.test.ts
@@ -797,10 +797,90 @@ test("detectAuthoritativeFieldConflicts reports divergence for hack-owned ticket
     "title",
     "body",
     "status",
-    "project",
   ]);
 });
 
+test("detectAuthoritativeFieldConflicts treats hack blocked as compatible with linear started", () => {
+  const conflicts = __testOnly.detectAuthoritativeFieldConflicts({
+    authority: "hack",
+    ticket: {
+      ticketId: "T-00001",
+      title: "Local title",
+      body: "Local body",
+      status: "blocked",
+      createdAt: "2026-03-05T10:00:00.000Z",
+      updatedAt: "2026-03-05T10:00:00.000Z",
+      dependsOn: [],
+      blocks: [],
+      owner: "hack",
+      source: "hack",
+      tags: [],
+      projectId: "proj-local",
+      projectName: "Local Project",
+    },
+    issue: {
+      id: "issue-1",
+      identifier: "ENG-123",
+      title: "Local title",
+      description: "Local body",
+      url: "https://linear.app/issue/ENG-123",
+      state: {
+        id: "state-1",
+        name: "Started",
+        type: "started",
+      },
+      teamId: "team-1",
+      projectId: "proj-remote",
+      projectName: "Remote Project",
+      labels: [],
+    },
+    remoteProjection: {
+      body: "Local body\n\n---\n\nLinear Issue: ENG-123\n\nLinear URL: https://linear.app/issue/ENG-123",
+      status: "in_progress",
+    },
+  });
+
+  expect(conflicts).toHaveLength(0);
+});
+
+test("resolveTicketAuthority follows source instead of owner", () => {
+  expect(
+    __testOnly.resolveTicketAuthority({
+      ticket: {
+        ticketId: "T-00001",
+        title: "Local title",
+        body: "Local body",
+        status: "open",
+        createdAt: "2026-03-05T10:00:00.000Z",
+        updatedAt: "2026-03-05T10:00:00.000Z",
+        dependsOn: [],
+        blocks: [],
+        owner: "linear",
+        source: "hack",
+        tags: [],
+      },
+    })
+  ).toBe("hack");
+
+  expect(
+    __testOnly.resolveTicketAuthority({
+      ticket: {
+        ticketId: "T-00002",
+        title: "Remote title",
+        body: "Remote body",
+        status: "open",
+        createdAt: "2026-03-05T10:00:00.000Z",
+        updatedAt: "2026-03-05T10:00:00.000Z",
+        dependsOn: [],
+        blocks: [],
+        owner: "hack",
+        source: "linear",
+        tags: [],
+      },
+    })
+  ).toBe("linear");
+});
+
 test("selectLinearCommentsToAppend keeps unmatched remote ids in FIFO order", () => {
   const selected = __testOnly.selectLinearCommentsToAppend({
     localComments: [
@@ -1088,9 +1168,9 @@ test("syncIssueFromLinearToTicket preserves hack authority, appends comments, an
   }
 
   expect(result.commentsPulled).toBe(1);
-  expect(result.conflictsRecorded).toBe(4);
+  expect(result.conflictsRecorded).toBe(3);
   expect(appendedBodies).toEqual(["Fresh remote note"]);
-  expect(conflicts).toEqual(["title", "body", "status", "project"]);
+  expect(conflicts).toEqual(["title", "body", "status"]);
   expect(checkpoints).toEqual(["linear_to_hack"]);
   expect(updatedTickets).toHaveLength(1);
   expect(updatedTickets[0]?.title).toBeUndefined();

From 3e98540904c8287d80653bce318b76b84014bfa3 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:35:50 +0000
Subject: [PATCH 118/134] docs(tickets): add portability implementation plan

---
 ...22-tickets-storage-git-portability-plan.md | 224 ++++++++++++++++++
 1 file changed, 224 insertions(+)
 create mode 100644 docs/plans/2026-03-22-tickets-storage-git-portability-plan.md

diff --git a/docs/plans/2026-03-22-tickets-storage-git-portability-plan.md b/docs/plans/2026-03-22-tickets-storage-git-portability-plan.md
new file mode 100644
index 000000000..18df48af7
--- /dev/null
+++ b/docs/plans/2026-03-22-tickets-storage-git-portability-plan.md
@@ -0,0 +1,224 @@
+# Tickets Storage Git Portability Implementation Plan
+
+**Goal:** Preserve git portability and hidden-ref sync while moving tickets to a normalized journal-plus-projection storage model.
+
+**Architecture:** Keep the tickets ref as the durable transport layer, keep the journal as the canonical source of truth, rebuild projections locally, and preserve the current hidden-ref plus legacy-branch migration behavior in `tickets-git-channel.ts`.
+
+**Tech Stack:** Bun, TypeScript, tickets control-plane store, tickets git channel, Bun tests.
+
+---
+
+### Task 1: Introduce an explicit durable-vs-derived storage contract in code
+
+**Files:**
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Modify: `src/control-plane/extensions/tickets/tickets-git-channel.ts`
+- Add or modify: storage manifest helpers under `src/control-plane/extensions/tickets/`
+- Test: `tests/tickets-store.test.ts`
+
+**Step 1: Define the portable payload**
+
+Encode a small storage contract in code so the implementation can distinguish:
+
+- durable journal data that belongs in git
+- durable metadata needed to interpret the journal
+- derived local projection state that can be rebuilt
+
+This should be explicit enough that future storage changes cannot accidentally make projection files authoritative.
+
+**Step 2: Add a versioned manifest if the normalized model needs one**
+
+If the new storage layout introduces journal manifests or storage metadata, keep them inside the tickets ref and version them clearly.
+
+**Step 3: Keep rebuildability as the invariant**
+
+The store should continue to support rebuilding ticket state by replaying durable journal data, even if projection files are added for read performance.
+
+**Step 4: Add focused tests**
+
+Verify that deleting derived state does not lose ticket history and that the store can rebuild from the durable journal payload alone.
+
+**Step 5: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/store.ts src/control-plane/extensions/tickets/tickets-git-channel.ts tests/tickets-store.test.ts
+git commit -m "feat(tickets): encode portable storage contract"
+```
+
+### Task 2: Keep the tickets ref limited to portable state
+
+**Files:**
+- Modify: `src/control-plane/extensions/tickets/tickets-git-channel.ts`
+- Test: `tests/tickets-git-channel.test.ts`
+- Test: `tests/tickets-extension.test.ts`
+
+**Step 1: Define which paths are allowed in the tickets ref**
+
+The ref should contain only:
+
+- journal files
+- durable storage metadata
+- any non-rebuildable ticket artifacts introduced by the normalized model
+
+It should not contain:
+
+- projection caches
+- bare git internals
+- local lock files
+- unrelated repository content
+
+**Step 2: Preserve repair behavior**
+
+Keep `inspect` and `repair` aligned with that invariant so a dirty or legacy tickets ref can be rebuilt into a tickets-only portable payload.
+
+**Step 3: Add tests for path hygiene**
+
+Verify the ref remains limited to durable ticket payload and that repair removes non-ticket state without losing history.
+
+**Step 4: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/tickets-git-channel.ts tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts
+git commit -m "test(tickets): enforce tickets ref portability rules"
+```
+
+### Task 3: Preserve hidden-ref and legacy-branch sync behavior during migration
+
+**Files:**
+- Modify: `src/control-plane/extensions/tickets/tickets-git-channel.ts`
+- Test: `tests/tickets-git-channel.test.ts`
+- Test: `tests/tickets-extension.test.ts`
+
+**Step 1: Keep hidden refs as the default**
+
+Maintain the current default transport:
+
+- hidden mode: `refs/hack/tickets`
+- heads mode fallback: `refs/heads/hack/tickets`
+
+**Step 2: Keep migration-safe fetch and push rules**
+
+The migration path should continue to:
+
+1. fetch the hidden ref first
+2. fall back to the legacy branch ref when the hidden ref is missing
+3. merge journal entries idempotently
+4. rebuild projections after merge
+5. only prune the legacy ref after the hidden ref carries equivalent durable history
+
+**Step 3: Test offline and mixed-history cases**
+
+Add or update tests for:
+
+- hidden-ref only remotes
+- legacy branch only remotes
+- remotes with both refs present
+- local offline writes followed by sync
+
+**Step 4: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/tickets-git-channel.ts tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts
+git commit -m "feat(tickets): preserve hidden ref migration semantics"
+```
+
+### Task 4: Make projection rebuild behavior explicit and disposable
+
+**Files:**
+- Modify: `src/control-plane/extensions/tickets/store.ts`
+- Add or modify: projection rebuild helpers under `src/control-plane/extensions/tickets/`
+- Test: `tests/tickets-store.test.ts`
+
+**Step 1: Treat projections as cache, not source of truth**
+
+If the normalized storage model adds materialized views or indexes, make the rebuild triggers explicit:
+
+- journal contents changed
+- storage version changed
+- projection version changed
+- local state is corrupt or incomplete
+
+**Step 2: Prefer replay over partial trust**
+
+When validity is uncertain, rebuild from the durable journal rather than attempting risky incremental repair of derived state.
+
+**Step 3: Add rebuild-path tests**
+
+Verify projection invalidation and rebuild do not lose comments, review notes, checkpoints, or conflicts.
+
+**Step 4: Commit**
+
+```bash
+git add src/control-plane/extensions/tickets/store.ts tests/tickets-store.test.ts
+git commit -m "feat(tickets): rebuild projections from durable journal"
+```
+
+### Task 5: Update user-facing docs to match the shipped model
+
+**Files:**
+- Modify: `docs/guides/tickets.md`
+- Modify: `docs/plans/2026-03-22-tickets-storage-git-portability-design.md`
+- Modify: migration notes if implementation details diverge
+
+**Step 1: Document the final storage layout**
+
+Keep the guide accurate about:
+
+- what is durable
+- what is rebuildable
+- how hidden-ref sync behaves
+- how legacy refs are migrated
+
+**Step 2: Remove any stale wording from pre-normalization docs**
+
+Do not leave docs implying that derived local state must be preserved or committed.
+
+**Step 3: Commit**
+
+```bash
+git add docs/guides/tickets.md docs/plans/2026-03-22-tickets-storage-git-portability-design.md
+git commit -m "docs(tickets): update normalized storage guidance"
+```
+
+### Task 6: Full verification
+
+**Files:**
+- Verify touched tickets code and docs
+
+**Step 1: Run targeted tests**
+
+Run:
+
+```bash
+bun test tests/tickets-store.test.ts tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts
+```
+
+Expected: PASS
+
+**Step 2: Run broader workspace checks if shared behavior changed**
+
+Run:
+
+```bash
+bun run typecheck
+bun run test
+bun run check
+```
+
+Expected: PASS
+
+**Step 3: Perform a git portability smoke check**
+
+Verify manually or with an integration test:
+
+- clone to a fresh repo
+- recreate local derived state from the tickets ref
+- confirm hidden-ref sync still works
+- confirm legacy-branch fallback still works
+
+**Step 4: Commit final integrated changes**
+
+```bash
+git add src/control-plane/extensions/tickets docs/guides/tickets.md docs/plans/2026-03-22-tickets-storage-git-portability-design.md docs/plans/2026-03-22-tickets-storage-git-portability-plan.md tests/tickets-store.test.ts tests/tickets-git-channel.test.ts tests/tickets-extension.test.ts
+git commit -m "Finish tickets storage portability migration"
+```

From 165edc784ca3c4d3ea44f439181715b7dab01569 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:35:55 +0000
Subject: [PATCH 119/134] docs: strengthen runtime requirements review criteria

---
 docs/README.md                                |  2 ++
 ...gent-native-runtime-requirements-design.md | 28 +++++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/docs/README.md b/docs/README.md
index e493be242..4e6ce4c34 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -31,6 +31,8 @@ Quick diagnostics:
   - [Remote node quickstart](guides/remote-node-quickstart.md)
   - [Run laptop-to-laptop node pairing e2e](guides/remote-node-laptop-e2e.md)
   - [Bootstrap a remote node on Railway](guides/remote-node-railway.md)
+- Current runtime design notes:
+  - [Agent-native runtime requirements](plans/2026-03-22-agent-native-runtime-requirements-design.md)
 - Remote setup (one command): `hack remote setup`
 - [Initialize a project](guides/init-project.md)
 - [Global settings](guides/global-settings.md)
diff --git a/docs/plans/2026-03-22-agent-native-runtime-requirements-design.md b/docs/plans/2026-03-22-agent-native-runtime-requirements-design.md
index 5b5eaa3cf..b851d7738 100644
--- a/docs/plans/2026-03-22-agent-native-runtime-requirements-design.md
+++ b/docs/plans/2026-03-22-agent-native-runtime-requirements-design.md
@@ -219,6 +219,19 @@ These materially improve the runtime, but they should not block initial architec
 
 - Make it easier to move project runtime state, env contracts, and workspace metadata between controller and node without rebuilding everything from scratch.
 
+## Workflow Traceability
+
+This is the minimum traceability map for architecture review. Every mandatory requirement should be justified by at least one real Hack workflow, and every source workflow should be protected by more than one runtime capability where appropriate.
+
+| Workflow | Primary requirements it drives |
+| --- | --- |
+| WF-1 Parallel branch environments | Project Instance Isolation, First-Class Hack Networking, Recovery As A First-Class Capability |
+| WF-2 Agent-heavy local work | Sessions As Runtime Objects, Cheap Concurrent Execution For Subagents, Control-Plane Native Runtime Introspection |
+| WF-3 Host-side helpers | Host-Native Lifecycle Integration, Sessions As Runtime Objects, Recovery As A First-Class Capability |
+| WF-4 Remote control-plane execution | Control-Plane Native Runtime Introspection, Cheap Concurrent Execution For Subagents, Recovery As A First-Class Capability |
+| WF-5 Controller local-edit, remote-run | Remote Workspace Bootstrap And Branch Ensure, First-Class Hack Networking, Control-Plane Native Runtime Introspection, Recovery As A First-Class Capability |
+| WF-6 Fresh-node bootstrap and devcontainers | Remote Workspace Bootstrap And Branch Ensure, Control-Plane Native Runtime Introspection |
+
 ## Explicit Non-Requirements
 
 These should not distort the architecture discussion.
@@ -251,6 +264,21 @@ A candidate runtime should be evaluated against these questions before implement
 4. Does it make job, shell, session, and lifecycle logging more coherent?
 5. Does it make architecture simpler for the desktop app, CLI, and gateway consumers?
 
+## Required Prototype Evidence
+
+The evaluation loop should not accept slideware or narrow happy-path demos. A runtime spike should prove each mandatory capability with direct evidence and should avoid the false positives listed here.
+
+| Requirement | Minimum proof for architecture evaluation | False positive to avoid |
+| --- | --- | --- |
+| Project Instance Isolation | Start two branch instances of one repo, confirm independent routing, logs, and teardown, then restart the daemon/CLI and rediscover both instances by stable identity. | Demoing two unrelated projects or two manual ports instead of true branch-instance isolation. |
+| First-Class Hack Networking | Prove stable `*.hack` access from browser, from inside a service, and through a controller-side remote route bridge to a node-hosted workload. Then force drift and show route repair. | Showing only host-to-container localhost access or static port mappings with no hostname model. |
+| Sessions As Runtime Objects | Create named sessions, reconnect after CLI exit, exec commands, capture/tail output, and stop them through the local API surface. | Replacing durable sessions with plain subprocesses that die when the caller disconnects. |
+| Cheap Concurrent Execution For Subagents | Run several concurrent jobs and interactive shells against one project instance, with isolated terminal state, streamed output, stable run ids, and reliable cancellation. | Serial command execution or one shared PTY presented as “multi-agent support.” |
+| Host-Native Lifecycle Integration | Start a project with required host hooks and persistent helper processes, surface them in logs and runtime state, then tear them down cleanly with the project instance. | Treating host helpers as external prerequisites or unmanaged terminal tabs. |
+| Remote Workspace Bootstrap And Branch Ensure | On a fresh node, bootstrap the repo from hints only, ensure a branch, record bootstrap auth source, and reuse the workspace for later dispatch or devcontainer startup. | Assuming the workspace was pre-cloned or manually prepared outside Hack. |
+| Control-Plane Native Runtime Introspection | Use one runtime-backed API surface to list projects, instances, jobs, shells, sessions, and lifecycle processes for both local CLI and gateway consumers. | Scraping ad hoc shell output differently in each client and calling that a control plane. |
+| Recovery As A First-Class Capability | Simulate runtime reset or stale daemon state, distinguish the failure mode, preserve discoverability of live instances, and prove reconnect or guided repair by stable identity. | Only proving clean-start behavior and ignoring reset, drift, or stale-state recovery. |
+
 ## Recommendation For Option Evaluation
 
 When comparing runtime architectures, score them against the mandatory set first and only discuss performance, implementation language, or operator simplicity after that gate passes.

From 4cbf22634dbdb24e642ee7641aa9b99e4f00a2c8 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:36:03 +0000
Subject: [PATCH 120/134] docs: add docs ia proposal and guide labels

---
 docs/README.md                        |  1 +
 docs/docs-ia.md                       | 98 +++++++++++++++++++++++++++
 docs/guides/create-extension.md       |  4 ++
 docs/guides/global-settings.md        |  3 +
 docs/guides/remote-node-quickstart.md |  4 ++
 docs/guides/tickets.md                |  3 +
 docs/reference.md                     |  1 +
 7 files changed, 114 insertions(+)
 create mode 100644 docs/docs-ia.md

diff --git a/docs/README.md b/docs/README.md
index e18aa532e..57b8547ca 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -46,6 +46,7 @@ This section is easy to find, but it does not lead the product story.
 - New to `hack`: [Core docs](core.md)
 - Ready for 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
 
diff --git a/docs/docs-ia.md b/docs/docs-ia.md
new file mode 100644
index 000000000..23435f7ff
--- /dev/null
+++ b/docs/docs-ia.md
@@ -0,0 +1,98 @@
+# Docs Information Architecture
+
+This document defines the documentation split for `hack`:
+
+- core
+- beta
+- extensions and reference
+
+The goal is to keep the primary product story legible while still making advanced and evolving
+surfaces easy to find on purpose.
+
+## Principles
+
+1. Core comes first.
+2. Beta remains accessible, but never reads as the default path.
+3. Reference is easy to find, but does not lead onboarding.
+4. Cross-links should help readers move from core into beta intentionally.
+5. Deep links into beta or reference pages should self-identify where the reader is.
+
+## Sections
+
+### Core
+
+Core docs describe the default local `hack` experience:
+
+- initialize a repo
+- run services on isolated local networks
+- open stable local hostnames
+- manage env and secrets
+- configure lifecycle hooks
+- manage persistent sessions
+
+Current landing page:
+- [Core docs](core.md)
+
+Core pages:
+- [Initialize a project](guides/init-project.md)
+- [Architecture](architecture.md)
+- [Env & secrets](env.md)
+- [Lifecycle](lifecycle.md)
+- [Sessions](sessions.md)
+
+### Beta
+
+Beta docs cover remote and control-plane workflows that are still evolving:
+
+- gateway exposure
+- remote nodes
+- remote execution
+- remote supervisor jobs
+
+Current landing page:
+- [Beta workflows](beta.md)
+
+Beta pages:
+- [Gateway overview](gateway.md)
+- [Remote node quickstart](guides/remote-node-quickstart.md)
+- [Run laptop-to-laptop node pairing e2e](guides/remote-node-laptop-e2e.md)
+- [Bootstrap a remote node on Railway](guides/remote-node-railway.md)
+- [Run a remote node via container image](guides/remote-node-container.md)
+- [Expose the gateway over SSH](guides/remote-ssh.md)
+- [Expose the gateway with Cloudflare](guides/remote-cloudflare.md)
+- [Expose the gateway with Tailscale](guides/remote-tailscale.md)
+- [Run remote supervisor jobs](guides/remote-supervisor.md)
+
+### Extensions & Reference
+
+Extensions and reference docs hold command lookup, APIs, and implementation-oriented material:
+
+- CLI command tables
+- extension configuration and authoring
+- tickets and integrations
+- API and SDK reference
+
+Current landing page:
+- [Extensions & reference](reference.md)
+
+Reference pages:
+- [CLI reference](cli.md)
+- [Extensions](extensions.md)
+- [Global settings](guides/global-settings.md)
+- [Tickets (git-backed)](guides/tickets.md)
+- [Create a new extension](guides/create-extension.md)
+- [Linear integration architecture](guides/linear-integration-architecture.md)
+- [Auth broker Neon bootstrap](guides/auth-broker-neon-bootstrap.md)
+- [Gateway API](gateway-api.md)
+- [Supervisor](supervisor.md)
+- [Control-plane SDK](sdk.md)
+
+## Navigation Rules
+
+Use these rules when adding or updating docs:
+
+1. Default new user links should point to [Core docs](core.md), not directly to beta or reference.
+2. Remote and control-plane setup pages should identify themselves as beta.
+3. Command tables, SDK docs, and extension authoring guides should identify themselves as reference.
+4. Core pages may link out to beta only when the move is explicit and intentional.
+5. Root docs navigation should present the three buckets before individual pages.
diff --git a/docs/guides/create-extension.md b/docs/guides/create-extension.md
index a088232ba..8848dfe3d 100644
--- a/docs/guides/create-extension.md
+++ b/docs/guides/create-extension.md
@@ -1,5 +1,9 @@
 # Create an extension
 
+This page is part of [Extensions & reference](../reference.md).
+Start with [Core docs](../core.md) if you are learning `hack`, or use [Beta workflows](../beta.md)
+if you are here because of remote/control-plane features.
+
 Extensions add commands and configuration without bloating the core CLI.
 
 ## Layout (current)
diff --git a/docs/guides/global-settings.md b/docs/guides/global-settings.md
index 9ff051572..13408c458 100644
--- a/docs/guides/global-settings.md
+++ b/docs/guides/global-settings.md
@@ -1,5 +1,8 @@
 # Global settings
 
+This page is part of [Extensions & reference](../reference.md).
+For the default local product story, start with [Core docs](../core.md).
+
 Global settings live at `~/.hack/hack.config.json`. Use the CLI instead of editing by hand:
 
 ```bash
diff --git a/docs/guides/remote-node-quickstart.md b/docs/guides/remote-node-quickstart.md
index d4af4bc71..f2ce635cc 100644
--- a/docs/guides/remote-node-quickstart.md
+++ b/docs/guides/remote-node-quickstart.md
@@ -1,5 +1,9 @@
 # Remote Node Quickstart
 
+This is a beta workflow.
+Start with [Core docs](../core.md) if you are new to `hack`, and use [Beta workflows](../beta.md)
+for the rest of the remote path.
+
 Use this guide to connect one remote machine as a `hack` execution node and run a project on it.
 
 ## What you need
diff --git a/docs/guides/tickets.md b/docs/guides/tickets.md
index 279f60a02..c4752827c 100644
--- a/docs/guides/tickets.md
+++ b/docs/guides/tickets.md
@@ -1,5 +1,8 @@
 # Tickets (git-backed)
 
+This page is part of [Extensions & reference](../reference.md).
+If you are learning the core local product flow, start with [Core docs](../core.md).
+
 The tickets extension is a lightweight, git-backed ticket log intended for small teams and solo dev.
 It stores events in a dedicated git ref (`refs/hack/tickets` by default, hidden from branch lists) so
 ticket history is versioned and syncable without requiring an external service.
diff --git a/docs/reference.md b/docs/reference.md
index 8376d3c67..a12b10001 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -28,3 +28,4 @@ do not compete with the default `hack` onboarding path.
 
 - If you are setting up or learning `hack`, start with [Core docs](core.md)
 - If you are intentionally enabling remote execution or exposure, go to [Beta workflows](beta.md)
+- If you need the section definitions themselves, see [Docs information architecture](docs-ia.md)

From 20d22bc30c67b3e179783ddf58784afbfac39256 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:36:46 +0000
Subject: [PATCH 121/134] docs: add adjacent capabilities to cli reference

---
 docs/cli.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/cli.md b/docs/cli.md
index b24c10d74..ce76fbbbe 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -10,6 +10,24 @@ Run `hack help` or `hack help <command>` for interactive help.
 - `--profile` accepts comma-separated compose profiles.
 - Options marked repeatable can be passed multiple times.
 
+## Adjacent capabilities
+
+These commands usually matter after the basic `hack init` / `hack up` / `hack open` loop is already
+working. You do not need all of them for every repo.
+
+- **GitHub**: Use `hack x github` when you want `hack` to help with connected-account setup and pull
+  request workflows. It becomes relevant once a branch is ready to open, update, or hand off for
+  review.
+- **Linear**: Use `hack linear` when repo work should stay connected to Linear issues or projects. It
+  becomes relevant when the repo maps to a Linear workflow and you want sync without leaving the CLI.
+- **Tickets**: Use `hack tickets` when you want lightweight repo-local work tracking that stays in git.
+  It becomes relevant as soon as you want to capture follow-up work without depending on an external
+  tracker.
+- **Sessions**: Use `hack session` when you want a reusable terminal workspace you can return to or hand
+  off. It becomes relevant when you keep long-running shells, agent runs, or SSH workspaces alive.
+- **Env**: Use `hack env` when a project needs explicit local config or secrets. It becomes relevant as
+  soon as `hack up`, `hack run`, or remote workflows depend on values that should not be hardcoded.
+
 ## Top-level commands
 
 | Command | Summary | Group |

From 53d764ec7b6a42b3e0792def908b92f99551dbf9 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:37:34 +0000
Subject: [PATCH 122/134] docs(tickets): clarify portable journal paths

---
 docs/guides/tickets.md                                | 11 ++++++++---
 ...26-03-22-tickets-storage-git-portability-design.md |  6 +++---
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/guides/tickets.md b/docs/guides/tickets.md
index 78caf0340..b59833f87 100644
--- a/docs/guides/tickets.md
+++ b/docs/guides/tickets.md
@@ -132,17 +132,22 @@ Tip: use `--body-stdin` for multi-line markdown.
 
 ### Storage layout
 
-In your project repo:
+Local tickets state under your project:
 
-- `.hack/tickets/events/events-YYYY-MM.jsonl` — event log segments (UTC month)
 - `.hack/tickets/git/bare.git` — a bare repo used to manage the tickets ref
 - `.hack/tickets/git/worktree` — a worktree used for reading/writing ticket data
+- `.hack/tickets/git/worktree/.hack/tickets/events/events-YYYY-MM.jsonl` — local checkout of the durable event log
+
+Path inside the tickets ref:
+
+- `.hack/tickets/events/events-YYYY-MM.jsonl` — portable event log segments (UTC month)
 
 ### Durability and portability
 
 The durable portable layer is the event log in the tickets ref.
 
-- `.hack/tickets/events/*.jsonl` is the source of truth
+- inside the ref, `.hack/tickets/events/*.jsonl` is the source of truth
+- locally, those files are materialized under `.hack/tickets/git/worktree/.hack/tickets/events/*.jsonl`
 - `list`, `show`, and related views are rebuilt by replaying the event log
 - deleting local projection state must not lose ticket history
 
diff --git a/docs/plans/2026-03-22-tickets-storage-git-portability-design.md b/docs/plans/2026-03-22-tickets-storage-git-portability-design.md
index 25a4b0144..3976463ed 100644
--- a/docs/plans/2026-03-22-tickets-storage-git-portability-design.md
+++ b/docs/plans/2026-03-22-tickets-storage-git-portability-design.md
@@ -4,7 +4,7 @@
 
 Tickets already rely on git as the durable transport layer:
 
-- the canonical ticket history is an append-only event log stored under `.hack/tickets/events`
+- the canonical ticket history is an append-only event log stored at `.hack/tickets/events` inside the tickets ref
 - sync uses a dedicated tickets ref, hidden by default as `refs/hack/tickets`
 - the local store rebuilds ticket summaries, comments, review notes, checkpoints, and conflicts by replaying the event log
 
@@ -50,7 +50,7 @@ The tickets ref remains the canonical portable payload. It should contain only d
   - migration markers when needed
 - durable artifacts that cannot be recreated from the journal alone
 
-For the current implementation, the journal is the existing monthly JSONL event log under `.hack/tickets/events/events-YYYY-MM.jsonl`.
+For the current implementation, the journal is the existing monthly JSONL event log at `.hack/tickets/events/events-YYYY-MM.jsonl` inside the tickets ref, materialized locally under `.hack/tickets/git/worktree/.hack/tickets/events/events-YYYY-MM.jsonl`.
 
 For the normalized model, the journal may move or be segmented differently, but it keeps the same contract:
 
@@ -187,7 +187,7 @@ The existing inspect and repair workflow already points in this direction by det
 
 ### From current event logs
 
-Existing `.hack/tickets/events/*.jsonl` files remain valid durable journal input during migration.
+Existing `.hack/tickets/events/*.jsonl` files inside the tickets ref remain valid durable journal input during migration.
 
 If the normalized model introduces a different journal layout, migration must:
 

From 7ad4ffddc38675047f75374473444ede09b624d7 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:37:40 +0000
Subject: [PATCH 123/134] docs: label beta guide entry points

---
 docs/guides/remote-cloudflare.md      | 4 ++++
 docs/guides/remote-node-container.md  | 4 ++++
 docs/guides/remote-node-laptop-e2e.md | 4 ++++
 docs/guides/remote-node-railway.md    | 4 ++++
 docs/guides/remote-ssh.md             | 4 ++++
 docs/guides/remote-supervisor.md      | 4 ++++
 docs/guides/remote-tailscale.md       | 4 ++++
 7 files changed, 28 insertions(+)

diff --git a/docs/guides/remote-cloudflare.md b/docs/guides/remote-cloudflare.md
index 2f75279e0..12480f8a3 100644
--- a/docs/guides/remote-cloudflare.md
+++ b/docs/guides/remote-cloudflare.md
@@ -1,5 +1,9 @@
 # Expose the gateway with Cloudflare
 
+This is a beta workflow.
+Start with [Core docs](../core.md) if you are new to `hack`, and use [Beta workflows](../beta.md)
+for the rest of the remote path.
+
 > ⚠️ Experimental: this guide has not been validated end-to-end yet. Use with caution and report issues.
 
 Cloudflare Tunnel is ideal for HTTP/WS gateway access from a phone or browser when you are off-network.
diff --git a/docs/guides/remote-node-container.md b/docs/guides/remote-node-container.md
index 88d5df282..c22bc052a 100644
--- a/docs/guides/remote-node-container.md
+++ b/docs/guides/remote-node-container.md
@@ -1,5 +1,9 @@
 # Remote Node Runtime Container
 
+This is a beta workflow.
+Start with [Core docs](../core.md) if you are new to `hack`, and use [Beta workflows](../beta.md)
+for the rest of the remote path.
+
 Use the published node-runtime container to spin up a remote node with minimal host setup.
 
 Recommended public image:
diff --git a/docs/guides/remote-node-laptop-e2e.md b/docs/guides/remote-node-laptop-e2e.md
index 0ff9c3864..564123257 100644
--- a/docs/guides/remote-node-laptop-e2e.md
+++ b/docs/guides/remote-node-laptop-e2e.md
@@ -1,5 +1,9 @@
 # Run laptop-to-laptop node pairing e2e
 
+This is a beta workflow.
+Start with [Core docs](../core.md) if you are new to `hack`, and use [Beta workflows](../beta.md)
+for the rest of the remote path.
+
 This guide is the full validation run for two Macs:
 1. Controller Mac (host mode)
 2. Remote MacBook node
diff --git a/docs/guides/remote-node-railway.md b/docs/guides/remote-node-railway.md
index 1fd58775f..e641e96db 100644
--- a/docs/guides/remote-node-railway.md
+++ b/docs/guides/remote-node-railway.md
@@ -1,5 +1,9 @@
 # Railway Node Bootstrap Guide
 
+This is a beta workflow.
+Start with [Core docs](../core.md) if you are new to `hack`, and use [Beta workflows](../beta.md)
+for the rest of the remote path.
+
 Use this guide to register a Railway-hosted runtime as a `hack` remote node.
 
 If this is your first remote node, start with [Remote node quickstart](remote-node-quickstart.md) for core concepts.
diff --git a/docs/guides/remote-ssh.md b/docs/guides/remote-ssh.md
index ed86f599d..87e1219c2 100644
--- a/docs/guides/remote-ssh.md
+++ b/docs/guides/remote-ssh.md
@@ -1,5 +1,9 @@
 # Expose the gateway over SSH
 
+This is a beta workflow.
+Start with [Core docs](../core.md) if you are new to `hack`, and use [Beta workflows](../beta.md)
+for the rest of the remote path.
+
 > ⚠️ Experimental: this guide has not been validated end-to-end yet. Use with caution and report issues.
 
 Use SSH port-forwarding when you want quick, ad-hoc access without extra tooling.
diff --git a/docs/guides/remote-supervisor.md b/docs/guides/remote-supervisor.md
index b529cdebb..11cbf217b 100644
--- a/docs/guides/remote-supervisor.md
+++ b/docs/guides/remote-supervisor.md
@@ -1,5 +1,9 @@
 # Run remote supervisor jobs
 
+This is a beta workflow.
+Start with [Core docs](../core.md) if you are new to `hack`, and use [Beta workflows](../beta.md)
+for the rest of the remote path.
+
 Use the gateway API to run commands and stream logs remotely.
 
 ## Prereqs
diff --git a/docs/guides/remote-tailscale.md b/docs/guides/remote-tailscale.md
index 3a9525765..1a6564d7b 100644
--- a/docs/guides/remote-tailscale.md
+++ b/docs/guides/remote-tailscale.md
@@ -1,5 +1,9 @@
 # Expose the gateway with Tailscale
 
+This is a beta workflow.
+Start with [Core docs](../core.md) if you are new to `hack`, and use [Beta workflows](../beta.md)
+for the rest of the remote path.
+
 Use this guide when you want private tailnet-only access to `hack` gateway endpoints.
 
 Tailscale is recommended for:

From 9fe88488636e401d2a3bbf288a6a1bc1abf289d3 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:37:43 +0000
Subject: [PATCH 124/134] Align desktop Linear sync guidance

---
 .../Sources/DashboardFeature/SettingsOverlayView.swift      | 2 +-
 .../Shared/Models/Sources/HackDesktopModels/Models.swift    | 2 +-
 .../HackDesktopModelsTests/LinearSyncUXModelTests.swift     | 6 ++++--
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/apps/macos/Packages/Features/DashboardFeature/Sources/DashboardFeature/SettingsOverlayView.swift b/apps/macos/Packages/Features/DashboardFeature/Sources/DashboardFeature/SettingsOverlayView.swift
index f99c08202..40da800d8 100644
--- a/apps/macos/Packages/Features/DashboardFeature/Sources/DashboardFeature/SettingsOverlayView.swift
+++ b/apps/macos/Packages/Features/DashboardFeature/Sources/DashboardFeature/SettingsOverlayView.swift
@@ -3530,7 +3530,7 @@ private struct LinearExtensionSettingsView: View {
   }
 
   private var linearSyncPolicySummary: String {
-    "Authority follows ticket origin. Origin-owned fields such as title, body, status, and project binding stay authoritative on the side that created the ticket, while assignees, labels, dependencies, and sub-issue links are best-effort mergeable when enabled. Comments are append-only and synced in FIFO order rather than edited in place."
+    "Authority follows ticket origin. Origin-owned fields such as title, body, and status stay authoritative on the side that created the ticket. Linear linkage metadata refreshes from Linear, while Hack project placement stays local. Assignees, labels, dependencies, and sub-issue links are best-effort mergeable when enabled. Comments are append-only and synced in FIFO order rather than edited in place."
   }
 
   private var linearSyncReviewSummary: String {
diff --git a/apps/macos/Packages/Shared/Models/Sources/HackDesktopModels/Models.swift b/apps/macos/Packages/Shared/Models/Sources/HackDesktopModels/Models.swift
index eb6106e45..81033232d 100644
--- a/apps/macos/Packages/Shared/Models/Sources/HackDesktopModels/Models.swift
+++ b/apps/macos/Packages/Shared/Models/Sources/HackDesktopModels/Models.swift
@@ -2479,7 +2479,7 @@ public struct LinearSyncUXState: Hashable {
     guard isLinkedToLinear else {
       return "Local only. Connect to Linear to sync this ticket."
     }
-    return "\(authority.label) controls title, body, status, and project. Comments append only. Assignee, labels, and dependencies sync best effort."
+    return "\(authority.label) controls title, body, and status. Linear linkage metadata refreshes from Linear, while Hack project placement stays local. Comments append only. Assignee, labels, and dependencies sync best effort."
   }
 
   private static func makeReviewHint(
diff --git a/apps/macos/Packages/Shared/Models/Tests/HackDesktopModelsTests/LinearSyncUXModelTests.swift b/apps/macos/Packages/Shared/Models/Tests/HackDesktopModelsTests/LinearSyncUXModelTests.swift
index 4fb045486..a8faa2161 100644
--- a/apps/macos/Packages/Shared/Models/Tests/HackDesktopModelsTests/LinearSyncUXModelTests.swift
+++ b/apps/macos/Packages/Shared/Models/Tests/HackDesktopModelsTests/LinearSyncUXModelTests.swift
@@ -37,7 +37,8 @@ final class LinearSyncUXModelTests: XCTestCase {
     XCTAssertEqual(ticket.linearSyncAuthority, .hack)
     XCTAssertTrue(ticket.linearSyncUXState.isLinkedToLinear)
     XCTAssertNil(ticket.linearSyncUXState.reviewHint)
-    XCTAssertTrue(ticket.linearSyncUXState.shortGuidance.contains("Hack controls title, body, status, and project."))
+    XCTAssertTrue(ticket.linearSyncUXState.shortGuidance.contains("Hack controls title, body, and status."))
+    XCTAssertTrue(ticket.linearSyncUXState.shortGuidance.contains("Hack project placement stays local."))
   }
 
   func testLinearOriginTicketIsLinearAuthoritative() {
@@ -52,7 +53,8 @@ final class LinearSyncUXModelTests: XCTestCase {
     XCTAssertEqual(ticket.linearSyncAuthority, .linear)
     XCTAssertTrue(ticket.linearSyncUXState.isLinkedToLinear)
     XCTAssertNil(ticket.linearSyncUXState.reviewHint)
-    XCTAssertTrue(ticket.linearSyncUXState.shortGuidance.contains("Linear controls title, body, status, and project."))
+    XCTAssertTrue(ticket.linearSyncUXState.shortGuidance.contains("Linear controls title, body, and status."))
+    XCTAssertTrue(ticket.linearSyncUXState.shortGuidance.contains("Hack project placement stays local."))
   }
 
   func testLinkedLinearTicketWithMismatchedOwnershipNeedsReviewHint() {

From 16c49fc7942198c22551e83cf1eb98009b928975 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:38:00 +0000
Subject: [PATCH 125/134] Add markdown-backed ticket documents design

---
 ...03-22-tickets-markdown-documents-design.md | 255 ++++++++++++++++++
 1 file changed, 255 insertions(+)
 create mode 100644 docs/plans/2026-03-22-tickets-markdown-documents-design.md

diff --git a/docs/plans/2026-03-22-tickets-markdown-documents-design.md b/docs/plans/2026-03-22-tickets-markdown-documents-design.md
new file mode 100644
index 000000000..08ff21100
--- /dev/null
+++ b/docs/plans/2026-03-22-tickets-markdown-documents-design.md
@@ -0,0 +1,255 @@
+# Tickets Markdown Documents Design
+
+## Goal
+
+Add ticket-linked markdown documents so specs and working notes can live beside normalized ticket state without losing plain-text portability, git readability, or clean integration boundaries.
+
+## Constraints
+
+- Keep tickets local-first and git-backed under `.hack/tickets/`.
+- Fit beside the normalized ticket core rather than replacing it with a second document system.
+- Keep markdown files readable as normal `.md` files without requiring Hack-specific tooling.
+- Avoid inventing rich document semantics such as comments, blocks, or WYSIWYG structure in v1.
+- Keep external ticket sync conservative. Extra documents should not silently become remote issue comments or attachments.
+
+## Design Summary
+
+- The normalized ticket record stays small and owns document metadata.
+- Document content lives in plain markdown files on disk, one file per document.
+- Ticket `body` remains the short overview field for lists, summaries, and lightweight integrations.
+- Richer long-form content moves into ticket documents with explicit metadata:
+  - `spec`
+  - `notes`
+  - `attachment`
+- Documents are stored inside the same ticket-scoped directory as normalized ticket state and sync through the existing tickets git ref.
+- Exactly zero or one document may opt into `ticket_body` projection for integrations that only have a single body field. All other documents stay local-only.
+
+## Normalized Model
+
+Each normalized ticket record gains a `documents` array.
+
+```json
+{
+  "ticketId": "T-00042",
+  "title": "Normalize ticket storage",
+  "body": "Short overview used in lists and lightweight sync targets.",
+  "status": "in_progress",
+  "documents": [
+    {
+      "documentId": "doc_01HV6M3Y7P8JQ6J6V2M4G2R5HX",
+      "slug": "spec",
+      "title": "Normalization spec",
+      "kind": "spec",
+      "format": "markdown",
+      "path": "docs/spec.md",
+      "role": "primary",
+      "syncMode": "ticket_body",
+      "createdAt": "2026-03-22T18:30:11.000Z",
+      "updatedAt": "2026-03-22T20:01:04.000Z",
+      "createdBy": "symphony@hack",
+      "updatedBy": "symphony@hack"
+    },
+    {
+      "documentId": "doc_01HV6M43TQX11P1Q3V14F5FD8A",
+      "slug": "working-notes",
+      "title": "Working notes",
+      "kind": "notes",
+      "format": "markdown",
+      "path": "docs/working-notes.md",
+      "role": "secondary",
+      "syncMode": "local_only",
+      "createdAt": "2026-03-22T18:41:08.000Z",
+      "updatedAt": "2026-03-22T18:41:08.000Z"
+    }
+  ]
+}
+```
+
+### Document Metadata
+
+Required fields:
+
+- `documentId`: stable identity for references and renames
+- `slug`: ticket-local selector used for human selection and path derivation
+- `title`: user-facing label
+- `kind`: `spec | notes | attachment`
+- `format`: `markdown`
+- `path`: ticket-local relative path to the markdown file
+- `role`: `primary | secondary`
+- `syncMode`: `local_only | ticket_body`
+- `createdAt`
+- `updatedAt`
+
+Optional fields:
+
+- `createdBy`
+- `updatedBy`
+- `source`: `hack | imported | mirrored`
+- `externalUrl`: when the markdown file is a repo-local copy of an external spec
+
+### Semantics
+
+- `spec`: durable long-form design or implementation document tied to the ticket.
+- `notes`: mutable working notes, investigation logs, and handoff context.
+- `attachment`: supporting markdown imported from elsewhere or kept as a secondary reference.
+- `primary`: the default document shown in ticket detail and the only role eligible for `ticket_body` projection.
+- `secondary`: visible in detail and CLI document lists, but not used as the default rendered document.
+- `ticket_body`: project the markdown content into a single remote issue body field when a sync integration explicitly supports it.
+- `local_only`: keep the document repo-shared only.
+
+Rules:
+
+- A ticket may have many documents.
+- A ticket may have at most one `primary` document.
+- A ticket may have at most one document with `syncMode: "ticket_body"`.
+- `syncMode: "ticket_body"` is only valid on a `primary` document.
+- `slug` must be unique within a ticket.
+
+## On-Disk Layout
+
+Documents live beside normalized ticket state, not inside JSON blobs.
+
+```text
+.hack/tickets/
+  tickets/
+    T-00042/
+      ticket.json
+      docs/
+        spec.md
+        working-notes.md
+```
+
+Rules:
+
+- All document files are UTF-8 markdown with LF line endings.
+- Filenames are lower-kebab-case and end in `.md`.
+- `path` is always relative to the ticket directory.
+- Hack does not require YAML frontmatter. Existing frontmatter may be preserved but is not authoritative for metadata.
+- The normalized record, not the markdown heading, is the source of truth for `title`, `kind`, `role`, and `syncMode`.
+
+## Storage And Sync Rules
+
+### 1. Authority
+
+- `ticket.json` owns document metadata.
+- `docs/*.md` owns document content.
+- A document update may change metadata, content, or both, but both changes should land in the same tickets-ref commit when they are part of one user action.
+
+### 2. Sync Surface
+
+- Document files live under `.hack/tickets/**`, so they sync with the same hidden tickets ref as normalized ticket state.
+- No separate git ref, blob store, or broker table is needed for repo-shared markdown documents.
+- Normalization should canonicalize:
+  - relative paths
+  - filename casing
+  - LF endings
+  - stable JSON key order in `ticket.json`
+
+### 3. Lifecycle
+
+Create:
+
+- Add metadata entry to `ticket.json`
+- Write markdown file to `docs/<slug>.md`
+
+Update content:
+
+- Rewrite only the markdown file
+- Update `updatedAt` and `updatedBy` in `ticket.json`
+
+Rename:
+
+- Change `slug`, `title`, and `path` in `ticket.json`
+- Rename the markdown file in the same commit
+- Preserve `documentId`
+
+Delete:
+
+- Remove the metadata entry from `ticket.json`
+- Delete the markdown file in the same commit
+- Rely on git history for recovery rather than adding a second soft-delete system
+
+### 4. Conflict Model
+
+- Repo-local document edits rely on normal git text merge behavior first.
+- Hack should not invent line-level document merge semantics in the ticket model.
+- If a document is projected into an external ticket body, projection conflicts are handled at the sync boundary, not by rewriting the local markdown model.
+
+### 5. External Integrations
+
+- Extra documents are `local_only` by default.
+- Integrations that only support one markdown body may read from the single `ticket_body` document.
+- External systems should not receive secondary documents until Hack adds an explicit export or attachment transport for them.
+- If no document is marked `ticket_body`, integrations continue using the normalized ticket `body` field exactly as they do today.
+
+This keeps the markdown document model portable while avoiding accidental remote noise.
+
+## Workflow Guidance
+
+### CLI
+
+Documents should become a first-class sub-surface instead of overloading `body`.
+
+Recommended commands:
+
+- `hack tickets docs list <ticket-id>`
+- `hack tickets docs show <ticket-id> <document-id|slug>`
+- `hack tickets docs add <ticket-id> --kind spec --title "..." [--primary] [--stdin|--file]`
+- `hack tickets docs update <ticket-id> <document-id|slug> [--stdin|--file]`
+- `hack tickets docs remove <ticket-id> <document-id|slug>`
+
+`hack tickets show` should:
+
+- keep the short ticket body summary
+- list document metadata in a `Documents` section
+- identify which document is primary and whether one is projected to `ticket_body`
+
+`hack tickets show --json` should return document metadata by default and include markdown content only behind an explicit flag such as `--include-documents` to avoid bloated agent payloads.
+
+### TUI And Desktop
+
+- Ticket list surfaces should show only a lightweight document indicator, not full markdown previews.
+- Ticket detail should show:
+  - short overview body
+  - primary document preview or open action
+  - secondary documents list
+- Specs and notes should read as repo-backed artifacts, not synced comments.
+
+### Agents And MCP
+
+- Agent-facing ticket detail should expose document metadata and filesystem paths by default.
+- Inline markdown content should be opt-in to keep prompts bounded.
+- Agents should be able to reference documents as stable ticket-scoped assets instead of scraping long markdown out of `ticket.body`.
+
+### Integrated Workflows
+
+- For Linear or similar issue trackers, Hack keeps syncing the normalized ticket summary fields as today.
+- A team that wants its long-form spec mirrored into the remote issue description can opt one primary document into `ticket_body`.
+- Secondary notes remain local/repo-shared unless a later feature adds explicit publish/export semantics.
+
+## Why This Fits The Normalized Core
+
+- The ticket record stays normalized: metadata in structured JSON, content in files.
+- Document identity is stable independent of path changes.
+- Markdown content is not duplicated into multiple structured stores.
+- The model preserves the current local-first tickets ref instead of introducing a second persistence system.
+- It gives the normalized core a single attachment shape now, so future UI and sync work can build on fixed semantics rather than inventing them ad hoc.
+
+## Non-Goals
+
+- Binary attachments
+- Rich-text block models
+- Inline comments or annotations
+- Automatic export of every ticket document to external systems
+- Replacing the existing append-only history model with document diffs
+
+## Implementation Notes
+
+This model should be implemented as part of the normalized ticket layout, not by stuffing markdown into event payloads.
+
+During migration from the current event-log-only store:
+
+- keep `ticket.body` as the short summary field
+- add normalized document metadata plus `docs/*.md` files
+- treat markdown documents as first-class normalized assets
+- keep legacy event logs as history and operational input until the normalized core fully owns ticket reads

From 0f8bc6db6360d20fe80e427405ab8ca193e531dd Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 04:23:05 +0000
Subject: [PATCH 126/134] feat(auth): define org and team membership semantics

---
 docs/cli.md                                   | 442 ++++++++++++
 ...nd-organizations-admin-semantics-design.md | 356 ++++++++++
 ...-and-organizations-admin-semantics-plan.md | 330 +++++++++
 services/auth-broker/src/app.ts               |  18 +
 .../auth-broker/src/modules/orgs/plugin.ts    | 637 ++++++++++++++++++
 .../auth-broker/src/modules/orgs/service.ts   | 623 +++++++++++++++++
 .../tests/org-team-membership.test.ts         | 401 +++++++++++
 src/cli/help.ts                               |  14 +-
 src/cli/spec.ts                               |   4 +
 src/commands/auth.ts                          | 147 ++++
 src/commands/org.ts                           | 396 +++++++++++
 src/commands/team.ts                          | 404 +++++++++++
 src/lib/auth-broker-client.ts                 | 123 ++++
 tests/auth-command.test.ts                    | 128 ++++
 tests/cli-command.test.ts                     | 100 ++-
 tests/org-team-command.test.ts                | 375 +++++++++++
 16 files changed, 4495 insertions(+), 3 deletions(-)
 create mode 100644 docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md
 create mode 100644 docs/plans/2026-03-13-teams-and-organizations-admin-semantics-plan.md
 create mode 100644 services/auth-broker/src/modules/orgs/plugin.ts
 create mode 100644 services/auth-broker/src/modules/orgs/service.ts
 create mode 100644 services/auth-broker/tests/org-team-membership.test.ts
 create mode 100644 src/commands/org.ts
 create mode 100644 src/commands/team.ts
 create mode 100644 src/lib/auth-broker-client.ts
 create mode 100644 tests/org-team-command.test.ts

diff --git a/docs/cli.md b/docs/cli.md
index b8660d683..1bf046f49 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -46,6 +46,9 @@ Current practical rule:
 | Command | Summary | Group |
 | --- | --- | --- |
 | `hack global` | Manage machine-wide infra (DNS/TLS, Caddy proxy, logs) | Global |
+| `hack auth` | Manage Hack auth sessions and recipient-side invitations | Global |
+| `hack org` | Manage organizations and org-scoped membership lifecycle | Global |
+| `hack team` | Manage teams and team-scoped membership lifecycle | Global |
 | `hack projects` | Show all projects (registry + running docker compose) | Global |
 | `hack status` | Show project status (shortcut for `hack projects --details`) | Global |
 | `hack usage` | Show resource usage across running projects | Global |
@@ -152,6 +155,445 @@ Options:
 | `--install`   | boolean | false           | Run mkcert -install before generating certs |
 | `--out <dir>` | string  | `~/.hack/certs` | Directory for generated cert/key            |
 
+### hack auth
+
+Usage: `hack auth <subcommand>`
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `login` | Open a browser and sign in to Hack auth |
+| `logout` | Clear the locally stored Hack auth session |
+| `status` | Show whether Hack auth is configured locally |
+| `whoami` | Resolve the current Hack auth identity via the broker |
+| `invites` | List pending invitations for the authenticated user |
+| `invite` | Act on a specific invitation |
+
+#### hack auth login
+
+Usage: `hack auth login [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--no-open` | boolean | false | Print the browser URL instead of opening it automatically |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+| `--redirect <url>` | string | - | Return to this URL after browser sign-in finishes |
+
+#### hack auth logout
+
+Usage: `hack auth logout [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack auth status
+
+Usage: `hack auth status [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+#### hack auth whoami
+
+Usage: `hack auth whoami [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+#### hack auth invites
+
+Usage: `hack auth invites [options]`
+
+Recipient-side lifecycle command. Lists pending org and team invites that the authenticated user can accept or decline explicitly.
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+#### hack auth invite
+
+Usage: `hack auth invite <subcommand>`
+
+Recipient-side invitation actions. Acceptance and decline stay under `hack auth` so admins cannot implicitly activate access for someone else.
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `accept` | Accept a pending invitation and activate membership |
+| `decline` | Decline a pending invitation and mark it removed |
+
+#### hack auth invite accept
+
+Usage: `hack auth invite accept <invite-id> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `invite-id` | string | yes | Pending invite identifier |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+#### hack auth invite decline
+
+Usage: `hack auth invite decline <invite-id> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `invite-id` | string | yes | Pending invite identifier |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+| `--broker-url <url>` | string | - | Override the Hack auth broker base URL |
+
+### hack org
+
+Usage: `hack org <subcommand>`
+
+Admin-side organization surface. Org membership is the parent grant for team access.
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `create` | Create an organization without creating any teams implicitly |
+| `list` | List organizations visible to the authenticated user |
+| `show` | Show one organization and its current membership context |
+| `member` | Manage org memberships and invitation lifecycle |
+
+#### hack org create
+
+Usage: `hack org create <slug> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `slug` | string | yes | Organization slug |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--name <display-name>` | string | - | Human-friendly name to store alongside the slug |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack org list
+
+Usage: `hack org list [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack org show
+
+Usage: `hack org show <org> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `org` | string | yes | Organization slug or id |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack org member
+
+Usage: `hack org member <subcommand>`
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List org members and pending invites |
+| `invite` | Create pending org membership for an email address |
+| `add` | Grant active org membership immediately to an existing user |
+| `remove` | Remove org membership or cancel a pending org invite |
+
+Lifecycle semantics:
+
+- `invite` creates `pending`
+- `add` creates `active`
+- `remove` transitions `pending` or `active` membership to `removed`
+- Removing org access is expected to preview and cascade affected team memberships in the same org
+
+#### hack org member list
+
+Usage: `hack org member list <org> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `org` | string | yes | Organization slug or id |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--state <pending|active|removed|all>` | string | - | Filter membership rows by lifecycle state |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+Notes:
+
+- Default output should focus on actionable memberships rather than removed audit history.
+- Use `--state removed` or `--state all` to inspect audit-visible removals.
+
+#### hack org member invite
+
+Usage: `hack org member invite <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `org` | string | yes | Organization slug or id |
+| `target` | string | yes | Invitee email address |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--team <team>` | string | - | Seed one or more team-scoped invites alongside the org invite |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack org member add
+
+Usage: `hack org member add <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `org` | string | yes | Organization slug or id |
+| `target` | string | yes | Existing Hack user id, slug, or email |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+Notes:
+
+- `add` is immediate-access semantics and should fail when the target cannot be resolved to an existing Hack user.
+- Use `invite` instead when the person does not already have a Hack account.
+
+#### hack org member remove
+
+Usage: `hack org member remove <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `org` | string | yes | Organization slug or id |
+| `target` | string | yes | Membership target to revoke or cancel |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+### hack team
+
+Usage: `hack team <subcommand>`
+
+Admin-side team surface. Team membership is always nested under one organization.
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `create` | Create a team inside an existing organization |
+| `list` | List teams for one organization |
+| `show` | Show one team and its parent org context |
+| `member` | Manage team memberships and invitation lifecycle |
+
+#### hack team create
+
+Usage: `hack team create <slug> --org <org> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `slug` | string | yes | Team slug |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--name <display-name>` | string | - | Human-friendly name to store alongside the slug |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+Notes:
+
+- Team creation requires explicit org targeting and does not add members implicitly.
+
+#### hack team list
+
+Usage: `hack team list --org <org> [options]`
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack team show
+
+Usage: `hack team show <team> --org <org> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `team` | string | yes | Team slug or id |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack team member
+
+Usage: `hack team member <subcommand>`
+
+Subcommands:
+
+| Subcommand | Summary |
+| --- | --- |
+| `list` | List team members and pending invites |
+| `invite` | Create pending team membership for an email address |
+| `add` | Grant active team membership immediately to an existing user |
+| `remove` | Remove team membership or cancel a pending team invite |
+
+Lifecycle semantics:
+
+- Team membership depends on active org membership in the same organization
+- `invite` creates `pending`
+- `add` creates `active`
+- `remove` transitions `pending` or `active` membership to `removed`
+- Removing team access does not change the parent org membership
+
+#### hack team member list
+
+Usage: `hack team member list <team> --org <org> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `team` | string | yes | Team slug or id |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--state <pending|active|removed|all>` | string | - | Filter membership rows by lifecycle state |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack team member invite
+
+Usage: `hack team member invite <team> --org <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `team` | string | yes | Team slug or id |
+| `target` | string | yes | Invitee email address |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+Notes:
+
+- Final implementation should pair this with an org invite when the recipient is not already an org member.
+
+#### hack team member add
+
+Usage: `hack team member add <team> --org <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `team` | string | yes | Team slug or id |
+| `target` | string | yes | Existing Hack user id, slug, or email |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
+#### hack team member remove
+
+Usage: `hack team member remove <team> --org <org> <target> [options]`
+
+Arguments:
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `team` | string | yes | Team slug or id |
+| `target` | string | yes | Membership target to revoke or cancel |
+
+Options:
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--org <org>` | string | - | Parent organization slug or id |
+| `--json` | boolean | false | Output JSON (machine-readable) |
+
 ### hack projects
 
 Usage: `hack projects [options]`
diff --git a/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md b/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md
new file mode 100644
index 000000000..b2dd7b596
--- /dev/null
+++ b/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md
@@ -0,0 +1,356 @@
+# Teams And Organizations Admin Semantics Design
+
+## Context
+
+Hack already has a real Hack-account model in flight:
+
+- `hack auth` establishes the local Hack session
+- broker-owned resources can already be scoped to `userId`, `organizationId`, and `teamId`
+- the auth broker already exposes active org/team metadata to CLI consumers
+
+What is still missing is the user-facing admin contract for:
+
+- creating organizations and teams
+- inviting or directly adding members
+- accepting, declining, and removing membership
+- explaining what happens when org and team access overlap
+
+Without that contract, implementation work will drift into hidden admin behavior, especially around team onboarding and org removal cascades.
+
+## Goals
+
+- Define a command surface that is explicit enough to implement directly.
+- Make pending, active, and removed membership states predictable.
+- Remove hidden privilege escalation and hidden access inheritance.
+- Keep the common onboarding path concise without making team access implicit.
+- Define UX rules for confirmations, audit visibility, and safe defaults.
+
+## Non-Goals
+
+- Full role and permission matrix design beyond minimal creator/admin defaults.
+- Billing, seat management, or SCIM-style bulk provisioning.
+- Team rename/archive or organization deletion flows.
+- Browser UI design for an admin console.
+
+## Approaches Considered
+
+### 1. Put everything under `hack auth`
+
+Examples:
+
+- `hack auth org create`
+- `hack auth team create`
+- `hack auth member invite`
+
+Pros:
+
+- Keeps account and admin flows under one top-level area.
+- Matches the fact that org/team data is tied to Hack auth.
+
+Cons:
+
+- Makes durable resources look like session subcommands.
+- Hurts discoverability for day-to-day admin work.
+- Becomes awkward once `org` and `team` have multiple sub-areas.
+
+### 2. Top-level `hack org` and `hack team` commands with invite acceptance under `hack auth` (recommended)
+
+Examples:
+
+- `hack org create`
+- `hack org member invite`
+- `hack team member remove`
+- `hack auth invite accept`
+
+Pros:
+
+- Keeps durable resources discoverable at the top level.
+- Keeps personal invitation acceptance under the existing identity/session area.
+- Maps cleanly to resource-local help and future growth.
+
+Cons:
+
+- Adds two new top-level command groups.
+- Requires clear docs for where invite acceptance lives.
+
+### 3. One generic `hack membership` surface
+
+Examples:
+
+- `hack membership invite --scope org:hack`
+- `hack membership remove --scope team:hack/cli`
+
+Pros:
+
+- Uniform implementation surface.
+- Easy to script mechanically.
+
+Cons:
+
+- Harder for humans to learn.
+- Pushes core semantics into flags instead of verbs.
+- Makes `hack help` less readable.
+
+## Recommended Design
+
+Adopt approach 2:
+
+- `hack org` owns organization resource management and org-scoped membership
+- `hack team` owns team resource management and team-scoped membership
+- `hack auth invite ...` owns recipient-side invite acceptance and decline
+
+This keeps resource management explicit while preserving a clear boundary:
+
+- admins act on orgs and teams
+- invited users act on their own invitations through `auth`
+
+## Resource Model
+
+### Organization
+
+An organization is the parent scope for one or more teams.
+
+Creating an organization:
+
+- creates the org record
+- makes the creator the initial active org owner/admin
+- does not create any teams implicitly
+
+### Team
+
+A team always belongs to exactly one organization.
+
+Creating a team:
+
+- requires an explicit `--org <org>`
+- creates the team record inside that organization
+- makes the creator an active team admin/manager for that team
+- does not invite or add any other members implicitly
+
+### Membership
+
+Membership is always scoped to exactly one resource:
+
+- organization membership
+- team membership
+
+Team membership depends on organization membership.
+
+That dependency is explicit:
+
+- an active team member must also be an active org member
+- a pending team invite for a non-org member must be created together with an org invite
+- removing org membership removes access to all teams in that org
+
+## Command Surface
+
+### Organization commands
+
+- `hack org create <slug> --name <display-name>`
+- `hack org list`
+- `hack org show <org>`
+- `hack org member list <org> [--state pending|active|removed|all]`
+- `hack org member invite <org> <email> [--team <team>...]`
+- `hack org member add <org> <user>`
+- `hack org member remove <org> <member>`
+
+### Team commands
+
+- `hack team create <slug> --org <org> --name <display-name>`
+- `hack team list --org <org>`
+- `hack team show <team> --org <org>`
+- `hack team member list <team> --org <org> [--state pending|active|removed|all]`
+- `hack team member invite <team> --org <org> <email>`
+- `hack team member add <team> --org <org> <user>`
+- `hack team member remove <team> --org <org> <member>`
+
+### Invite-recipient commands
+
+- `hack auth invites`
+- `hack auth invite accept <invite-id>`
+- `hack auth invite decline <invite-id>`
+
+## Command Semantics
+
+### `invite` means pending access
+
+`invite` is for an email-address target that may or may not already have a Hack account.
+
+Effects:
+
+- creates a membership in `pending`
+- does not grant access yet
+- sends or reissues an invitation link
+
+Safe default:
+
+- inviting an already-active member fails with an explicit `already_active` result
+- inviting an already-pending member fails with `already_pending` unless the user runs a future dedicated resend/reinvite command
+
+### `add` means immediate active access
+
+`add` is for a target that already resolves to an existing Hack user.
+
+Effects:
+
+- creates or reactivates the membership in `active`
+- grants access immediately
+- does not send an invite email
+
+Safe default:
+
+- `add` fails if the target cannot be resolved to an existing Hack user
+- the fallback guidance is to use `invite`
+
+### `remove` means access revoked or invite canceled
+
+`remove` is the admin-side verb for both pending and active memberships.
+
+Effects:
+
+- `pending -> removed`: cancels the invite before acceptance
+- `active -> removed`: revokes access immediately
+
+The CLI should say which path happened in plain language:
+
+- `Invite revoked`
+- `Access removed`
+
+### Recipient acceptance is explicit
+
+Only the invited user can move their own invite from `pending` to `active` through:
+
+- `hack auth invite accept <invite-id>`
+
+Decline is also explicit:
+
+- `hack auth invite decline <invite-id>`
+
+That transition results in:
+
+- `pending -> active` on accept
+- `pending -> removed` on decline
+
+## Membership Lifecycle Model
+
+### States
+
+- `pending`: membership has been proposed but does not grant access
+- `active`: membership grants access to the scope
+- `removed`: membership no longer grants access and remains visible in audit history
+
+### State transitions
+
+- `invite` creates `pending`
+- `add` creates `active`
+- `accept` moves `pending -> active`
+- `decline` moves `pending -> removed`
+- `remove` moves `pending -> removed`
+- `remove` moves `active -> removed`
+- `invite` on a previously removed membership creates a new pending invite attempt
+- `add` on a previously removed membership reactivates access immediately
+
+### Org and team coupling
+
+The rules for parent and child scopes are:
+
+- org membership is the parent grant
+- team membership is invalid without org membership
+- removing org membership cascades all pending and active team memberships in that org to `removed`
+- removing a team membership does not affect org membership
+
+### Recommended onboarding path
+
+The common case should be:
+
+- use `hack org member invite <org> <email> --team <team>...` for a new person
+- use `hack team member add <team> --org <org> <user>` only when the user is already an active org member
+
+That gives one explicit onboarding command for new people without requiring team commands to invent implicit org access.
+
+## Output And Audit Contract
+
+Every membership mutation should return the same core fields in human and JSON output:
+
+- `scopeType`: `organization` or `team`
+- `scopeId`
+- `memberUserId` when known
+- `memberEmail`
+- `state`
+- `previousState`
+- `changedBy`
+- `changedAt`
+- `reason`
+- `cascade` details when other memberships were affected
+
+### Audit visibility rules
+
+- default member lists show `pending` and `active`
+- `--state removed` or `--state all` exposes removed membership history
+- org member removal must show the team memberships removed by cascade
+- member detail views should show when a membership was invited, accepted, declined, or removed and by whom
+
+## Confirmation And Safety Rules
+
+### Confirmation
+
+Interactive destructive commands must show a preview before execution.
+
+Required confirmation cases:
+
+- removing an active org member
+- removing any org member when team memberships will cascade
+- removing multiple members in a future bulk flow
+
+Non-interactive automation must require `--yes` for destructive operations.
+
+### Safe defaults
+
+- no command may silently grant org access as a side effect of a team command
+- no command may silently delete audit history
+- no duplicate invite should be silently resent
+- no active member should be silently downgraded or re-added as part of another operation
+
+### Error guidance
+
+Errors should explain the next correct command, for example:
+
+- `user_not_found`: "Use \`hack org member invite\` for new users."
+- `org_membership_required`: "Add the user to the organization first, or use \`hack org member invite --team ...\`."
+- `already_pending`: "Use a future resend command or remove the pending invite first."
+
+## Minimal JSON Contract
+
+The machine-readable mutation payload should include:
+
+```json
+{
+  "ok": true,
+  "action": "invite",
+  "scopeType": "organization",
+  "scopeId": "hack",
+  "member": {
+    "userId": "user_123",
+    "email": "dev@example.com"
+  },
+  "membership": {
+    "state": "pending",
+    "previousState": null,
+    "changedAt": "2026-03-13T12:00:00.000Z",
+    "changedBy": "user_admin"
+  },
+  "cascade": {
+    "removedTeamMemberships": []
+  }
+}
+```
+
+The exact payload can grow, but these fields should remain stable enough for CLI, desktop, and MCP consumers.
+
+## Follow-On Work
+
+The next implementation slices should cover:
+
+1. broker persistence and APIs for org/team membership lifecycle
+2. CLI command registration and JSON output for `org`, `team`, and invite flows
+3. desktop/admin UX that uses the same lifecycle terms and confirmation rules
diff --git a/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-plan.md b/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-plan.md
new file mode 100644
index 000000000..34edb7550
--- /dev/null
+++ b/docs/plans/2026-03-13-teams-and-organizations-admin-semantics-plan.md
@@ -0,0 +1,330 @@
+# Teams And Organizations Admin Semantics Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Turn the approved org/team admin semantics into explicit broker APIs, CLI commands, and shared lifecycle outputs that make membership changes trustworthy.
+
+**Architecture:** Add first-class organization, team, and membership lifecycle records to `auth-broker`, then expose them through top-level `hack org` and `hack team` command groups plus recipient-side `hack auth invite` actions. Keep invite acceptance separate from admin mutations, keep team membership dependent on org membership, and make destructive operations preview their cascades before execution.
+
+**Tech Stack:** Bun, TypeScript, Elysia, Better Auth, Drizzle, Hack CLI command framework, JSON CLI output, future macOS consumer surfaces.
+
+---
+
+### Task 1: Lock the semantics into docs and command expectations
+
+**Files:**
+
+- Modify: `docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md`
+- Modify: `docs/cli.md`
+- Test: `tests/cli-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add command-spec coverage that expects the future top-level command groups and their immediate subcommands to appear in CLI help metadata:
+
+- `hack org`
+- `hack team`
+- `hack auth invite`
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts
+```
+
+Expected: FAIL because the command groups do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Update help/spec plumbing and docs so the command surface is visible even before all mutation handlers are implemented.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add docs/plans/2026-03-13-teams-and-organizations-admin-semantics-design.md docs/cli.md tests/cli-command.test.ts src/cli/spec.ts src/commands/auth.ts src/commands/org.ts src/commands/team.ts
+git commit -m "feat: scaffold org and team command groups"
+```
+
+### Task 2: Add broker data model for org, team, and membership lifecycle
+
+**Files:**
+
+- Modify: `services/auth-broker/src/db/schema.ts`
+- Modify: `services/auth-broker/src/db/ensure-columns.ts`
+- Modify: `services/auth-broker/src/types.ts`
+- Test: `services/auth-broker/tests/better-auth-schema.test.ts`
+- Test: `services/auth-broker/tests/index.test.ts`
+
+**Step 1: Write the failing test**
+
+Add schema/store tests that expect first-class records for:
+
+- organizations
+- teams
+- memberships with `pending`, `active`, and `removed` states
+- invite metadata and removal audit fields
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test --cwd services/auth-broker tests/better-auth-schema.test.ts tests/index.test.ts
+```
+
+Expected: FAIL because the lifecycle tables/columns do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Add the smallest schema and types that can persist:
+
+- org records
+- team records with parent org id
+- membership records with state and audit timestamps
+- optional invite linkage for pending memberships
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test --cwd services/auth-broker tests/better-auth-schema.test.ts tests/index.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add services/auth-broker/src/db/schema.ts services/auth-broker/src/db/ensure-columns.ts services/auth-broker/src/types.ts services/auth-broker/tests/better-auth-schema.test.ts services/auth-broker/tests/index.test.ts
+git commit -m "feat(auth-broker): add org and membership lifecycle schema"
+```
+
+### Task 3: Add broker lifecycle services and route authorization
+
+**Files:**
+
+- Modify: `services/auth-broker/src/app.ts`
+- Create: `services/auth-broker/src/modules/orgs/plugin.ts`
+- Create: `services/auth-broker/src/modules/orgs/service.ts`
+- Create: `services/auth-broker/src/modules/teams/plugin.ts`
+- Create: `services/auth-broker/src/modules/teams/service.ts`
+- Create: `services/auth-broker/src/modules/memberships/plugin.ts`
+- Create: `services/auth-broker/src/modules/memberships/service.ts`
+- Test: `services/auth-broker/tests/index.test.ts`
+- Test: `services/auth-broker/tests/session-auth.test.ts`
+
+**Step 1: Write the failing test**
+
+Add route tests for:
+
+- org create
+- team create under an org
+- org member invite/add/remove
+- team member invite/add/remove
+- invite accept/decline
+- org removal cascade preview for child team memberships
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test --cwd services/auth-broker tests/index.test.ts tests/session-auth.test.ts
+```
+
+Expected: FAIL because these routes do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Implement the service layer and protected routes with the approved semantics:
+
+- `invite` creates `pending`
+- `add` creates `active`
+- `accept` moves `pending -> active`
+- `decline` and `remove` move membership to `removed`
+- org removal previews and then applies team cascades
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test --cwd services/auth-broker tests/index.test.ts tests/session-auth.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add services/auth-broker/src/app.ts services/auth-broker/src/modules/orgs/plugin.ts services/auth-broker/src/modules/orgs/service.ts services/auth-broker/src/modules/teams/plugin.ts services/auth-broker/src/modules/teams/service.ts services/auth-broker/src/modules/memberships/plugin.ts services/auth-broker/src/modules/memberships/service.ts services/auth-broker/tests/index.test.ts services/auth-broker/tests/session-auth.test.ts
+git commit -m "feat(auth-broker): add org team and membership lifecycle routes"
+```
+
+### Task 4: Add CLI command groups and shared mutation rendering
+
+**Files:**
+
+- Modify: `src/cli/spec.ts`
+- Modify: `src/commands/auth.ts`
+- Create: `src/commands/org.ts`
+- Create: `src/commands/team.ts`
+- Create: `src/lib/membership-output.ts`
+- Test: `tests/cli-command.test.ts`
+- Test: `tests/auth-command.test.ts`
+
+**Step 1: Write the failing test**
+
+Add CLI tests for:
+
+- `hack org create`
+- `hack org member invite`
+- `hack org member add`
+- `hack org member remove`
+- `hack team create`
+- `hack team member invite`
+- `hack team member add`
+- `hack team member remove`
+- `hack auth invites`
+- `hack auth invite accept`
+- `hack auth invite decline`
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts tests/auth-command.test.ts
+```
+
+Expected: FAIL because the command handlers do not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Add CLI groups and formatters that:
+
+- call the broker lifecycle routes
+- print clear human summaries
+- emit stable JSON payloads with membership state transitions and cascade details
+- require `--yes` for destructive non-interactive removals
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts tests/auth-command.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/cli/spec.ts src/commands/auth.ts src/commands/org.ts src/commands/team.ts src/lib/membership-output.ts tests/cli-command.test.ts tests/auth-command.test.ts
+git commit -m "feat(cli): add org and team admin commands"
+```
+
+### Task 5: Add confirmation, cascade preview, and audit list behavior
+
+**Files:**
+
+- Modify: `src/commands/org.ts`
+- Modify: `src/commands/team.ts`
+- Modify: `services/auth-broker/src/modules/memberships/service.ts`
+- Test: `tests/cli-command.test.ts`
+- Test: `services/auth-broker/tests/index.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests that verify:
+
+- removing an org member previews affected team memberships
+- `--yes` bypasses interactive confirmation cleanly
+- member listing defaults to pending and active
+- `--state all` includes removed memberships with audit metadata
+
+**Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts && bun test --cwd services/auth-broker tests/index.test.ts
+```
+
+Expected: FAIL until preview and audit behaviors are implemented.
+
+**Step 3: Write minimal implementation**
+
+Implement preview-first destructive behavior and consistent list filters without adding bulk operations or advanced role editing.
+
+**Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts && bun test --cwd services/auth-broker tests/index.test.ts
+```
+
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/commands/org.ts src/commands/team.ts services/auth-broker/src/modules/memberships/service.ts tests/cli-command.test.ts services/auth-broker/tests/index.test.ts
+git commit -m "feat: add membership confirmation and audit views"
+```
+
+### Task 6: Final verification and docs cleanup
+
+**Files:**
+
+- Modify: `docs/cli.md`
+- Verify only
+
+**Step 1: Run focused verification**
+
+Run:
+
+```bash
+bun test tests/cli-command.test.ts tests/auth-command.test.ts
+bun test --cwd services/auth-broker tests/better-auth-schema.test.ts tests/index.test.ts tests/session-auth.test.ts
+```
+
+Expected: PASS
+
+**Step 2: Run repo quality gates**
+
+Run:
+
+```bash
+bun x ultracite fix
+bun x ultracite check
+bun test
+```
+
+Expected: PASS
+
+**Step 3: Sync follow-up docs**
+
+Make sure `docs/cli.md` and command help text match the shipped CLI behavior.
+
+**Step 4: Commit**
+
+```bash
+git add docs/cli.md
+git commit -m "docs: finalize org and team admin CLI semantics"
+```
diff --git a/services/auth-broker/src/app.ts b/services/auth-broker/src/app.ts
index 4a24fc68b..27bfcbbc4 100644
--- a/services/auth-broker/src/app.ts
+++ b/services/auth-broker/src/app.ts
@@ -30,6 +30,11 @@ import {
   InMemoryLinearSyncStore,
   type LinearSyncStore,
 } from "./modules/linear-sync-store/service.ts";
+import { createOrgsPlugin } from "./modules/orgs/plugin.ts";
+import {
+  InMemoryOrgTeamsStore,
+  type OrgTeamsStore,
+} from "./modules/orgs/service.ts";
 import { createProvidersPlugin } from "./modules/providers/plugin.ts";
 import { createSharedMiddlewarePlugin } from "./plugins/shared-middleware.ts";
 
@@ -40,6 +45,7 @@ export type CreateAuthBrokerAppOptions = {
   readonly linearSyncStore?: LinearSyncStore;
   readonly linearConnectionStore?: LinearConnectionStore;
   readonly linearAutosyncStore?: LinearAutosyncStore;
+  readonly orgTeamsStore?: OrgTeamsStore;
 };
 
 /**
@@ -52,6 +58,7 @@ export function createAuthBrokerApp({
   linearSyncStore: externalLinearSyncStore,
   linearConnectionStore: externalLinearConnectionStore,
   linearAutosyncStore: externalLinearAutosyncStore,
+  orgTeamsStore: externalOrgTeamsStore,
 }: CreateAuthBrokerAppOptions) {
   const flowStore =
     externalStore ?? new FlowStore({ filePath: config.flowStorePath });
@@ -63,6 +70,7 @@ export function createAuthBrokerApp({
     externalLinearConnectionStore ?? createDefaultLinearConnectionStore();
   const linearAutosyncStore =
     externalLinearAutosyncStore ?? createDefaultLinearAutosyncStore();
+  const orgTeamsStore = externalOrgTeamsStore ?? createDefaultOrgTeamsStore();
   let flowSweepTimer: ReturnType<typeof setInterval> | null = null;
 
   return new Elysia({
@@ -133,6 +141,12 @@ export function createAuthBrokerApp({
         betterAuthRuntime,
       })
     )
+    .use(
+      createOrgsPlugin({
+        store: orgTeamsStore,
+        betterAuthRuntime,
+      })
+    )
     .use(
       createLinearSyncStorePlugin({
         syncStore: linearSyncStore,
@@ -203,6 +217,10 @@ function createDefaultLinearAutosyncStore(): LinearAutosyncStore {
   }
 }
 
+function createDefaultOrgTeamsStore(): OrgTeamsStore {
+  return new InMemoryOrgTeamsStore();
+}
+
 /**
  * Identify route paths that are intentionally GET-only in broker v1.
  */
diff --git a/services/auth-broker/src/modules/orgs/plugin.ts b/services/auth-broker/src/modules/orgs/plugin.ts
new file mode 100644
index 000000000..35e16af87
--- /dev/null
+++ b/services/auth-broker/src/modules/orgs/plugin.ts
@@ -0,0 +1,637 @@
+import { Elysia, t } from "elysia";
+
+import type { BetterAuthRuntime } from "../../better-auth.ts";
+import { resolveBetterAuthSession } from "../better-auth/session.ts";
+import type { MembershipState, OrgTeamsStore } from "./service.ts";
+
+export function createOrgsPlugin(input: {
+  readonly store: OrgTeamsStore;
+  readonly betterAuthRuntime: BetterAuthRuntime;
+}) {
+  return new Elysia({
+    name: "hack-auth-broker.orgs",
+  })
+    .get("/v1/auth/orgs", async ({ request, set }) => {
+      const session = await requireSession({
+        runtime: input.betterAuthRuntime,
+        request,
+        set,
+      });
+      if (!session) {
+        return;
+      }
+      const organizations = await input.store.listOrganizations({
+        actorUserId: session.userId,
+      });
+      return { ok: true, organizations } as const;
+    })
+    .post(
+      "/v1/auth/orgs",
+      async ({ body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const created = await input.store.createOrganization({
+          slug: body.slug,
+          name: body.name ?? body.slug,
+          actorUserId: session.userId,
+          actorEmail: session.email,
+        });
+        return {
+          ok: true,
+          organization: created.organization,
+          membership: created.membership,
+        } as const;
+      },
+      {
+        body: t.Object({
+          slug: t.String(),
+          name: t.Optional(t.String()),
+        }),
+      }
+    )
+    .get(
+      "/v1/auth/orgs/:org",
+      async ({ params, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: params.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        return { ok: true, organization } as const;
+      },
+      { params: t.Object({ org: t.String() }) }
+    )
+    .get(
+      "/v1/auth/orgs/:org/members",
+      async ({ params, query, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: params.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        const memberships = await input.store.listMembers({
+          scope: "organization",
+          orgKey: params.org,
+          state: normalizeState({ value: query.state }),
+        });
+        return { ok: true, memberships } as const;
+      },
+      {
+        params: t.Object({ org: t.String() }),
+        query: t.Object({ state: t.Optional(t.String()) }),
+      }
+    )
+    .post(
+      "/v1/auth/orgs/:org/members/invite",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: params.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        const invited = await input.store.inviteMember({
+          scope: "organization",
+          orgKey: params.org,
+          target: body.target,
+          teamTargets: body.teams ?? [],
+        });
+        if (!invited) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        return {
+          ok: true,
+          invitation: invited.invitation,
+          membership: invited.membership,
+        } as const;
+      },
+      {
+        params: t.Object({ org: t.String() }),
+        body: t.Object({
+          target: t.String(),
+          teams: t.Optional(t.Array(t.String())),
+        }),
+      }
+    )
+    .post(
+      "/v1/auth/orgs/:org/members/add",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: params.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        const membership = await input.store.addMember({
+          scope: "organization",
+          orgKey: params.org,
+          target: body.target,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      {
+        params: t.Object({ org: t.String() }),
+        body: t.Object({ target: t.String() }),
+      }
+    )
+    .post(
+      "/v1/auth/orgs/:org/members/remove",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: params.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        const membership = await input.store.removeMember({
+          scope: "organization",
+          orgKey: params.org,
+          target: body.target,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "org_membership_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      {
+        params: t.Object({ org: t.String() }),
+        body: t.Object({ target: t.String() }),
+      }
+    )
+    .get(
+      "/v1/auth/teams",
+      async ({ query, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const teams = await input.store.listTeams({
+          orgKey: normalizeOptionalString(query.org),
+          actorUserId: session.userId,
+        });
+        return { ok: true, teams } as const;
+      },
+      { query: t.Object({ org: t.Optional(t.String()) }) }
+    )
+    .post(
+      "/v1/auth/teams",
+      async ({ body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const organization = await input.store.getOrganization({
+          orgKey: body.org,
+          actorUserId: session.userId,
+        });
+        if (!organization) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        const created = await input.store.createTeam({
+          slug: body.slug,
+          name: body.name ?? body.slug,
+          orgKey: body.org,
+          actorUserId: session.userId,
+          actorEmail: session.email,
+        });
+        if (!created) {
+          set.status = 404;
+          return { ok: false, error: "org_not_found" } as const;
+        }
+        return {
+          ok: true,
+          team: created.team,
+          membership: created.membership,
+        } as const;
+      },
+      {
+        body: t.Object({
+          slug: t.String(),
+          org: t.String(),
+          name: t.Optional(t.String()),
+        }),
+      }
+    )
+    .get(
+      "/v1/auth/teams/:team",
+      async ({ params, query, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const team = await input.store.getTeam({
+          teamKey: params.team,
+          orgKey: normalizeOptionalString(query.org),
+          actorUserId: session.userId,
+        });
+        if (!team) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        return { ok: true, team } as const;
+      },
+      {
+        params: t.Object({ team: t.String() }),
+        query: t.Object({ org: t.Optional(t.String()) }),
+      }
+    )
+    .get(
+      "/v1/auth/teams/:team/members",
+      async ({ params, query, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const orgKey = normalizeOptionalString(query.org);
+        if (!orgKey) {
+          set.status = 400;
+          return { ok: false, error: "org_required" } as const;
+        }
+        const team = await input.store.getTeam({
+          teamKey: params.team,
+          orgKey,
+          actorUserId: session.userId,
+        });
+        if (!team) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        const memberships = await input.store.listMembers({
+          scope: "team",
+          orgKey,
+          teamKey: params.team,
+          state: normalizeState({ value: query.state }),
+        });
+        return { ok: true, memberships } as const;
+      },
+      {
+        params: t.Object({ team: t.String() }),
+        query: t.Object({
+          org: t.Optional(t.String()),
+          state: t.Optional(t.String()),
+        }),
+      }
+    )
+    .post(
+      "/v1/auth/teams/:team/members/invite",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const team = await input.store.getTeam({
+          teamKey: params.team,
+          orgKey: body.org,
+          actorUserId: session.userId,
+        });
+        if (!team) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        const hasParentOrgMembership = await hasActiveParentOrgMembership({
+          store: input.store,
+          orgKey: body.org,
+          target: body.target,
+        });
+        if (!hasParentOrgMembership) {
+          set.status = 409;
+          return {
+            ok: false,
+            error: "team_member_requires_active_org_membership",
+          } as const;
+        }
+        const invited = await input.store.inviteMember({
+          scope: "team",
+          orgKey: body.org,
+          teamKey: params.team,
+          target: body.target,
+        });
+        if (!invited) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        return {
+          ok: true,
+          invitation: invited.invitation,
+          membership: invited.membership,
+        } as const;
+      },
+      {
+        params: t.Object({ team: t.String() }),
+        body: t.Object({
+          org: t.String(),
+          target: t.String(),
+        }),
+      }
+    )
+    .post(
+      "/v1/auth/teams/:team/members/add",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const team = await input.store.getTeam({
+          teamKey: params.team,
+          orgKey: body.org,
+          actorUserId: session.userId,
+        });
+        if (!team) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        const hasParentOrgMembership = await hasActiveParentOrgMembership({
+          store: input.store,
+          orgKey: body.org,
+          target: body.target,
+        });
+        if (!hasParentOrgMembership) {
+          set.status = 409;
+          return {
+            ok: false,
+            error: "team_member_requires_active_org_membership",
+          } as const;
+        }
+        const membership = await input.store.addMember({
+          scope: "team",
+          orgKey: body.org,
+          teamKey: params.team,
+          target: body.target,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      {
+        params: t.Object({ team: t.String() }),
+        body: t.Object({
+          org: t.String(),
+          target: t.String(),
+        }),
+      }
+    )
+    .post(
+      "/v1/auth/teams/:team/members/remove",
+      async ({ params, body, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        const team = await input.store.getTeam({
+          teamKey: params.team,
+          orgKey: body.org,
+          actorUserId: session.userId,
+        });
+        if (!team) {
+          set.status = 404;
+          return { ok: false, error: "team_not_found" } as const;
+        }
+        const membership = await input.store.removeMember({
+          scope: "team",
+          orgKey: body.org,
+          teamKey: params.team,
+          target: body.target,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "team_membership_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      {
+        params: t.Object({ team: t.String() }),
+        body: t.Object({
+          org: t.String(),
+          target: t.String(),
+        }),
+      }
+    )
+    .get("/v1/auth/invitations", async ({ request, set }) => {
+      const session = await requireSession({
+        runtime: input.betterAuthRuntime,
+        request,
+        set,
+      });
+      if (!session) {
+        return;
+      }
+      if (!session.email) {
+        set.status = 400;
+        return { ok: false, error: "better_auth_email_required" } as const;
+      }
+      const invitations = await input.store.listInvitationsForEmail({
+        email: session.email,
+      });
+      return { ok: true, invitations } as const;
+    })
+    .post(
+      "/v1/auth/invitations/:inviteId/accept",
+      async ({ params, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        if (!session.email) {
+          set.status = 400;
+          return { ok: false, error: "better_auth_email_required" } as const;
+        }
+        const membership = await input.store.acceptInvitation({
+          inviteId: params.inviteId,
+          userId: session.userId,
+          email: session.email,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "invitation_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      { params: t.Object({ inviteId: t.String() }) }
+    )
+    .post(
+      "/v1/auth/invitations/:inviteId/decline",
+      async ({ params, request, set }) => {
+        const session = await requireSession({
+          runtime: input.betterAuthRuntime,
+          request,
+          set,
+        });
+        if (!session) {
+          return;
+        }
+        if (!session.email) {
+          set.status = 400;
+          return { ok: false, error: "better_auth_email_required" } as const;
+        }
+        const membership = await input.store.declineInvitation({
+          inviteId: params.inviteId,
+          email: session.email,
+        });
+        if (!membership) {
+          set.status = 404;
+          return { ok: false, error: "invitation_not_found" } as const;
+        }
+        return { ok: true, membership } as const;
+      },
+      { params: t.Object({ inviteId: t.String() }) }
+    );
+}
+
+async function requireSession(input: {
+  readonly runtime: BetterAuthRuntime;
+  readonly request: Request;
+  readonly set: { status?: number };
+}) {
+  const session = await resolveBetterAuthSession({
+    runtime: input.runtime,
+    request: input.request,
+  });
+  if (session.enabled && !session.session) {
+    input.set.status = 401;
+    return null;
+  }
+  return session.session;
+}
+
+function normalizeOptionalString(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizeState(input: {
+  readonly value: string | undefined;
+}): MembershipState | "all" {
+  const normalized = normalizeOptionalString(input.value);
+  if (
+    normalized === "pending" ||
+    normalized === "active" ||
+    normalized === "removed" ||
+    normalized === "all"
+  ) {
+    return normalized;
+  }
+  return "all";
+}
+
+async function hasActiveParentOrgMembership(input: {
+  readonly store: OrgTeamsStore;
+  readonly orgKey: string;
+  readonly target: string;
+}): Promise<boolean> {
+  const memberships = await input.store.listMembers({
+    scope: "organization",
+    orgKey: input.orgKey,
+    state: "active",
+  });
+  const normalizedTarget = input.target.trim();
+  return memberships.some((membership) => {
+    const membershipTarget = membership.target.trim();
+    const membershipEmail = membership.email?.trim() ?? "";
+    return (
+      membershipTarget === normalizedTarget ||
+      membershipEmail === normalizedTarget
+    );
+  });
+}
diff --git a/services/auth-broker/src/modules/orgs/service.ts b/services/auth-broker/src/modules/orgs/service.ts
new file mode 100644
index 000000000..5993cd250
--- /dev/null
+++ b/services/auth-broker/src/modules/orgs/service.ts
@@ -0,0 +1,623 @@
+import { randomUUID } from "node:crypto";
+
+export type MembershipState = "pending" | "active" | "removed";
+
+export type OrganizationRecord = {
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+export type TeamRecord = {
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+  readonly organizationId: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+export type MembershipRecord = {
+  readonly id: string;
+  readonly scope: "organization" | "team";
+  readonly state: MembershipState;
+  readonly organizationId: string;
+  readonly teamId: string | null;
+  readonly userId: string | null;
+  readonly email: string | null;
+  readonly target: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+export type InvitationRecord = {
+  readonly id: string;
+  readonly scope: "organization" | "team";
+  readonly organizationId: string;
+  readonly teamId: string | null;
+  readonly email: string;
+  readonly status: "pending" | "accepted" | "removed";
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly teamTargets: readonly string[];
+};
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type OrgTeamsStore = {
+  readonly createOrganization: (input: {
+    readonly slug: string;
+    readonly name: string;
+    readonly actorUserId: string;
+    readonly actorEmail: string | null;
+  }) => MaybePromise<{
+    readonly organization: OrganizationRecord;
+    readonly membership: MembershipRecord;
+  }>;
+  readonly listOrganizations: (input: {
+    readonly actorUserId: string;
+  }) => MaybePromise<readonly OrganizationRecord[]>;
+  readonly getOrganization: (input: {
+    readonly orgKey: string;
+    readonly actorUserId: string;
+  }) => MaybePromise<OrganizationRecord | null>;
+  readonly createTeam: (input: {
+    readonly slug: string;
+    readonly name: string;
+    readonly orgKey: string;
+    readonly actorUserId: string;
+    readonly actorEmail: string | null;
+  }) => MaybePromise<{
+    readonly team: TeamRecord;
+    readonly membership: MembershipRecord;
+  } | null>;
+  readonly listTeams: (input: {
+    readonly orgKey: string | null;
+    readonly actorUserId: string;
+  }) => MaybePromise<readonly TeamRecord[]>;
+  readonly getTeam: (input: {
+    readonly teamKey: string;
+    readonly orgKey: string | null;
+    readonly actorUserId: string;
+  }) => MaybePromise<TeamRecord | null>;
+  readonly listMembers: (input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly state: MembershipState | "all";
+  }) => MaybePromise<readonly MembershipRecord[]>;
+  readonly inviteMember: (input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+    readonly teamTargets?: readonly string[];
+  }) => MaybePromise<{
+    readonly invitation: InvitationRecord;
+    readonly membership: MembershipRecord;
+  } | null>;
+  readonly addMember: (input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+  }) => MaybePromise<MembershipRecord | null>;
+  readonly removeMember: (input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+  }) => MaybePromise<MembershipRecord | null>;
+  readonly listInvitationsForEmail: (input: {
+    readonly email: string;
+  }) => MaybePromise<readonly InvitationRecord[]>;
+  readonly acceptInvitation: (input: {
+    readonly inviteId: string;
+    readonly userId: string;
+    readonly email: string;
+  }) => MaybePromise<MembershipRecord | null>;
+  readonly declineInvitation: (input: {
+    readonly inviteId: string;
+    readonly email: string;
+  }) => MaybePromise<MembershipRecord | null>;
+};
+
+export class InMemoryOrgTeamsStore implements OrgTeamsStore {
+  private readonly organizations = new Map<string, OrganizationRecord>();
+  private readonly teams = new Map<string, TeamRecord>();
+  private readonly activeMemberships = new Map<string, MembershipRecord>();
+  private readonly removedMemberships = new Map<string, MembershipRecord>();
+  private readonly invitations = new Map<string, InvitationRecord>();
+
+  createOrganization(input: {
+    readonly slug: string;
+    readonly name: string;
+    readonly actorUserId: string;
+    readonly actorEmail: string | null;
+  }): MaybePromise<{
+    readonly organization: OrganizationRecord;
+    readonly membership: MembershipRecord;
+  }> {
+    const now = new Date().toISOString();
+    const organization: OrganizationRecord = {
+      id: randomUUID(),
+      slug: input.slug.trim(),
+      name: input.name.trim() || input.slug.trim(),
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.organizations.set(organization.id, organization);
+    const membership = this.createActiveMembership({
+      scope: "organization",
+      organizationId: organization.id,
+      teamId: null,
+      userId: input.actorUserId,
+      email: input.actorEmail,
+      target: input.actorUserId,
+    });
+    return { organization, membership };
+  }
+
+  listOrganizations(input: {
+    readonly actorUserId: string;
+  }): MaybePromise<readonly OrganizationRecord[]> {
+    const allowedOrgIds = new Set(
+      [...this.activeMemberships.values()]
+        .filter(
+          (membership) =>
+            membership.scope === "organization" &&
+            membership.userId === input.actorUserId
+        )
+        .map((membership) => membership.organizationId)
+    );
+    return [...this.organizations.values()].filter((organization) =>
+      allowedOrgIds.has(organization.id)
+    );
+  }
+
+  getOrganization(input: {
+    readonly orgKey: string;
+    readonly actorUserId: string;
+  }): MaybePromise<OrganizationRecord | null> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return null;
+    }
+    const allowed = [...this.activeMemberships.values()].some(
+      (membership) =>
+        membership.scope === "organization" &&
+        membership.organizationId === organization.id &&
+        membership.userId === input.actorUserId
+    );
+    return allowed ? organization : null;
+  }
+
+  createTeam(input: {
+    readonly slug: string;
+    readonly name: string;
+    readonly orgKey: string;
+    readonly actorUserId: string;
+    readonly actorEmail: string | null;
+  }): MaybePromise<{
+    readonly team: TeamRecord;
+    readonly membership: MembershipRecord;
+  } | null> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return null;
+    }
+    const now = new Date().toISOString();
+    const team: TeamRecord = {
+      id: randomUUID(),
+      slug: input.slug.trim(),
+      name: input.name.trim() || input.slug.trim(),
+      organizationId: organization.id,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.teams.set(team.id, team);
+    const membership = this.createActiveMembership({
+      scope: "team",
+      organizationId: organization.id,
+      teamId: team.id,
+      userId: input.actorUserId,
+      email: input.actorEmail,
+      target: input.actorUserId,
+    });
+    return { team, membership };
+  }
+
+  listTeams(input: {
+    readonly orgKey: string | null;
+    readonly actorUserId: string;
+  }): MaybePromise<readonly TeamRecord[]> {
+    const allowedTeamIds = new Set(
+      [...this.activeMemberships.values()]
+        .filter(
+          (membership) =>
+            membership.scope === "team" &&
+            membership.userId === input.actorUserId
+        )
+        .map((membership) => membership.teamId)
+        .filter((teamId): teamId is string => typeof teamId === "string")
+    );
+    const organization = input.orgKey
+      ? this.findOrganization({ orgKey: input.orgKey })
+      : null;
+    return [...this.teams.values()].filter((team) => {
+      if (organization && team.organizationId !== organization.id) {
+        return false;
+      }
+      return allowedTeamIds.has(team.id);
+    });
+  }
+
+  getTeam(input: {
+    readonly teamKey: string;
+    readonly orgKey: string | null;
+    readonly actorUserId: string;
+  }): MaybePromise<TeamRecord | null> {
+    const team = this.findTeam({
+      teamKey: input.teamKey,
+      orgKey: input.orgKey,
+    });
+    if (!team) {
+      return null;
+    }
+    const allowed = [...this.activeMemberships.values()].some(
+      (membership) =>
+        membership.scope === "team" &&
+        membership.teamId === team.id &&
+        membership.userId === input.actorUserId
+    );
+    return allowed ? team : null;
+  }
+
+  listMembers(input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly state: MembershipState | "all";
+  }): MaybePromise<readonly MembershipRecord[]> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return [];
+    }
+    const team =
+      input.scope === "team"
+        ? this.findTeam({ teamKey: input.teamKey ?? "", orgKey: input.orgKey })
+        : null;
+    const pending = [...this.invitations.values()]
+      .filter((invitation) => invitation.status === "pending")
+      .filter(
+        (invitation) =>
+          invitation.scope === input.scope &&
+          invitation.organizationId === organization.id &&
+          invitation.teamId === (team?.id ?? null)
+      )
+      .map((invitation) => this.toPendingMembership({ invitation }));
+    const active = [...this.activeMemberships.values()].filter(
+      (membership) =>
+        membership.scope === input.scope &&
+        membership.organizationId === organization.id &&
+        membership.teamId === (team?.id ?? null)
+    );
+    const removed = [...this.removedMemberships.values()].filter(
+      (membership) =>
+        membership.scope === input.scope &&
+        membership.organizationId === organization.id &&
+        membership.teamId === (team?.id ?? null)
+    );
+    if (input.state === "pending") {
+      return pending;
+    }
+    if (input.state === "active") {
+      return active;
+    }
+    if (input.state === "removed") {
+      return removed;
+    }
+    return [...pending, ...active, ...removed];
+  }
+
+  inviteMember(input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+    readonly teamTargets?: readonly string[];
+  }): MaybePromise<{
+    readonly invitation: InvitationRecord;
+    readonly membership: MembershipRecord;
+  } | null> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return null;
+    }
+    const team =
+      input.scope === "team"
+        ? this.findTeam({ teamKey: input.teamKey ?? "", orgKey: input.orgKey })
+        : null;
+    if (input.scope === "team" && !team) {
+      return null;
+    }
+    const now = new Date().toISOString();
+    const invitation: InvitationRecord = {
+      id: randomUUID(),
+      scope: input.scope,
+      organizationId: organization.id,
+      teamId: team?.id ?? null,
+      email: input.target.trim(),
+      status: "pending",
+      createdAt: now,
+      updatedAt: now,
+      teamTargets: [...(input.teamTargets ?? [])],
+    };
+    this.invitations.set(invitation.id, invitation);
+    return {
+      invitation,
+      membership: this.toPendingMembership({ invitation }),
+    };
+  }
+
+  addMember(input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+  }): MaybePromise<MembershipRecord | null> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return null;
+    }
+    const team =
+      input.scope === "team"
+        ? this.findTeam({ teamKey: input.teamKey ?? "", orgKey: input.orgKey })
+        : null;
+    if (input.scope === "team" && !team) {
+      return null;
+    }
+    return this.createActiveMembership({
+      scope: input.scope,
+      organizationId: organization.id,
+      teamId: team?.id ?? null,
+      userId: input.target.trim(),
+      email: null,
+      target: input.target.trim(),
+    });
+  }
+
+  removeMember(input: {
+    readonly scope: "organization" | "team";
+    readonly orgKey: string;
+    readonly teamKey?: string | null;
+    readonly target: string;
+  }): MaybePromise<MembershipRecord | null> {
+    const organization = this.findOrganization({ orgKey: input.orgKey });
+    if (!organization) {
+      return null;
+    }
+    const team =
+      input.scope === "team"
+        ? this.findTeam({ teamKey: input.teamKey ?? "", orgKey: input.orgKey })
+        : null;
+    if (input.scope === "team" && !team) {
+      return null;
+    }
+    const normalizedTarget = input.target.trim();
+    for (const invitation of this.invitations.values()) {
+      if (
+        invitation.status === "pending" &&
+        invitation.scope === input.scope &&
+        invitation.organizationId === organization.id &&
+        invitation.teamId === (team?.id ?? null) &&
+        invitation.email === normalizedTarget
+      ) {
+        const removed: InvitationRecord = {
+          ...invitation,
+          status: "removed",
+          updatedAt: new Date().toISOString(),
+        };
+        this.invitations.set(invitation.id, removed);
+        const membership = this.toRemovedMembership({
+          scope: invitation.scope,
+          organizationId: invitation.organizationId,
+          teamId: invitation.teamId,
+          userId: null,
+          email: invitation.email,
+          target: invitation.email,
+        });
+        this.removedMemberships.set(membership.id, membership);
+        return membership;
+      }
+    }
+
+    for (const [key, membership] of this.activeMemberships.entries()) {
+      if (
+        membership.scope === input.scope &&
+        membership.organizationId === organization.id &&
+        membership.teamId === (team?.id ?? null) &&
+        membership.target === normalizedTarget
+      ) {
+        this.activeMemberships.delete(key);
+        const removed = this.toRemovedMembership({
+          scope: membership.scope,
+          organizationId: membership.organizationId,
+          teamId: membership.teamId,
+          userId: membership.userId,
+          email: membership.email,
+          target: membership.target,
+        });
+        this.removedMemberships.set(removed.id, removed);
+        return removed;
+      }
+    }
+    return null;
+  }
+
+  listInvitationsForEmail(input: {
+    readonly email: string;
+  }): MaybePromise<readonly InvitationRecord[]> {
+    const normalizedEmail = input.email.trim();
+    return [...this.invitations.values()].filter(
+      (invitation) =>
+        invitation.status === "pending" && invitation.email === normalizedEmail
+    );
+  }
+
+  acceptInvitation(input: {
+    readonly inviteId: string;
+    readonly userId: string;
+    readonly email: string;
+  }): MaybePromise<MembershipRecord | null> {
+    const invitation = this.invitations.get(input.inviteId);
+    if (
+      !invitation ||
+      invitation.status !== "pending" ||
+      invitation.email !== input.email.trim()
+    ) {
+      return null;
+    }
+    this.invitations.set(invitation.id, {
+      ...invitation,
+      status: "accepted",
+      updatedAt: new Date().toISOString(),
+    });
+    return this.createActiveMembership({
+      scope: invitation.scope,
+      organizationId: invitation.organizationId,
+      teamId: invitation.teamId,
+      userId: input.userId,
+      email: input.email.trim(),
+      target: input.userId,
+    });
+  }
+
+  declineInvitation(input: {
+    readonly inviteId: string;
+    readonly email: string;
+  }): MaybePromise<MembershipRecord | null> {
+    const invitation = this.invitations.get(input.inviteId);
+    if (
+      !invitation ||
+      invitation.status !== "pending" ||
+      invitation.email !== input.email.trim()
+    ) {
+      return null;
+    }
+    this.invitations.set(invitation.id, {
+      ...invitation,
+      status: "removed",
+      updatedAt: new Date().toISOString(),
+    });
+    const removed = this.toRemovedMembership({
+      scope: invitation.scope,
+      organizationId: invitation.organizationId,
+      teamId: invitation.teamId,
+      userId: null,
+      email: invitation.email,
+      target: invitation.email,
+    });
+    this.removedMemberships.set(removed.id, removed);
+    return removed;
+  }
+
+  private findOrganization(input: {
+    readonly orgKey: string;
+  }): OrganizationRecord | null {
+    const key = input.orgKey.trim();
+    for (const organization of this.organizations.values()) {
+      if (organization.id === key || organization.slug === key) {
+        return organization;
+      }
+    }
+    return null;
+  }
+
+  private findTeam(input: {
+    readonly teamKey: string;
+    readonly orgKey: string | null;
+  }): TeamRecord | null {
+    const key = input.teamKey.trim();
+    const organization = input.orgKey
+      ? this.findOrganization({ orgKey: input.orgKey })
+      : null;
+    for (const team of this.teams.values()) {
+      if (!(team.id === key || team.slug === key)) {
+        continue;
+      }
+      if (organization && team.organizationId !== organization.id) {
+        continue;
+      }
+      return team;
+    }
+    return null;
+  }
+
+  private createActiveMembership(input: {
+    readonly scope: "organization" | "team";
+    readonly organizationId: string;
+    readonly teamId: string | null;
+    readonly userId: string | null;
+    readonly email: string | null;
+    readonly target: string;
+  }): MembershipRecord {
+    const now = new Date().toISOString();
+    const membership: MembershipRecord = {
+      id: randomUUID(),
+      scope: input.scope,
+      state: "active",
+      organizationId: input.organizationId,
+      teamId: input.teamId,
+      userId: input.userId,
+      email: input.email,
+      target: input.target,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.activeMemberships.set(membership.id, membership);
+    return membership;
+  }
+
+  private toPendingMembership(input: {
+    readonly invitation: InvitationRecord;
+  }): MembershipRecord {
+    return {
+      id: input.invitation.id,
+      scope: input.invitation.scope,
+      state: "pending",
+      organizationId: input.invitation.organizationId,
+      teamId: input.invitation.teamId,
+      userId: null,
+      email: input.invitation.email,
+      target: input.invitation.email,
+      createdAt: input.invitation.createdAt,
+      updatedAt: input.invitation.updatedAt,
+    };
+  }
+
+  private toRemovedMembership(input: {
+    readonly scope: "organization" | "team";
+    readonly organizationId: string;
+    readonly teamId: string | null;
+    readonly userId: string | null;
+    readonly email: string | null;
+    readonly target: string;
+  }): MembershipRecord {
+    const now = new Date().toISOString();
+    return {
+      id: randomUUID(),
+      scope: input.scope,
+      state: "removed",
+      organizationId: input.organizationId,
+      teamId: input.teamId,
+      userId: input.userId,
+      email: input.email,
+      target: input.target,
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+}
diff --git a/services/auth-broker/tests/org-team-membership.test.ts b/services/auth-broker/tests/org-team-membership.test.ts
new file mode 100644
index 000000000..3a57f86b0
--- /dev/null
+++ b/services/auth-broker/tests/org-team-membership.test.ts
@@ -0,0 +1,401 @@
+import { describe, expect, test } from "bun:test";
+
+import type { BetterAuthRuntime } from "../src/better-auth.ts";
+import { createAuthBrokerApp } from "../src/index.ts";
+import { InMemoryOrgTeamsStore } from "../src/modules/orgs/service.ts";
+
+type BetterAuthAuth = NonNullable<BetterAuthRuntime["auth"]>;
+type BetterAuthSession = Awaited<
+  ReturnType<BetterAuthAuth["api"]["getSession"]>
+>;
+
+function createTestConfig() {
+  return {
+    port: 0,
+    host: "127.0.0.1",
+    publicBaseUrl: "http://127.0.0.1:8080",
+    flowStorePath: ".data/test-oauth-flows.json",
+    githubClientId: "test-client-id",
+    githubClientSecret: "test-client-secret",
+    githubScopes: "repo,read:org",
+    githubAuthorizeUrl: "https://github.com/login/oauth/authorize",
+    githubTokenUrl: "https://github.com/login/oauth/access_token",
+    githubApiBaseUrl: "https://api.github.com",
+    githubRedirectUri: "http://127.0.0.1:8080/gh/callback",
+    betterAuthGitHubAutoProvisionUsers: false,
+    betterAuthLinearAutoProvisionUsers: false,
+    linearClientId: "linear-client-id",
+    linearClientSecret: "linear-client-secret",
+    linearActor: "app",
+    linearScopes: "read,write,app:mentionable,app:assignable",
+    linearAuthorizeUrl: "https://linear.app/oauth/authorize",
+    linearTokenUrl: "https://api.linear.app/oauth/token",
+    linearApiBaseUrl: "https://api.linear.app/graphql",
+    linearRedirectUri: "http://127.0.0.1:8080/linear/callback",
+    linearWebhookPath: "/linear/webhooks",
+    flowTtlMs: 60_000,
+    flowSweepIntervalMs: 60_000,
+  } as const;
+}
+
+function createBetterAuthRuntimeWithSession(
+  session: BetterAuthSession
+): BetterAuthRuntime {
+  return {
+    enabled: true,
+    socialProviders: [{ id: "github", label: "GitHub" }],
+    accountLinkingPolicy: {
+      requireVerifiedEmail: true,
+      allowDifferentEmails: false,
+      trustedProviders: [],
+    },
+    auth: {
+      api: {
+        getSession: async () => session,
+      },
+    } as unknown as BetterAuthAuth["api"],
+  } as unknown as BetterAuthRuntime;
+}
+
+function createSession(input?: {
+  readonly userId?: string;
+  readonly email?: string;
+  readonly activeOrganizationId?: string;
+  readonly activeTeamId?: string;
+}): BetterAuthSession {
+  return {
+    user: {
+      id: input?.userId ?? "user-123",
+      email: input?.email ?? "hack@example.com",
+      emailVerified: true,
+      name: "Hack User",
+    },
+    session: {
+      id: "sess-123",
+      userId: input?.userId ?? "user-123",
+      token: "session-token",
+      activeOrganizationId: input?.activeOrganizationId ?? null,
+      activeTeamId: input?.activeTeamId ?? null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      expiresAt: new Date(Date.now() + 60_000),
+    },
+  } as unknown as BetterAuthSession;
+}
+
+describe("org and team membership broker routes", () => {
+  test("org create and list return active ownership for the creator", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const app = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    const createResponse = await app.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+    expect(createResponse.status).toBe(200);
+    const created = (await createResponse.json()) as {
+      readonly ok: boolean;
+      readonly organization?: { readonly slug?: string };
+      readonly membership?: { readonly state?: string };
+    };
+    expect(created.ok).toBe(true);
+    expect(created.organization?.slug).toBe("hack");
+    expect(created.membership?.state).toBe("active");
+
+    const listResponse = await app.handle(
+      new Request("http://localhost/v1/auth/orgs")
+    );
+    expect(listResponse.status).toBe(200);
+    const listed = (await listResponse.json()) as {
+      readonly organizations?: ReadonlyArray<{ readonly slug?: string }>;
+    };
+    expect(
+      listed.organizations?.map((organization) => organization.slug)
+    ).toEqual(["hack"]);
+  });
+
+  test("team create, invite, and remove follow the expected state transitions", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const app = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    await app.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    const createTeamResponse = await app.handle(
+      new Request("http://localhost/v1/auth/teams", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "cli",
+          org: "hack",
+          name: "CLI",
+        }),
+      })
+    );
+    expect(createTeamResponse.status).toBe(200);
+
+    const addOrgMemberResponse = await app.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "person@example.com",
+        }),
+      })
+    );
+    expect(addOrgMemberResponse.status).toBe(200);
+
+    const inviteResponse = await app.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/invite", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "person@example.com",
+        }),
+      })
+    );
+    expect(inviteResponse.status).toBe(200);
+    const invitePayload = (await inviteResponse.json()) as {
+      readonly membership?: { readonly state?: string };
+    };
+    expect(invitePayload.membership?.state).toBe("pending");
+
+    const removeResponse = await app.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/remove", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "person@example.com",
+        }),
+      })
+    );
+    expect(removeResponse.status).toBe(200);
+    const removed = (await removeResponse.json()) as {
+      readonly membership?: { readonly state?: string };
+    };
+    expect(removed.membership?.state).toBe("removed");
+  });
+
+  test("org and team admin routes reject callers who are not active org members", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const ownerApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    const outsiderApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(
+        createSession({
+          userId: "user-999",
+          email: "outsider@example.com",
+        })
+      ),
+      orgTeamsStore: store,
+    });
+
+    const createTeamResponse = await outsiderApp.handle(
+      new Request("http://localhost/v1/auth/teams", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "cli",
+          org: "hack",
+          name: "CLI",
+        }),
+      })
+    );
+    expect(createTeamResponse.status).toBe(404);
+
+    const listMembersResponse = await outsiderApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members")
+    );
+    expect(listMembersResponse.status).toBe(404);
+  });
+
+  test("team membership changes require an active parent org membership", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const ownerApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "cli",
+          org: "hack",
+          name: "CLI",
+        }),
+      })
+    );
+
+    const addResponse = await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "user-456",
+        }),
+      })
+    );
+    expect(addResponse.status).toBe(409);
+
+    const inviteResponse = await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/invite", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "person@example.com",
+        }),
+      })
+    );
+    expect(inviteResponse.status).toBe(409);
+  });
+
+  test("recipient invitation accept and decline are scoped to the signed-in email", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const session = createSession({
+      userId: "user-123",
+      email: "person@example.com",
+    });
+    const app = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(session),
+      orgTeamsStore: store,
+    });
+
+    await app.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    const inviteResponse = await app.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/invite", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "person@example.com",
+        }),
+      })
+    );
+    const invitePayload = (await inviteResponse.json()) as {
+      readonly invitation?: { readonly id?: string };
+    };
+    const inviteId = invitePayload.invitation?.id;
+    expect(typeof inviteId).toBe("string");
+    if (!inviteId) {
+      return;
+    }
+
+    const listResponse = await app.handle(
+      new Request("http://localhost/v1/auth/invitations")
+    );
+    expect(listResponse.status).toBe(200);
+    const listed = (await listResponse.json()) as {
+      readonly invitations?: ReadonlyArray<{ readonly id?: string }>;
+    };
+    expect(listed.invitations?.[0]?.id).toBe(inviteId);
+
+    const acceptResponse = await app.handle(
+      new Request(`http://localhost/v1/auth/invitations/${inviteId}/accept`, {
+        method: "POST",
+      })
+    );
+    expect(acceptResponse.status).toBe(200);
+    const accepted = (await acceptResponse.json()) as {
+      readonly membership?: { readonly state?: string };
+    };
+    expect(accepted.membership?.state).toBe("active");
+
+    const secondInviteResponse = await app.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/invite", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "person@example.com",
+        }),
+      })
+    );
+    const secondInvitePayload = (await secondInviteResponse.json()) as {
+      readonly invitation?: { readonly id?: string };
+    };
+    const secondInviteId = secondInvitePayload.invitation?.id;
+    expect(typeof secondInviteId).toBe("string");
+    if (!secondInviteId) {
+      return;
+    }
+
+    const declineResponse = await app.handle(
+      new Request(
+        `http://localhost/v1/auth/invitations/${secondInviteId}/decline`,
+        {
+          method: "POST",
+        }
+      )
+    );
+    expect(declineResponse.status).toBe(200);
+    const declined = (await declineResponse.json()) as {
+      readonly membership?: { readonly state?: string };
+    };
+    expect(declined.membership?.state).toBe("removed");
+  });
+});
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 4fc15e443..b0002ab46 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -222,7 +222,7 @@ function renderCommandHelp(
   lines.push(`${invocation} — ${command.summary}`);
   lines.push("");
   lines.push("Usage:");
-  lines.push(`  ${invocation} [options]`);
+  lines.push(`  ${renderCommandUsage(invocation, command)}`);
   lines.push("");
 
   if (command.group === "Beta") {
@@ -276,7 +276,7 @@ function renderCommandHelpMarkdown(
   lines.push("### Usage");
   lines.push("");
   lines.push("```bash");
-  lines.push(`${invocation} [options]`);
+  lines.push(renderCommandUsage(invocation, command));
   lines.push("```");
   lines.push("");
 
@@ -324,6 +324,16 @@ function renderCommandHelpMarkdown(
   return lines.join("\n");
 }
 
+function renderCommandUsage(
+  invocation: string,
+  command: AnyCommandSpec
+): string {
+  const hasSubcommands = command.subcommands.length > 0;
+  return hasSubcommands
+    ? `${invocation} <subcommand> [options]`
+    : `${invocation} [options]`;
+}
+
 function buildInvocation(
   cliName: string,
   path: readonly string[],
diff --git a/src/cli/spec.ts b/src/cli/spec.ts
index c27e579d5..48fb85dec 100644
--- a/src/cli/spec.ts
+++ b/src/cli/spec.ts
@@ -16,6 +16,7 @@ import { linearCommand } from "../commands/linear.ts";
 import { logPipeCommand } from "../commands/log-pipe.ts";
 import { mcpCommand } from "../commands/mcp.ts";
 import { nodeCommand } from "../commands/node.ts";
+import { orgCommand } from "../commands/org.ts";
 import {
   downCommand,
   initCommand,
@@ -33,6 +34,7 @@ import { secretsCommand } from "../commands/secrets.ts";
 import { sessionCommand } from "../commands/session.ts";
 import { setupCommand } from "../commands/setup.ts";
 import { sshCommand } from "../commands/ssh.ts";
+import { teamCommand } from "../commands/team.ts";
 import { theCommand } from "../commands/the.ts";
 import { ticketsCommand } from "../commands/tickets.ts";
 import { tuiCommand } from "../commands/tui.ts";
@@ -61,6 +63,8 @@ export const CLI_SPEC = defineCli({
   commands: [
     globalCommand,
     authCommand,
+    orgCommand,
+    teamCommand,
     statusCommand,
     usageCommand,
     projectsCommand,
diff --git a/src/commands/auth.ts b/src/commands/auth.ts
index 8271491c4..e2d3d50b4 100644
--- a/src/commands/auth.ts
+++ b/src/commands/auth.ts
@@ -1,6 +1,7 @@
 import type { CommandHandlerFor } from "../cli/command.ts";
 import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
 import { optJson } from "../cli/options.ts";
+import { requestHackAuthBroker } from "../lib/auth-broker-client.ts";
 import {
   deleteHackAuthSession,
   fetchHackAuthMe,
@@ -74,6 +75,55 @@ const whoamiSpec = defineCommand({
   subcommands: [] as const,
 } as const);
 
+const inviteIdPositionals = [{ name: "inviteId", required: true }] as const;
+
+const invitesSpec = defineCommand({
+  name: "invites",
+  summary: "List pending invitations for the authenticated user",
+  description:
+    "Recipient-side membership lifecycle entry point. Lists pending org and team invites so the authenticated user can accept or decline them explicitly.",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: [] as const,
+  subcommands: [] as const,
+} as const);
+
+const inviteAcceptSpec = defineCommand({
+  name: "accept",
+  summary: "Accept a pending invitation and activate membership",
+  description:
+    "Moves a pending org or team invite to active membership for the authenticated user.",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: inviteIdPositionals,
+  subcommands: [] as const,
+} as const);
+
+const inviteDeclineSpec = defineCommand({
+  name: "decline",
+  summary: "Decline a pending invitation and mark it removed",
+  description:
+    "Moves a pending org or team invite to the removed audit state for the authenticated user.",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: inviteIdPositionals,
+  subcommands: [] as const,
+} as const);
+
+const inviteSpec = defineCommand({
+  name: "invite",
+  summary: "Act on a specific invitation",
+  description:
+    "Recipient-side invitation actions. Acceptance and decline stay under auth so admins cannot implicitly activate access for someone else.",
+  group: "Global",
+  options: [] as const,
+  positionals: [] as const,
+  subcommands: [
+    withHandler(inviteAcceptSpec, handleAuthInviteAccept),
+    withHandler(inviteDeclineSpec, handleAuthInviteDecline),
+  ] as const,
+} as const);
+
 export const authCommand = defineCommand({
   name: "auth",
   summary: "Manage Hack account sign-in",
@@ -86,6 +136,8 @@ export const authCommand = defineCommand({
     withHandler(logoutSpec, handleAuthLogout),
     withHandler(statusSpec, handleAuthStatus),
     withHandler(whoamiSpec, handleAuthWhoami),
+    withHandler(invitesSpec, handleAuthInvites),
+    inviteSpec,
   ] as const,
 } as const);
 
@@ -93,6 +145,9 @@ type LoginSpec = typeof loginSpec;
 type LogoutSpec = typeof logoutSpec;
 type StatusSpec = typeof statusSpec;
 type WhoamiSpec = typeof whoamiSpec;
+type InvitesSpec = typeof invitesSpec;
+type InviteAcceptSpec = typeof inviteAcceptSpec;
+type InviteDeclineSpec = typeof inviteDeclineSpec;
 
 async function handleAuthLogin({
   args,
@@ -348,6 +403,98 @@ async function handleAuthWhoami({
   });
 }
 
+async function handleAuthInvites({
+  args,
+}: Parameters<CommandHandlerFor<InvitesSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: "/v1/auth/invitations",
+    brokerUrl: args.options.brokerUrl,
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      payload: {
+        brokerBaseUrl: response.brokerBaseUrl,
+        loginRequired: response.loginRequired,
+      },
+    });
+  }
+
+  const invitations = Array.isArray(response.value.invitations)
+    ? response.value.invitations
+    : [];
+  return writeSuccess({
+    json: args.options.json === true,
+    human:
+      invitations.length > 0
+        ? `Found ${invitations.length} pending Hack auth invitation${invitations.length === 1 ? "" : "s"}.`
+        : "No pending Hack auth invitations.",
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleAuthInviteAccept({
+  args,
+}: Parameters<CommandHandlerFor<InviteAcceptSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/invitations/${encodeURIComponent(args.positionals.inviteId)}/accept`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      payload: {
+        brokerBaseUrl: response.brokerBaseUrl,
+        loginRequired: response.loginRequired,
+      },
+    });
+  }
+
+  return writeSuccess({
+    json: args.options.json === true,
+    human: "Invitation accepted.",
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleAuthInviteDecline({
+  args,
+}: Parameters<CommandHandlerFor<InviteDeclineSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/invitations/${encodeURIComponent(args.positionals.inviteId)}/decline`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      payload: {
+        brokerBaseUrl: response.brokerBaseUrl,
+        loginRequired: response.loginRequired,
+      },
+    });
+  }
+
+  return writeSuccess({
+    json: args.options.json === true,
+    human: "Invitation declined.",
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
 function writeSuccess(input: {
   readonly json: boolean;
   readonly human: string;
diff --git a/src/commands/org.ts b/src/commands/org.ts
new file mode 100644
index 000000000..eba63e5b4
--- /dev/null
+++ b/src/commands/org.ts
@@ -0,0 +1,396 @@
+import type { CommandHandlerFor } from "../cli/command.ts";
+import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
+import { optJson } from "../cli/options.ts";
+import { requestHackAuthBroker } from "../lib/auth-broker-client.ts";
+import { logger } from "../ui/logger.ts";
+
+const optName = defineOption({
+  name: "name",
+  type: "string",
+  long: "--name",
+  valueHint: "<display-name>",
+  description: "Human-friendly name to store alongside the slug",
+} as const);
+
+const optState = defineOption({
+  name: "state",
+  type: "string",
+  long: "--state",
+  valueHint: "<pending|active|removed|all>",
+  description: "Filter membership rows by lifecycle state",
+} as const);
+
+const optTeam = defineOption({
+  name: "team",
+  type: "string",
+  long: "--team",
+  valueHint: "<team>",
+  description: "Seed one or more team-scoped invites alongside the org invite",
+} as const);
+
+const optBrokerUrl = defineOption({
+  name: "brokerUrl",
+  type: "string",
+  long: "--broker-url",
+  valueHint: "<url>",
+  description: "Override the Hack auth broker base URL",
+} as const);
+
+const orgPositionals = [{ name: "org", required: true }] as const;
+const orgSlugPositionals = [{ name: "slug", required: true }] as const;
+const orgMemberTargetPositionals = [
+  { name: "org", required: true },
+  { name: "target", required: true },
+] as const;
+
+const createSpec = defineCommand({
+  name: "create",
+  summary: "Create an organization without creating any teams implicitly",
+  description:
+    "Creates the organization record and makes the caller the initial active org admin.",
+  group: "Global",
+  options: [optName, optJson, optBrokerUrl] as const,
+  positionals: orgSlugPositionals,
+  subcommands: [] as const,
+} as const);
+
+const listSpec = defineCommand({
+  name: "list",
+  summary: "List organizations visible to the authenticated user",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: [] as const,
+  subcommands: [] as const,
+} as const);
+
+const showSpec = defineCommand({
+  name: "show",
+  summary: "Show one organization and its current membership context",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: orgPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberListSpec = defineCommand({
+  name: "list",
+  summary: "List org members and pending invites",
+  description:
+    "Defaults to actionable memberships; use --state removed or --state all for audit history.",
+  group: "Global",
+  options: [optState, optJson, optBrokerUrl] as const,
+  positionals: orgPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberInviteSpec = defineCommand({
+  name: "invite",
+  summary: "Create pending org membership for an email address",
+  description:
+    "Creates pending access only. Existing accounts still stay pending until the recipient accepts.",
+  group: "Global",
+  options: [optTeam, optJson, optBrokerUrl] as const,
+  positionals: orgMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberAddSpec = defineCommand({
+  name: "add",
+  summary: "Grant active org membership immediately to an existing user",
+  description:
+    "Requires a resolvable Hack user identity. Use invite when the target does not already exist.",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: orgMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberRemoveSpec = defineCommand({
+  name: "remove",
+  summary: "Remove org membership or cancel a pending org invite",
+  description:
+    "Admin-side revoke verb. Removing org access is expected to preview and cascade affected team memberships in the same org.",
+  group: "Global",
+  options: [optJson, optBrokerUrl] as const,
+  positionals: orgMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberSpec = defineCommand({
+  name: "member",
+  summary: "Manage org memberships and invitation lifecycle",
+  group: "Global",
+  options: [] as const,
+  positionals: [] as const,
+  subcommands: [
+    withHandler(memberListSpec, handleOrgMemberList),
+    withHandler(memberInviteSpec, handleOrgMemberInvite),
+    withHandler(memberAddSpec, handleOrgMemberAdd),
+    withHandler(memberRemoveSpec, handleOrgMemberRemove),
+  ] as const,
+} as const);
+
+export const orgCommand = defineCommand({
+  name: "org",
+  summary: "Manage organizations and org-scoped membership lifecycle",
+  description:
+    "Admin-side organization surface. Org membership is the parent grant for team access.",
+  group: "Global",
+  expandInRootHelp: true,
+  options: [] as const,
+  positionals: [] as const,
+  subcommands: [
+    withHandler(createSpec, handleOrgCreate),
+    withHandler(listSpec, handleOrgList),
+    withHandler(showSpec, handleOrgShow),
+    memberSpec,
+  ] as const,
+} as const);
+
+type CreateSpec = typeof createSpec;
+type ListSpec = typeof listSpec;
+type ShowSpec = typeof showSpec;
+type MemberListSpec = typeof memberListSpec;
+type MemberInviteSpec = typeof memberInviteSpec;
+type MemberAddSpec = typeof memberAddSpec;
+type MemberRemoveSpec = typeof memberRemoveSpec;
+
+async function handleOrgCreate({
+  args,
+}: Parameters<CommandHandlerFor<CreateSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: "/v1/auth/orgs",
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      slug: args.positionals.slug,
+      ...(args.options.name ? { name: args.options.name } : {}),
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Created organization ${args.positionals.slug}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgList({
+  args,
+}: Parameters<CommandHandlerFor<ListSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: "/v1/auth/orgs",
+    brokerUrl: args.options.brokerUrl,
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  const organizations = Array.isArray(response.value.organizations)
+    ? response.value.organizations
+    : [];
+  return writeSuccess({
+    json: args.options.json === true,
+    human:
+      organizations.length > 0
+        ? `Found ${organizations.length} organization${organizations.length === 1 ? "" : "s"}.`
+        : "No organizations found.",
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgShow({
+  args,
+}: Parameters<CommandHandlerFor<ShowSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/orgs/${encodeURIComponent(args.positionals.org)}`,
+    brokerUrl: args.options.brokerUrl,
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Loaded organization ${args.positionals.org}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgMemberList({
+  args,
+}: Parameters<CommandHandlerFor<MemberListSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/orgs/${encodeURIComponent(args.positionals.org)}/members`,
+    brokerUrl: args.options.brokerUrl,
+    query: {
+      state: args.options.state,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Loaded membership state for org ${args.positionals.org}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgMemberInvite({
+  args,
+}: Parameters<CommandHandlerFor<MemberInviteSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/orgs/${encodeURIComponent(args.positionals.org)}/members/invite`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+      ...(args.options.team ? { teams: [args.options.team] } : {}),
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Created pending org invite for ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgMemberAdd({
+  args,
+}: Parameters<CommandHandlerFor<MemberAddSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/orgs/${encodeURIComponent(args.positionals.org)}/members/add`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Granted org access to ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleOrgMemberRemove({
+  args,
+}: Parameters<CommandHandlerFor<MemberRemoveSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/orgs/${encodeURIComponent(args.positionals.org)}/members/remove`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Removed org access for ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+function writeSuccess(input: {
+  readonly json: boolean;
+  readonly human: string;
+  readonly payload: Record<string, unknown>;
+}): number {
+  if (input.json) {
+    process.stdout.write(`${JSON.stringify(input.payload, null, 2)}\n`);
+  } else {
+    logger.success({ message: input.human });
+  }
+  return 0;
+}
+
+function writeFailure(input: {
+  readonly json: boolean;
+  readonly error: string;
+  readonly brokerBaseUrl: string;
+  readonly loginRequired: boolean;
+}): number {
+  if (input.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: false,
+          error: input.error,
+          brokerBaseUrl: input.brokerBaseUrl,
+          loginRequired: input.loginRequired,
+        },
+        null,
+        2
+      )}\n`
+    );
+  } else {
+    logger.error({ message: input.error });
+  }
+  return 1;
+}
diff --git a/src/commands/team.ts b/src/commands/team.ts
new file mode 100644
index 000000000..0c8c436a1
--- /dev/null
+++ b/src/commands/team.ts
@@ -0,0 +1,404 @@
+import type { CommandHandlerFor } from "../cli/command.ts";
+import { defineCommand, defineOption, withHandler } from "../cli/command.ts";
+import { optJson } from "../cli/options.ts";
+import { requestHackAuthBroker } from "../lib/auth-broker-client.ts";
+import { logger } from "../ui/logger.ts";
+
+const optOrg = defineOption({
+  name: "org",
+  type: "string",
+  long: "--org",
+  valueHint: "<org>",
+  description: "Parent organization slug or id",
+} as const);
+
+const optName = defineOption({
+  name: "name",
+  type: "string",
+  long: "--name",
+  valueHint: "<display-name>",
+  description: "Human-friendly name to store alongside the slug",
+} as const);
+
+const optState = defineOption({
+  name: "state",
+  type: "string",
+  long: "--state",
+  valueHint: "<pending|active|removed|all>",
+  description: "Filter membership rows by lifecycle state",
+} as const);
+
+const optBrokerUrl = defineOption({
+  name: "brokerUrl",
+  type: "string",
+  long: "--broker-url",
+  valueHint: "<url>",
+  description: "Override the Hack auth broker base URL",
+} as const);
+
+const teamPositionals = [{ name: "team", required: true }] as const;
+const teamSlugPositionals = [{ name: "slug", required: true }] as const;
+const teamMemberTargetPositionals = [
+  { name: "team", required: true },
+  { name: "target", required: true },
+] as const;
+
+const createSpec = defineCommand({
+  name: "create",
+  summary: "Create a team inside an existing organization",
+  description:
+    "Requires an explicit --org value and does not add any members implicitly.",
+  group: "Global",
+  options: [optOrg, optName, optJson, optBrokerUrl] as const,
+  positionals: teamSlugPositionals,
+  subcommands: [] as const,
+} as const);
+
+const listSpec = defineCommand({
+  name: "list",
+  summary: "List teams for one organization",
+  group: "Global",
+  options: [optOrg, optJson, optBrokerUrl] as const,
+  positionals: [] as const,
+  subcommands: [] as const,
+} as const);
+
+const showSpec = defineCommand({
+  name: "show",
+  summary: "Show one team and its parent org context",
+  group: "Global",
+  options: [optOrg, optJson, optBrokerUrl] as const,
+  positionals: teamPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberListSpec = defineCommand({
+  name: "list",
+  summary: "List team members and pending invites",
+  description:
+    "Team membership depends on active org membership in the same organization.",
+  group: "Global",
+  options: [optOrg, optState, optJson, optBrokerUrl] as const,
+  positionals: teamPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberInviteSpec = defineCommand({
+  name: "invite",
+  summary: "Create pending team membership for an email address",
+  description:
+    "If the recipient is not already an org member, the final implementation must pair this with an org invite instead of granting access implicitly.",
+  group: "Global",
+  options: [optOrg, optJson, optBrokerUrl] as const,
+  positionals: teamMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberAddSpec = defineCommand({
+  name: "add",
+  summary: "Grant active team membership immediately to an existing user",
+  description:
+    "Requires both a resolvable Hack user and active org membership in the parent org.",
+  group: "Global",
+  options: [optOrg, optJson, optBrokerUrl] as const,
+  positionals: teamMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberRemoveSpec = defineCommand({
+  name: "remove",
+  summary: "Remove team membership or cancel a pending team invite",
+  description:
+    "Revokes only the team-level grant. Parent org membership stays unchanged.",
+  group: "Global",
+  options: [optOrg, optJson, optBrokerUrl] as const,
+  positionals: teamMemberTargetPositionals,
+  subcommands: [] as const,
+} as const);
+
+const memberSpec = defineCommand({
+  name: "member",
+  summary: "Manage team memberships and invitation lifecycle",
+  group: "Global",
+  options: [] as const,
+  positionals: [] as const,
+  subcommands: [
+    withHandler(memberListSpec, handleTeamMemberList),
+    withHandler(memberInviteSpec, handleTeamMemberInvite),
+    withHandler(memberAddSpec, handleTeamMemberAdd),
+    withHandler(memberRemoveSpec, handleTeamMemberRemove),
+  ] as const,
+} as const);
+
+export const teamCommand = defineCommand({
+  name: "team",
+  summary: "Manage teams and team-scoped membership lifecycle",
+  description:
+    "Admin-side team surface. Team membership is always nested under one organization.",
+  group: "Global",
+  expandInRootHelp: true,
+  options: [] as const,
+  positionals: [] as const,
+  subcommands: [
+    withHandler(createSpec, handleTeamCreate),
+    withHandler(listSpec, handleTeamList),
+    withHandler(showSpec, handleTeamShow),
+    memberSpec,
+  ] as const,
+} as const);
+
+type CreateSpec = typeof createSpec;
+type ListSpec = typeof listSpec;
+type ShowSpec = typeof showSpec;
+type MemberListSpec = typeof memberListSpec;
+type MemberInviteSpec = typeof memberInviteSpec;
+type MemberAddSpec = typeof memberAddSpec;
+type MemberRemoveSpec = typeof memberRemoveSpec;
+
+async function handleTeamCreate({
+  args,
+}: Parameters<CommandHandlerFor<CreateSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: "/v1/auth/teams",
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      slug: args.positionals.slug,
+      org: args.options.org,
+      ...(args.options.name ? { name: args.options.name } : {}),
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Created team ${args.positionals.slug}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamList({
+  args,
+}: Parameters<CommandHandlerFor<ListSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: "/v1/auth/teams",
+    brokerUrl: args.options.brokerUrl,
+    query: {
+      org: args.options.org,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  const teams = Array.isArray(response.value.teams) ? response.value.teams : [];
+  return writeSuccess({
+    json: args.options.json === true,
+    human:
+      teams.length > 0
+        ? `Found ${teams.length} team${teams.length === 1 ? "" : "s"}.`
+        : "No teams found.",
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamShow({
+  args,
+}: Parameters<CommandHandlerFor<ShowSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/teams/${encodeURIComponent(args.positionals.team)}`,
+    brokerUrl: args.options.brokerUrl,
+    query: {
+      org: args.options.org,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Loaded team ${args.positionals.team}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamMemberList({
+  args,
+}: Parameters<CommandHandlerFor<MemberListSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/teams/${encodeURIComponent(args.positionals.team)}/members`,
+    brokerUrl: args.options.brokerUrl,
+    query: {
+      org: args.options.org,
+      state: args.options.state,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Loaded membership state for team ${args.positionals.team}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamMemberInvite({
+  args,
+}: Parameters<CommandHandlerFor<MemberInviteSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/teams/${encodeURIComponent(args.positionals.team)}/members/invite`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+      org: args.options.org,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Created pending team invite for ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamMemberAdd({
+  args,
+}: Parameters<CommandHandlerFor<MemberAddSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/teams/${encodeURIComponent(args.positionals.team)}/members/add`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+      org: args.options.org,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Granted team access to ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+async function handleTeamMemberRemove({
+  args,
+}: Parameters<CommandHandlerFor<MemberRemoveSpec>>[0]): Promise<number> {
+  const response = await requestHackAuthBroker({
+    path: `/v1/auth/teams/${encodeURIComponent(args.positionals.team)}/members/remove`,
+    method: "POST",
+    brokerUrl: args.options.brokerUrl,
+    body: {
+      target: args.positionals.target,
+      org: args.options.org,
+    },
+  });
+  if (!response.ok) {
+    return writeFailure({
+      json: args.options.json === true,
+      error: response.error,
+      brokerBaseUrl: response.brokerBaseUrl,
+      loginRequired: response.loginRequired,
+    });
+  }
+  return writeSuccess({
+    json: args.options.json === true,
+    human: `Removed team access for ${args.positionals.target}.`,
+    payload: {
+      ...response.value,
+      brokerBaseUrl: response.brokerBaseUrl,
+    },
+  });
+}
+
+function writeSuccess(input: {
+  readonly json: boolean;
+  readonly human: string;
+  readonly payload: Record<string, unknown>;
+}): number {
+  if (input.json) {
+    process.stdout.write(`${JSON.stringify(input.payload, null, 2)}\n`);
+  } else {
+    logger.success({ message: input.human });
+  }
+  return 0;
+}
+
+function writeFailure(input: {
+  readonly json: boolean;
+  readonly error: string;
+  readonly brokerBaseUrl: string;
+  readonly loginRequired: boolean;
+}): number {
+  if (input.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: false,
+          error: input.error,
+          brokerBaseUrl: input.brokerBaseUrl,
+          loginRequired: input.loginRequired,
+        },
+        null,
+        2
+      )}\n`
+    );
+  } else {
+    logger.error({ message: input.error });
+  }
+  return 1;
+}
diff --git a/src/lib/auth-broker-client.ts b/src/lib/auth-broker-client.ts
new file mode 100644
index 000000000..d19f8f2d7
--- /dev/null
+++ b/src/lib/auth-broker-client.ts
@@ -0,0 +1,123 @@
+import {
+  type FetchLike,
+  loadHackAuthSession,
+  resolveHackAuthBrokerBaseUrl,
+} from "./auth-session.ts";
+
+type BrokerResult<T> =
+  | {
+      readonly ok: true;
+      readonly value: T;
+      readonly brokerBaseUrl: string;
+    }
+  | {
+      readonly ok: false;
+      readonly error: string;
+      readonly brokerBaseUrl: string;
+      readonly loginRequired: boolean;
+    };
+
+export async function requestHackAuthBroker(input: {
+  readonly path: string;
+  readonly method?: "GET" | "POST";
+  readonly query?: Record<string, string | undefined>;
+  readonly body?: Record<string, unknown>;
+  readonly brokerUrl?: string;
+  readonly fetchImpl?: FetchLike;
+}): Promise<BrokerResult<Record<string, unknown>>> {
+  const brokerBaseUrl = resolveHackAuthBrokerBaseUrl({
+    override: input.brokerUrl,
+  });
+  const stored = await loadHackAuthSession().catch(() => null);
+  const token = stored?.token?.trim() ?? "";
+  if (!token) {
+    return {
+      ok: false,
+      error:
+        "Hack auth login is required for broker-managed org and team commands. Run `hack auth login` and retry.",
+      brokerBaseUrl,
+      loginRequired: true,
+    };
+  }
+
+  const url = new URL(input.path, `${brokerBaseUrl}/`);
+  for (const [key, value] of Object.entries(input.query ?? {})) {
+    if (typeof value === "string" && value.trim()) {
+      url.searchParams.set(key, value.trim());
+    }
+  }
+
+  const fetchImpl: FetchLike =
+    input.fetchImpl ?? ((resource, init) => fetch(resource, init));
+
+  let response: Response;
+  try {
+    response = await fetchImpl(url.toString(), {
+      method: input.method ?? "GET",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${token}`,
+        ...(input.body ? { "content-type": "application/json" } : {}),
+      },
+      ...(input.body ? { body: JSON.stringify(input.body) } : {}),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Unable to reach Hack auth broker route ${input.path}: ${toErrorMessage(error)}`,
+      brokerBaseUrl,
+      loginRequired: false,
+    };
+  }
+
+  const body = await readJsonBody({ response });
+  if (!response.ok) {
+    const remoteError = readOptionalString(
+      (body as Record<string, unknown>).error
+    );
+    return {
+      ok: false,
+      error: remoteError
+        ? `Hack auth broker rejected ${input.path} (HTTP ${response.status}): ${remoteError}`
+        : `Hack auth broker rejected ${input.path} (HTTP ${response.status}).`,
+      brokerBaseUrl,
+      loginRequired: response.status === 401,
+    };
+  }
+
+  return {
+    ok: true,
+    value: isRecord(body) ? body : { ok: true },
+    brokerBaseUrl,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+async function readJsonBody(input: {
+  readonly response: Response;
+}): Promise<unknown> {
+  const text = await input.response.text();
+  if (!text.trim()) {
+    return {};
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+function readOptionalString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "Unknown error";
+}
diff --git a/tests/auth-command.test.ts b/tests/auth-command.test.ts
index fb116e028..8f1ee3888 100644
--- a/tests/auth-command.test.ts
+++ b/tests/auth-command.test.ts
@@ -512,6 +512,134 @@ test("auth status json includes a next step when login is required", async () =>
   expect(payload.nextStep).toContain("hack auth login");
 });
 
+test("auth invites lists pending invitations via the broker", async () => {
+  await writeStoredTokenEnvelope({
+    token: "hack-session-token",
+    expiresAt: "2099-03-06T19:00:00.000Z",
+  });
+
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/invitations") {
+      return Response.json({
+        ok: true,
+        invitations: [
+          {
+            id: "invite_123",
+            scope: "organization",
+            state: "pending",
+          },
+        ],
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["auth", "invites", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/invitations"
+  );
+  expect(fetchCalls[0]?.init?.method).toBe("GET");
+  expect(fetchCalls[0]?.init?.headers).toMatchObject({
+    authorization: "Bearer hack-session-token",
+  });
+  const payload = JSON.parse(result.stdout) as {
+    readonly invitations?: ReadonlyArray<{ readonly id?: string }>;
+  };
+  expect(payload.invitations?.[0]?.id).toBe("invite_123");
+});
+
+test("auth invite accept posts an activation request to the broker", async () => {
+  await writeStoredTokenEnvelope({
+    token: "hack-session-token",
+    expiresAt: "2099-03-06T19:00:00.000Z",
+  });
+
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (
+      url === "https://auth.hack.broker/v1/auth/invitations/invite_123/accept"
+    ) {
+      return Response.json({
+        ok: true,
+        membership: {
+          state: "active",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["auth", "invite", "accept", "invite_123", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/invitations/invite_123/accept"
+  );
+  expect(fetchCalls[0]?.init?.method).toBe("POST");
+  const payload = JSON.parse(result.stdout) as {
+    readonly membership?: { readonly state?: string };
+  };
+  expect(payload.membership?.state).toBe("active");
+});
+
+test("auth invite decline posts a removal request to the broker", async () => {
+  await writeStoredTokenEnvelope({
+    token: "hack-session-token",
+    expiresAt: "2099-03-06T19:00:00.000Z",
+  });
+
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (
+      url === "https://auth.hack.broker/v1/auth/invitations/invite_123/decline"
+    ) {
+      return Response.json({
+        ok: true,
+        membership: {
+          state: "removed",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["auth", "invite", "decline", "invite_123", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/invitations/invite_123/decline"
+  );
+  expect(fetchCalls[0]?.init?.method).toBe("POST");
+  const payload = JSON.parse(result.stdout) as {
+    readonly membership?: { readonly state?: string };
+  };
+  expect(payload.membership?.state).toBe("removed");
+});
+
 type CapturedRunResult = {
   readonly exitCode: number;
   readonly stdout: string;
diff --git a/tests/cli-command.test.ts b/tests/cli-command.test.ts
index add22e532..1fee6d2c3 100644
--- a/tests/cli-command.test.ts
+++ b/tests/cli-command.test.ts
@@ -1,4 +1,4 @@
-import { expect, test } from "bun:test";
+import { afterEach, beforeEach, expect, test } from "bun:test";
 import {
   collectAllowedOptionNames,
   parseOptionsForCommand,
@@ -7,6 +7,35 @@ import {
 } from "../src/cli/command.ts";
 import { CLI_SPEC } from "../src/cli/spec.ts";
 
+type CapturedRunResult = {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+let originalSetupSyncMode: string | undefined;
+let originalLogger: string | undefined;
+
+beforeEach(() => {
+  originalSetupSyncMode = process.env.HACK_SETUP_SYNC_MODE;
+  originalLogger = process.env.HACK_LOGGER;
+  process.env.HACK_SETUP_SYNC_MODE = "off";
+  process.env.HACK_LOGGER = "console";
+});
+
+afterEach(() => {
+  if (originalSetupSyncMode !== undefined) {
+    process.env.HACK_SETUP_SYNC_MODE = originalSetupSyncMode;
+  } else {
+    process.env.HACK_SETUP_SYNC_MODE = undefined;
+  }
+  if (originalLogger !== undefined) {
+    process.env.HACK_LOGGER = originalLogger;
+  } else {
+    process.env.HACK_LOGGER = undefined;
+  }
+});
+
 test("resolveCommand finds nested subcommand and remaining positionals", () => {
   const resolved = resolveCommand(CLI_SPEC, ["global", "logs", "caddy"]);
   expect(resolved.command?.name).toBe("logs");
@@ -87,3 +116,72 @@ test("resolveCommand finds nested project owner show command", () => {
   ]);
   expect(resolved.remainingPositionals).toEqual([]);
 });
+
+test("resolveCommand exposes org, team, and auth invite command paths", () => {
+  const orgResolved = resolveCommand(CLI_SPEC, ["org", "member", "invite"]);
+  expect(orgResolved.command?.name).toBe("invite");
+  expect(orgResolved.path.map((command) => command.name)).toEqual([
+    "org",
+    "member",
+    "invite",
+  ]);
+
+  const teamResolved = resolveCommand(CLI_SPEC, ["team", "member", "remove"]);
+  expect(teamResolved.command?.name).toBe("remove");
+  expect(teamResolved.path.map((command) => command.name)).toEqual([
+    "team",
+    "member",
+    "remove",
+  ]);
+
+  const authInviteResolved = resolveCommand(CLI_SPEC, [
+    "auth",
+    "invite",
+    "accept",
+  ]);
+  expect(authInviteResolved.command?.name).toBe("accept");
+  expect(authInviteResolved.path.map((command) => command.name)).toEqual([
+    "auth",
+    "invite",
+    "accept",
+  ]);
+});
+
+test("help shows subcommand usage for namespace commands", async () => {
+  const result = await runCliWithCapturedOutput(["help", "org"]);
+
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("Usage:");
+  expect(result.stdout).toContain("hack org <subcommand> [options]");
+  expect(result.stdout).toContain("hack org member");
+});
+
+async function runCliWithCapturedOutput(
+  args: readonly string[]
+): Promise<CapturedRunResult> {
+  let stdout = "";
+  let stderr = "";
+  const originalStdoutWrite = process.stdout.write;
+  const originalStderrWrite = process.stderr.write;
+
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdout +=
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    return true;
+  }) as typeof process.stdout.write;
+
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderr +=
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    return true;
+  }) as typeof process.stderr.write;
+
+  try {
+    const { runCli } = await import("../src/cli/run.ts");
+    const exitCode = await runCli(args);
+    return { exitCode, stdout, stderr };
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+}
diff --git a/tests/org-team-command.test.ts b/tests/org-team-command.test.ts
new file mode 100644
index 000000000..3ed0c58e0
--- /dev/null
+++ b/tests/org-team-command.test.ts
@@ -0,0 +1,375 @@
+import { afterAll, afterEach, beforeEach, expect, mock, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+type FetchCall = {
+  readonly url: string;
+  readonly init: RequestInit | undefined;
+};
+
+type CapturedRunResult = {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit
+) => Promise<Response>;
+
+let fetchCalls: FetchCall[] = [];
+let fetchImpl: FetchLike = async () =>
+  new Response("not mocked", {
+    status: 500,
+    headers: { "content-type": "text/plain" },
+  });
+
+const originalFetch = globalThis.fetch;
+const originalLogger = process.env.HACK_LOGGER;
+const originalGlobalConfigPath = process.env.HACK_GLOBAL_CONFIG_PATH;
+const originalSecretsKey = process.env.HACK_SECRETS_FILE_KEY;
+const originalHome = process.env.HOME;
+
+const { runCli } = await import("../src/cli/run.ts");
+const { saveHackAuthSession } = await import("../src/lib/auth-session.ts");
+
+let tempDir: string | null = null;
+let tempGlobalConfigPath: string | null = null;
+
+mock.module("../src/lib/os.ts", () => ({
+  isMac: () => process.platform === "darwin",
+  openUrl: async () => 0,
+}));
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-org-team-command-"));
+  tempGlobalConfigPath = resolve(tempDir, "hack.config.json");
+  process.env.HOME = tempDir;
+  process.env.HACK_GLOBAL_CONFIG_PATH = tempGlobalConfigPath;
+  process.env.HACK_SECRETS_FILE_KEY = "test-org-team-command-key";
+  process.env.HACK_LOGGER = "console";
+  process.env.HACK_AUTH_BROKER_URL = undefined;
+  process.env.HACK_SETUP_SYNC_MODE = "off";
+
+  await writeFile(
+    tempGlobalConfigPath,
+    `${JSON.stringify(
+      {
+        controlPlane: {
+          secrets: {
+            backend: "encrypted_file",
+            encryptedFile: {
+              path: resolve(tempDir, "secrets.enc.json"),
+            },
+          },
+        },
+      },
+      null,
+      2
+    )}\n`
+  );
+
+  await saveHackAuthSession({
+    session: {
+      token: "hack-session-token",
+      expiresAt: "2099-03-06T19:00:00.000Z",
+    },
+  });
+
+  fetchCalls = [];
+  fetchImpl = async () =>
+    new Response("not mocked", {
+      status: 500,
+      headers: { "content-type": "text/plain" },
+    });
+  globalThis.fetch = (async (
+    input: string | URL | Request,
+    init?: RequestInit
+  ) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    fetchCalls.push({ url, init });
+    return await fetchImpl(input, init);
+  }) as typeof globalThis.fetch;
+});
+
+afterEach(async () => {
+  globalThis.fetch = originalFetch;
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+  tempDir = null;
+  tempGlobalConfigPath = null;
+
+  if (originalLogger === undefined) {
+    process.env.HACK_LOGGER = undefined;
+  } else {
+    process.env.HACK_LOGGER = originalLogger;
+  }
+  if (originalGlobalConfigPath === undefined) {
+    process.env.HACK_GLOBAL_CONFIG_PATH = undefined;
+  } else {
+    process.env.HACK_GLOBAL_CONFIG_PATH = originalGlobalConfigPath;
+  }
+  if (originalSecretsKey === undefined) {
+    process.env.HACK_SECRETS_FILE_KEY = undefined;
+  } else {
+    process.env.HACK_SECRETS_FILE_KEY = originalSecretsKey;
+  }
+  if (originalHome === undefined) {
+    process.env.HOME = undefined;
+  } else {
+    process.env.HOME = originalHome;
+  }
+});
+
+afterAll(() => {
+  mock.restore();
+  globalThis.fetch = originalFetch;
+});
+
+test("org create posts slug and display name to the broker", async () => {
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/orgs") {
+      return Response.json({
+        ok: true,
+        organization: {
+          id: "org_123",
+          slug: "hack",
+          name: "Hack",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["org", "create", "hack", "--name", "Hack", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls).toHaveLength(1);
+  expect(fetchCalls[0]?.url).toBe("https://auth.hack.broker/v1/auth/orgs");
+  expect(fetchCalls[0]?.init?.method).toBe("POST");
+  expect(fetchCalls[0]?.init?.headers).toMatchObject({
+    authorization: "Bearer hack-session-token",
+  });
+  expect(JSON.parse(String(fetchCalls[0]?.init?.body))).toEqual({
+    slug: "hack",
+    name: "Hack",
+  });
+  const payload = JSON.parse(result.stdout) as {
+    readonly ok: boolean;
+    readonly organization?: { readonly slug?: string };
+  };
+  expect(payload.ok).toBe(true);
+  expect(payload.organization?.slug).toBe("hack");
+});
+
+test("org member invite posts pending membership request to the broker", async () => {
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/orgs/hack/members/invite") {
+      return Response.json({
+        ok: true,
+        membership: {
+          scope: "organization",
+          state: "pending",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["org", "member", "invite", "hack", "person@example.com", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/orgs/hack/members/invite"
+  );
+  expect(JSON.parse(String(fetchCalls[0]?.init?.body))).toEqual({
+    target: "person@example.com",
+  });
+  const payload = JSON.parse(result.stdout) as {
+    readonly membership?: { readonly state?: string };
+  };
+  expect(payload.membership?.state).toBe("pending");
+});
+
+test("org member invite includes seeded team targets in the broker request", async () => {
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/orgs/hack/members/invite") {
+      return Response.json({
+        ok: true,
+        membership: {
+          scope: "organization",
+          state: "pending",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: [
+      "org",
+      "member",
+      "invite",
+      "hack",
+      "person@example.com",
+      "--team",
+      "cli",
+      "--json",
+    ],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/orgs/hack/members/invite"
+  );
+  expect(JSON.parse(String(fetchCalls[0]?.init?.body))).toEqual({
+    target: "person@example.com",
+    teams: ["cli"],
+  });
+});
+
+test("team create posts to the broker with explicit org scope", async () => {
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/teams") {
+      return Response.json({
+        ok: true,
+        team: {
+          id: "team_123",
+          slug: "cli",
+          name: "CLI",
+          organizationId: "org_123",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: ["team", "create", "cli", "--org", "hack", "--name", "CLI", "--json"],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe("https://auth.hack.broker/v1/auth/teams");
+  expect(JSON.parse(String(fetchCalls[0]?.init?.body))).toEqual({
+    slug: "cli",
+    org: "hack",
+    name: "CLI",
+  });
+  const payload = JSON.parse(result.stdout) as {
+    readonly team?: { readonly slug?: string };
+  };
+  expect(payload.team?.slug).toBe("cli");
+});
+
+test("team member remove posts the revoke action to the broker", async () => {
+  fetchImpl = async (input) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    if (url === "https://auth.hack.broker/v1/auth/teams/cli/members/remove") {
+      return Response.json({
+        ok: true,
+        membership: {
+          scope: "team",
+          state: "removed",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch URL: ${url}`);
+  };
+
+  const result = await runCliWithCapturedIo({
+    argv: [
+      "team",
+      "member",
+      "remove",
+      "cli",
+      "user_123",
+      "--org",
+      "hack",
+      "--json",
+    ],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(fetchCalls[0]?.url).toBe(
+    "https://auth.hack.broker/v1/auth/teams/cli/members/remove"
+  );
+  expect(JSON.parse(String(fetchCalls[0]?.init?.body))).toEqual({
+    target: "user_123",
+    org: "hack",
+  });
+});
+
+async function runCliWithCapturedIo(input: {
+  readonly argv: readonly string[];
+}): Promise<CapturedRunResult> {
+  const stdoutChunks: string[] = [];
+  const stderrChunks: string[] = [];
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdoutChunks.push(
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8")
+    );
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderrChunks.push(
+      typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8")
+    );
+    return true;
+  }) as typeof process.stderr.write;
+
+  try {
+    const exitCode = await runCli([...input.argv]);
+    return {
+      exitCode,
+      stdout: stdoutChunks.join(""),
+      stderr: stderrChunks.join(""),
+    };
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+}

From 64dd8b2a9636347c06553a436d5772bea835f7ab Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 16:50:05 +0000
Subject: [PATCH 127/134] fix(auth): widen org plugin session status typing

---
 services/auth-broker/src/modules/orgs/plugin.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/services/auth-broker/src/modules/orgs/plugin.ts b/services/auth-broker/src/modules/orgs/plugin.ts
index 35e16af87..e44a67ffb 100644
--- a/services/auth-broker/src/modules/orgs/plugin.ts
+++ b/services/auth-broker/src/modules/orgs/plugin.ts
@@ -579,7 +579,7 @@ export function createOrgsPlugin(input: {
 async function requireSession(input: {
   readonly runtime: BetterAuthRuntime;
   readonly request: Request;
-  readonly set: { status?: number };
+  readonly set: { status?: number | string };
 }) {
   const session = await resolveBetterAuthSession({
     runtime: input.runtime,

From 2a16e271fc451a98ece73fcaf620cbbd820ead4c Mon Sep 17 00:00:00 2001
From: Dimitri Kennedy <dimitrikennedy@gmail.com>
Date: Sat, 14 Mar 2026 17:24:54 +0000
Subject: [PATCH 128/134] HACK-468: checkpoint merge prep

---
 docs/cli.md                                   |  2 +-
 .../auth-broker/src/modules/orgs/plugin.ts    |  4 +-
 .../auth-broker/src/modules/orgs/service.ts   | 80 ++++++++++++++++++-
 src/commands/org.ts                           |  2 +-
 4 files changed, 82 insertions(+), 6 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 1bf046f49..62d894fcb 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -351,7 +351,7 @@ Lifecycle semantics:
 - `invite` creates `pending`
 - `add` creates `active`
 - `remove` transitions `pending` or `active` membership to `removed`
-- Removing org access is expected to preview and cascade affected team memberships in the same org
+- Removing org access also transitions matching team memberships and team invites in that organization to `removed`
 
 #### hack org member list
 
diff --git a/services/auth-broker/src/modules/orgs/plugin.ts b/services/auth-broker/src/modules/orgs/plugin.ts
index e44a67ffb..06a6ad69c 100644
--- a/services/auth-broker/src/modules/orgs/plugin.ts
+++ b/services/auth-broker/src/modules/orgs/plugin.ts
@@ -602,7 +602,7 @@ function normalizeOptionalString(value: unknown): string | null {
 
 function normalizeState(input: {
   readonly value: string | undefined;
-}): MembershipState | "all" {
+}): MembershipState | "all" | "actionable" {
   const normalized = normalizeOptionalString(input.value);
   if (
     normalized === "pending" ||
@@ -612,7 +612,7 @@ function normalizeState(input: {
   ) {
     return normalized;
   }
-  return "all";
+  return "actionable";
 }
 
 async function hasActiveParentOrgMembership(input: {
diff --git a/services/auth-broker/src/modules/orgs/service.ts b/services/auth-broker/src/modules/orgs/service.ts
index 5993cd250..20f0522a2 100644
--- a/services/auth-broker/src/modules/orgs/service.ts
+++ b/services/auth-broker/src/modules/orgs/service.ts
@@ -86,7 +86,7 @@ export type OrgTeamsStore = {
     readonly scope: "organization" | "team";
     readonly orgKey: string;
     readonly teamKey?: string | null;
-    readonly state: MembershipState | "all";
+    readonly state: MembershipState | "all" | "actionable";
   }) => MaybePromise<readonly MembershipRecord[]>;
   readonly inviteMember: (input: {
     readonly scope: "organization" | "team";
@@ -279,7 +279,7 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
     readonly scope: "organization" | "team";
     readonly orgKey: string;
     readonly teamKey?: string | null;
-    readonly state: MembershipState | "all";
+    readonly state: MembershipState | "all" | "actionable";
   }): MaybePromise<readonly MembershipRecord[]> {
     const organization = this.findOrganization({ orgKey: input.orgKey });
     if (!organization) {
@@ -319,6 +319,9 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
     if (input.state === "removed") {
       return removed;
     }
+    if (input.state === "actionable") {
+      return [...pending, ...active];
+    }
     return [...pending, ...active, ...removed];
   }
 
@@ -430,6 +433,12 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
           target: invitation.email,
         });
         this.removedMemberships.set(membership.id, membership);
+        if (input.scope === "organization") {
+          this.cascadeRemovedOrganizationTarget({
+            organizationId: organization.id,
+            target: normalizedTarget,
+          });
+        }
         return membership;
       }
     }
@@ -451,6 +460,12 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
           target: membership.target,
         });
         this.removedMemberships.set(removed.id, removed);
+        if (input.scope === "organization") {
+          this.cascadeRemovedOrganizationTarget({
+            organizationId: organization.id,
+            target: normalizedTarget,
+          });
+        }
         return removed;
       }
     }
@@ -620,4 +635,65 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
       updatedAt: now,
     };
   }
+
+  private cascadeRemovedOrganizationTarget(input: {
+    readonly organizationId: string;
+    readonly target: string;
+  }): void {
+    const normalizedTarget = input.target.trim();
+
+    for (const invitation of this.invitations.values()) {
+      if (
+        invitation.status !== "pending" ||
+        invitation.scope !== "team" ||
+        invitation.organizationId !== input.organizationId ||
+        invitation.email !== normalizedTarget
+      ) {
+        continue;
+      }
+
+      this.invitations.set(invitation.id, {
+        ...invitation,
+        status: "removed",
+        updatedAt: new Date().toISOString(),
+      });
+      const removed = this.toRemovedMembership({
+        scope: invitation.scope,
+        organizationId: invitation.organizationId,
+        teamId: invitation.teamId,
+        userId: null,
+        email: invitation.email,
+        target: invitation.email,
+      });
+      this.removedMemberships.set(removed.id, removed);
+    }
+
+    for (const [key, membership] of this.activeMemberships.entries()) {
+      if (
+        membership.scope !== "team" ||
+        membership.organizationId !== input.organizationId
+      ) {
+        continue;
+      }
+
+      const membershipEmail = membership.email?.trim() ?? "";
+      if (
+        membership.target !== normalizedTarget &&
+        membershipEmail !== normalizedTarget
+      ) {
+        continue;
+      }
+
+      this.activeMemberships.delete(key);
+      const removed = this.toRemovedMembership({
+        scope: membership.scope,
+        organizationId: membership.organizationId,
+        teamId: membership.teamId,
+        userId: membership.userId,
+        email: membership.email,
+        target: membership.target,
+      });
+      this.removedMemberships.set(removed.id, removed);
+    }
+  }
 }
diff --git a/src/commands/org.ts b/src/commands/org.ts
index eba63e5b4..41eb6acfe 100644
--- a/src/commands/org.ts
+++ b/src/commands/org.ts
@@ -109,7 +109,7 @@ const memberRemoveSpec = defineCommand({
   name: "remove",
   summary: "Remove org membership or cancel a pending org invite",
   description:
-    "Admin-side revoke verb. Removing org access is expected to preview and cascade affected team memberships in the same org.",
+    "Admin-side revoke verb. Removing org access also removes matching team memberships and invites in that organization.",
   group: "Global",
   options: [optJson, optBrokerUrl] as const,
   positionals: orgMemberTargetPositionals,

From c25ae2dcaa1796fdd476f488c4ff95c8748297ac Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sat, 14 Mar 2026 21:49:07 +0000
Subject: [PATCH 129/134] fix(auth): allow org admins to administer teams

---
 .../auth-broker/src/modules/orgs/service.ts   | 159 +++++++++++-------
 .../tests/org-team-membership.test.ts         |  92 ++++++++++
 2 files changed, 186 insertions(+), 65 deletions(-)

diff --git a/services/auth-broker/src/modules/orgs/service.ts b/services/auth-broker/src/modules/orgs/service.ts
index 20f0522a2..88f4bd4fa 100644
--- a/services/auth-broker/src/modules/orgs/service.ts
+++ b/services/auth-broker/src/modules/orgs/service.ts
@@ -233,15 +233,14 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
     readonly orgKey: string | null;
     readonly actorUserId: string;
   }): MaybePromise<readonly TeamRecord[]> {
-    const allowedTeamIds = new Set(
+    const allowedOrgIds = new Set(
       [...this.activeMemberships.values()]
         .filter(
           (membership) =>
-            membership.scope === "team" &&
+            membership.scope === "organization" &&
             membership.userId === input.actorUserId
         )
-        .map((membership) => membership.teamId)
-        .filter((teamId): teamId is string => typeof teamId === "string")
+        .map((membership) => membership.organizationId)
     );
     const organization = input.orgKey
       ? this.findOrganization({ orgKey: input.orgKey })
@@ -250,7 +249,7 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
       if (organization && team.organizationId !== organization.id) {
         return false;
       }
-      return allowedTeamIds.has(team.id);
+      return allowedOrgIds.has(team.organizationId);
     });
   }
 
@@ -268,8 +267,8 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
     }
     const allowed = [...this.activeMemberships.values()].some(
       (membership) =>
-        membership.scope === "team" &&
-        membership.teamId === team.id &&
+        membership.scope === "organization" &&
+        membership.organizationId === team.organizationId &&
         membership.userId === input.actorUserId
     );
     return allowed ? team : null;
@@ -410,66 +409,30 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
       return null;
     }
     const normalizedTarget = input.target.trim();
-    for (const invitation of this.invitations.values()) {
-      if (
-        invitation.status === "pending" &&
-        invitation.scope === input.scope &&
-        invitation.organizationId === organization.id &&
-        invitation.teamId === (team?.id ?? null) &&
-        invitation.email === normalizedTarget
-      ) {
-        const removed: InvitationRecord = {
-          ...invitation,
-          status: "removed",
-          updatedAt: new Date().toISOString(),
-        };
-        this.invitations.set(invitation.id, removed);
-        const membership = this.toRemovedMembership({
-          scope: invitation.scope,
-          organizationId: invitation.organizationId,
-          teamId: invitation.teamId,
-          userId: null,
-          email: invitation.email,
-          target: invitation.email,
-        });
-        this.removedMemberships.set(membership.id, membership);
-        if (input.scope === "organization") {
-          this.cascadeRemovedOrganizationTarget({
-            organizationId: organization.id,
-            target: normalizedTarget,
-          });
-        }
-        return membership;
-      }
+    const teamId = team?.id ?? null;
+    const removedMembership =
+      this.removePendingInvitationMembership({
+        scope: input.scope,
+        organizationId: organization.id,
+        teamId,
+        target: normalizedTarget,
+      }) ??
+      this.removeActiveMembership({
+        scope: input.scope,
+        organizationId: organization.id,
+        teamId,
+        target: normalizedTarget,
+      });
+    if (!removedMembership) {
+      return null;
     }
-
-    for (const [key, membership] of this.activeMemberships.entries()) {
-      if (
-        membership.scope === input.scope &&
-        membership.organizationId === organization.id &&
-        membership.teamId === (team?.id ?? null) &&
-        membership.target === normalizedTarget
-      ) {
-        this.activeMemberships.delete(key);
-        const removed = this.toRemovedMembership({
-          scope: membership.scope,
-          organizationId: membership.organizationId,
-          teamId: membership.teamId,
-          userId: membership.userId,
-          email: membership.email,
-          target: membership.target,
-        });
-        this.removedMemberships.set(removed.id, removed);
-        if (input.scope === "organization") {
-          this.cascadeRemovedOrganizationTarget({
-            organizationId: organization.id,
-            target: normalizedTarget,
-          });
-        }
-        return removed;
-      }
+    if (input.scope === "organization") {
+      this.cascadeRemovedOrganizationTarget({
+        organizationId: organization.id,
+        target: normalizedTarget,
+      });
     }
-    return null;
+    return removedMembership;
   }
 
   listInvitationsForEmail(input: {
@@ -636,6 +599,72 @@ export class InMemoryOrgTeamsStore implements OrgTeamsStore {
     };
   }
 
+  private removePendingInvitationMembership(input: {
+    readonly scope: "organization" | "team";
+    readonly organizationId: string;
+    readonly teamId: string | null;
+    readonly target: string;
+  }): MembershipRecord | null {
+    for (const invitation of this.invitations.values()) {
+      if (
+        invitation.status !== "pending" ||
+        invitation.scope !== input.scope ||
+        invitation.organizationId !== input.organizationId ||
+        invitation.teamId !== input.teamId ||
+        invitation.email !== input.target
+      ) {
+        continue;
+      }
+      const removed: InvitationRecord = {
+        ...invitation,
+        status: "removed",
+        updatedAt: new Date().toISOString(),
+      };
+      this.invitations.set(invitation.id, removed);
+      const membership = this.toRemovedMembership({
+        scope: invitation.scope,
+        organizationId: invitation.organizationId,
+        teamId: invitation.teamId,
+        userId: null,
+        email: invitation.email,
+        target: invitation.email,
+      });
+      this.removedMemberships.set(membership.id, membership);
+      return membership;
+    }
+    return null;
+  }
+
+  private removeActiveMembership(input: {
+    readonly scope: "organization" | "team";
+    readonly organizationId: string;
+    readonly teamId: string | null;
+    readonly target: string;
+  }): MembershipRecord | null {
+    for (const [key, membership] of this.activeMemberships.entries()) {
+      if (
+        membership.scope !== input.scope ||
+        membership.organizationId !== input.organizationId ||
+        membership.teamId !== input.teamId ||
+        membership.target !== input.target
+      ) {
+        continue;
+      }
+      this.activeMemberships.delete(key);
+      const removed = this.toRemovedMembership({
+        scope: membership.scope,
+        organizationId: membership.organizationId,
+        teamId: membership.teamId,
+        userId: membership.userId,
+        email: membership.email,
+        target: membership.target,
+      });
+      this.removedMemberships.set(removed.id, removed);
+      return removed;
+    }
+    return null;
+  }
+
   private cascadeRemovedOrganizationTarget(input: {
     readonly organizationId: string;
     readonly target: string;
diff --git a/services/auth-broker/tests/org-team-membership.test.ts b/services/auth-broker/tests/org-team-membership.test.ts
index 3a57f86b0..96943972e 100644
--- a/services/auth-broker/tests/org-team-membership.test.ts
+++ b/services/auth-broker/tests/org-team-membership.test.ts
@@ -249,6 +249,98 @@ describe("org and team membership broker routes", () => {
     expect(listMembersResponse.status).toBe(404);
   });
 
+  test("active org members can administer teams without direct team membership", async () => {
+    const store = new InMemoryOrgTeamsStore();
+    const ownerApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(createSession()),
+      orgTeamsStore: store,
+    });
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "hack",
+          name: "Hack",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/teams", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          slug: "cli",
+          org: "hack",
+          name: "CLI",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "user-456",
+        }),
+      })
+    );
+
+    await ownerApp.handle(
+      new Request("http://localhost/v1/auth/orgs/hack/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          target: "user-789",
+        }),
+      })
+    );
+
+    const orgAdminApp = createAuthBrokerApp({
+      config: createTestConfig(),
+      betterAuthRuntime: createBetterAuthRuntimeWithSession(
+        createSession({
+          userId: "user-456",
+          email: "org-admin@example.com",
+        })
+      ),
+      orgTeamsStore: store,
+    });
+
+    const listTeamsResponse = await orgAdminApp.handle(
+      new Request("http://localhost/v1/auth/teams?org=hack")
+    );
+    expect(listTeamsResponse.status).toBe(200);
+    const listedTeams = (await listTeamsResponse.json()) as {
+      readonly teams?: ReadonlyArray<{ readonly slug?: string }>;
+    };
+    expect(listedTeams.teams?.map((team) => team.slug)).toEqual(["cli"]);
+
+    const addTeamMemberResponse = await orgAdminApp.handle(
+      new Request("http://localhost/v1/auth/teams/cli/members/add", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          org: "hack",
+          target: "user-789",
+        }),
+      })
+    );
+    expect(addTeamMemberResponse.status).toBe(200);
+    const addedMembership = (await addTeamMemberResponse.json()) as {
+      readonly membership?: {
+        readonly scope?: string;
+        readonly state?: string;
+      };
+    };
+    expect(addedMembership.membership?.scope).toBe("team");
+    expect(addedMembership.membership?.state).toBe("active");
+  });
+
   test("team membership changes require an active parent org membership", async () => {
     const store = new InMemoryOrgTeamsStore();
     const ownerApp = createAuthBrokerApp({

From 4ec26f07eb2713e134a0c42f2996051d3f698fed Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Sun, 22 Mar 2026 19:26:32 +0000
Subject: [PATCH 130/134] chore(symphony): checkpoint HACK-465 before
 integration

---
 .cursor/rules/hack.mdc | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/.cursor/rules/hack.mdc b/.cursor/rules/hack.mdc
index 835164c17..8f55277b3 100644
--- a/.cursor/rules/hack.mdc
+++ b/.cursor/rules/hack.mdc
@@ -37,6 +37,12 @@ hack down
 hack global status
 hack session
 hack tickets list
+hack node list
+hack node status --watch
+hack node ssh setup --node <id>
+hack node routes status
+hack node routes repair
+hack dispatch run --project <name|id> --node default --branch <branch> --runner generic -- "pwd"
 hack internal extra-hosts list
 hack internal extra-hosts set <hostname> <target>
 hack internal extra-hosts unset <hostname>

From 6330a0f16d6d246ebeb19d6459bf9bd3efa22e9d Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Mon, 23 Mar 2026 11:46:09 -0400
Subject: [PATCH 131/134] chore(symphony): finalize HACK-546 merge branch
 workspace updates

---
 src/commands/project.ts       |  43 +++--
 src/commands/session.ts       | 329 +++++++++++++++++++++++-----------
 src/mux/session-names.ts      |  33 +++-
 tests/session-command.test.ts | 165 +++++++++++++++++
 tests/session-names.test.ts   |  47 +++++
 5 files changed, 487 insertions(+), 130 deletions(-)
 create mode 100644 tests/session-command.test.ts
 create mode 100644 tests/session-names.test.ts

diff --git a/src/commands/project.ts b/src/commands/project.ts
index c18106309..2d8e37118 100644
--- a/src/commands/project.ts
+++ b/src/commands/project.ts
@@ -125,7 +125,7 @@ import {
   resolveDefaultBackendName,
   resolveMux,
 } from "../mux/mux-resolver.ts";
-import { buildSessionName } from "../mux/session-names.ts";
+import { buildLifecycleSessionName } from "../mux/session-names.ts";
 import {
   renderProjectConfigJson,
   renderProjectEnvContractJson,
@@ -947,8 +947,7 @@ function resolveLifecycleSessionName(opts: {
   readonly projectName: string;
   readonly branch: string | null;
 }): string {
-  const suffix = opts.branch ? `lifecycle-${opts.branch}` : "lifecycle";
-  return buildSessionName({ base: opts.projectName, suffix });
+  return buildLifecycleSessionName(opts);
 }
 
 function resolveLifecycleCwd(opts: {
@@ -1983,29 +1982,39 @@ function parseComposeServiceNetworkNames(value: unknown): readonly string[] {
   if (!isRecord(value)) {
     return [];
   }
+
   const networks = value.networks;
   if (Array.isArray(networks)) {
     const out: string[] = [];
     for (const entry of networks) {
-      if (typeof entry === "string" && entry.trim().length > 0) {
-        out.push(entry.trim());
-      } else if (isRecord(entry)) {
-        for (const key of Object.keys(entry)) {
-          const trimmed = key.trim();
-          if (trimmed.length > 0) {
-            out.push(trimmed);
-          }
-        }
+      const names = parseComposeNetworkEntry(entry);
+      for (const name of names) {
+        out.push(name);
       }
     }
     return out;
   }
-  if (isRecord(networks)) {
-    return Object.keys(networks)
-      .map((entry) => entry.trim())
-      .filter((entry) => entry.length > 0);
+
+  if (!isRecord(networks)) {
+    return [];
+  }
+
+  return Object.keys(networks)
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+function parseComposeNetworkEntry(value: unknown): readonly string[] {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? [trimmed] : [];
+  }
+  if (!isRecord(value)) {
+    return [];
   }
-  return [];
+  return Object.keys(value)
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
 }
 
 async function readComposeCaddyHosts(
diff --git a/src/commands/session.ts b/src/commands/session.ts
index 496084e9b..f2cb9dac9 100644
--- a/src/commands/session.ts
+++ b/src/commands/session.ts
@@ -10,6 +10,7 @@ import { optJson, optPretty } from "../cli/options.ts";
 import type { RegisteredProject } from "../lib/projects-registry.ts";
 import { readProjectsRegistry } from "../lib/projects-registry.ts";
 import { exec, run } from "../lib/shell.ts";
+import { buildSessionName } from "../mux/session-names.ts";
 import { logger } from "../ui/logger.ts";
 import {
   buildSessionPanesEndEvent,
@@ -225,6 +226,7 @@ type TailArgs = CommandArgs<
  *
  * Uses clack prompts with grouped options for sessions and projects.
  */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: explicit CLI branching keeps command UX behavior stable.
 async function handleSessionPicker(): Promise<number> {
   const sessions = await listTmuxSessions();
   const registry = await readProjectsRegistry();
@@ -323,7 +325,11 @@ async function handleSessionPicker(): Promise<number> {
         message: `Session '${name}' is attached elsewhere`,
         options: [
           { value: "attach", label: "Attach", hint: "detaches other clients" },
-          { value: "new", label: "Create new", hint: `${name}:${nextNum}` },
+          {
+            value: "new",
+            label: "Create new",
+            hint: buildSessionName({ base: name, suffix: String(nextNum) }),
+          },
         ],
       });
 
@@ -338,7 +344,7 @@ async function handleSessionPicker(): Promise<number> {
         );
         const cwd = project?.repoRoot ?? session.path ?? process.cwd();
         return await createAndAttachSession({
-          name: `${name}:${nextNum}`,
+          name: buildSessionName({ base: name, suffix: String(nextNum) }),
           cwd,
         });
       }
@@ -420,98 +426,126 @@ const handleStart = async ({
   readonly args: StartArgs;
 }): Promise<number> => {
   const projectNameOrPath = args.positionals.project;
-  const forceNew = args.options.new === true;
-  const runUp = args.options.up === true;
-  const customName = args.options.name;
-  const detach = args.options.detach === true;
-
-  // Find project
   const registry = await readProjectsRegistry();
-  const projects = registry.projects;
-  let project = projectNameOrPath
-    ? projects.find(
-        (p: RegisteredProject) =>
-          p.name === projectNameOrPath ||
-          p.projectDir === resolve(projectNameOrPath)
-      )
-    : null;
-
-  if (!project && projectNameOrPath) {
-    // Try as path
-    const resolvedPath = resolve(projectNameOrPath);
-    project = projects.find(
-      (p: RegisteredProject) => p.projectDir === resolvedPath
-    );
-  }
-
+  const project = resolveProjectForSessionStart({
+    projects: registry.projects,
+    projectNameOrPath,
+  });
   if (!project) {
     if (projectNameOrPath) {
       logger.error({ message: `Project not found: ${projectNameOrPath}` });
-    } else {
-      logger.error({
-        message: "No project specified. Use: hack session start <project>",
-      });
+      return 1;
     }
+    logger.error({
+      message: "No project specified. Use: hack session start <project>",
+    });
     return 1;
   }
 
-  const baseName = project.name;
-  let sessionName = baseName;
+  return await startOrAttachSession({
+    project,
+    args,
+    sessions: await listTmuxSessions(),
+  });
+};
 
-  if (forceNew || customName) {
-    if (customName) {
-      sessionName = `${baseName}:${customName}`;
-    } else {
-      // Find next available number
-      const sessions = await listTmuxSessions();
-      const existing = sessions.filter(
-        (s) => s.name === baseName || s.name.startsWith(`${baseName}:`)
-      );
-      if (existing.length > 0) {
-        let n = 2;
-        while (existing.some((s) => s.name === `${baseName}:${n}`)) {
-          n++;
-        }
-        sessionName = `${baseName}:${n}`;
-      }
+function resolveProjectForSessionStart(opts: {
+  readonly projects: readonly RegisteredProject[];
+  readonly projectNameOrPath: string | undefined;
+}): RegisteredProject | null {
+  if (!opts.projectNameOrPath) {
+    return null;
+  }
+
+  const input = opts.projectNameOrPath;
+  const normalizedPath = resolve(input);
+  const project =
+    opts.projects.find(
+      (p: RegisteredProject) =>
+        p.name === input ||
+        p.projectDir === input ||
+        p.projectDir === normalizedPath
+    ) ?? null;
+
+  return project;
+}
+
+function buildSessionNameForStart(opts: {
+  readonly baseName: string;
+  readonly sessions: readonly TmuxSession[];
+  readonly forceNew: boolean;
+  readonly customSuffix?: string;
+}): string | null {
+  const hasCustomSuffix = opts.customSuffix !== undefined;
+  if (!(opts.forceNew || hasCustomSuffix)) {
+    const exists = opts.sessions.find((s) => s.name === opts.baseName);
+    if (exists) {
+      return null;
     }
-  } else {
-    // Check if session exists
-    const sessions = await listTmuxSessions();
-    const existing = sessions.find((s) => s.name === baseName);
-    if (existing) {
-      if (detach) {
-        logger.info({ message: `Session ready: ${baseName}` });
-      } else {
-        logger.info({ message: `Attaching to existing session: ${baseName}` });
-      }
-      if (runUp) {
-        await runHackUp(project.projectDir);
-      }
-      if (detach) {
-        return 0;
-      }
-      return await attachToSession(baseName);
+    return opts.baseName;
+  }
+
+  if (hasCustomSuffix) {
+    return buildSessionName({
+      base: opts.baseName,
+      suffix: opts.customSuffix,
+    });
+  }
+
+  const existing = opts.sessions.filter(
+    (s) => s.name === opts.baseName || s.name.startsWith(`${opts.baseName}:`)
+  );
+  let n = 2;
+  while (existing.some((s) => s.name === `${opts.baseName}:${n}`)) {
+    n++;
+  }
+  return buildSessionName({
+    base: opts.baseName,
+    suffix: String(n),
+  });
+}
+
+async function startOrAttachSession(opts: {
+  readonly project: RegisteredProject;
+  readonly args: StartArgs;
+  readonly sessions: readonly TmuxSession[];
+}): Promise<number> {
+  const sessionName = buildSessionNameForStart({
+    baseName: opts.project.name,
+    sessions: opts.sessions,
+    forceNew: opts.args.options.new === true,
+    customSuffix: opts.args.options.name,
+  });
+  const runUp = opts.args.options.up === true;
+  const detach = opts.args.options.detach === true;
+
+  if (sessionName === null) {
+    if (runUp) {
+      await runHackUp(opts.project.projectDir);
     }
+    if (detach) {
+      logger.info({ message: `Session ready: ${opts.project.name}` });
+      return 0;
+    }
+    return await attachToSession(opts.project.name);
   }
 
-  // Run hack up if requested
   if (runUp) {
-    await runHackUp(project.repoRoot);
+    await runHackUp(opts.project.repoRoot);
   }
 
-  // Use repoRoot (project root), not projectDir (.hack/)
   if (detach) {
     return await createSessionDetached({
       name: sessionName,
-      cwd: project.repoRoot,
+      cwd: opts.project.repoRoot,
     });
   }
+
   return await createAndAttachSession({
     name: sessionName,
-    cwd: project.repoRoot,
+    cwd: opts.project.repoRoot,
   });
-};
+}
 
 const handleStop = async ({
   args,
@@ -698,44 +732,38 @@ const handleTail = async ({
   readonly ctx: CliContext;
   readonly args: TailArgs;
 }): Promise<number> => {
-  const sessionName = args.positionals.session;
-  const target =
-    args.options.target ?? (await resolveActiveTarget(sessionName));
-  const lines = args.options.lines ?? 200;
-  const intervalMs = args.options.intervalMs ?? 500;
-  const maxMs = args.options.maxMs ?? 5000;
-  const pretty = args.options.pretty === true;
-  const json = args.options.json === true || !pretty;
+  const opts = await buildTailArgs({
+    sessionName: args.positionals.session,
+    options: args.options,
+  });
 
-  if (json && pretty) {
+  if (opts.json && opts.pretty) {
     process.stderr.write("Cannot combine --json with --pretty.\n");
     return 1;
   }
 
-  const context = {
-    session: sessionName,
-    target,
-    lines,
-    follow: true,
-    intervalMs,
-    maxMs,
-  };
-
-  if (json) {
+  if (opts.json) {
     writeSessionStreamEvent({
-      event: buildSessionStreamStartEvent({ context }),
+      event: buildSessionStreamStartEvent({ context: opts.context }),
     });
   }
 
-  const initial = await capturePane({ target, lines });
+  const initial = await capturePane({ target: opts.target, lines: opts.lines });
   if (initial.exitCode !== 0) {
-    const message = initial.stderr || `Failed to capture ${sessionName}`;
-    if (json) {
+    const message =
+      initial.stderr || `Failed to capture ${opts.context.session}`;
+    if (opts.json) {
       writeSessionStreamEvent({
-        event: buildSessionStreamErrorEvent({ context, message }),
+        event: buildSessionStreamErrorEvent({
+          context: opts.context,
+          message,
+        }),
       });
       writeSessionStreamEvent({
-        event: buildSessionStreamEndEvent({ context, reason: "error" }),
+        event: buildSessionStreamEndEvent({
+          context: opts.context,
+          reason: "error",
+        }),
       });
     } else {
       console.error(message);
@@ -743,21 +771,103 @@ const handleTail = async ({
     return 1;
   }
 
-  let lastOutput = initial.stdout;
+  return await streamTailOutput({
+    context: opts.context,
+    target: opts.target,
+    lines: opts.lines,
+    json: opts.json,
+    initial,
+  });
+};
+
+async function buildTailArgs(opts: {
+  readonly sessionName: string;
+  readonly options: TailArgs["options"];
+}): Promise<{
+  readonly target: string;
+  readonly lines: number;
+  readonly intervalMs: number;
+  readonly maxMs: number;
+  readonly pretty: boolean;
+  readonly json: boolean;
+  readonly context: {
+    readonly session: string;
+    readonly target: string;
+    readonly lines: number;
+    readonly follow: boolean;
+    readonly intervalMs: number;
+    readonly maxMs: number;
+  };
+}> {
+  const target =
+    opts.options.target ?? (await resolveActiveTarget(opts.sessionName));
+  const lines = opts.options.lines ?? 200;
+  const intervalMs = opts.options.intervalMs ?? 500;
+  const maxMs = opts.options.maxMs ?? 5000;
+  const pretty = opts.options.pretty === true;
+  const json = opts.options.json === true || !pretty;
+
+  return {
+    target,
+    lines,
+    intervalMs,
+    maxMs,
+    pretty,
+    json,
+    context: {
+      session: opts.sessionName,
+      target,
+      lines,
+      follow: true,
+      intervalMs,
+      maxMs,
+    },
+  };
+}
+
+async function streamTailOutput(opts: {
+  readonly context: {
+    readonly session: string;
+    readonly target: string;
+    readonly lines: number;
+    readonly follow: boolean;
+    readonly intervalMs: number;
+    readonly maxMs: number;
+  };
+  readonly lines: number;
+  readonly target: string;
+  readonly json: boolean;
+  readonly initial: {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+  };
+}): Promise<number> {
+  let lastOutput = opts.initial.stdout;
   const start = Date.now();
 
-  while (Date.now() - start < maxMs) {
-    await delay(intervalMs);
+  while (Date.now() - start < opts.context.maxMs) {
+    await delay(opts.context.intervalMs);
 
-    const result = await capturePane({ target, lines });
+    const result = await capturePane({
+      target: opts.target,
+      lines: opts.lines,
+    });
     if (result.exitCode !== 0) {
-      const message = result.stderr || `Failed to capture ${sessionName}`;
-      if (json) {
+      const message =
+        result.stderr || `Failed to capture ${opts.context.session}`;
+      if (opts.json) {
         writeSessionStreamEvent({
-          event: buildSessionStreamErrorEvent({ context, message }),
+          event: buildSessionStreamErrorEvent({
+            context: opts.context,
+            message,
+          }),
         });
         writeSessionStreamEvent({
-          event: buildSessionStreamEndEvent({ context, reason: "error" }),
+          event: buildSessionStreamEndEvent({
+            context: opts.context,
+            reason: "error",
+          }),
         });
       } else {
         console.error(message);
@@ -768,10 +878,10 @@ const handleTail = async ({
     const nextOutput = result.stdout;
     const suffix = diffNewLines({ previous: lastOutput, next: nextOutput });
     if (suffix) {
-      if (json) {
+      if (opts.json) {
         for (const line of splitLines(suffix)) {
           writeSessionStreamEvent({
-            event: buildSessionStreamLogEvent({ context, line }),
+            event: buildSessionStreamLogEvent({ context: opts.context, line }),
           });
         }
       } else {
@@ -782,14 +892,17 @@ const handleTail = async ({
     lastOutput = nextOutput;
   }
 
-  if (json) {
+  if (opts.json) {
     writeSessionStreamEvent({
-      event: buildSessionStreamEndEvent({ context, reason: "timeout" }),
+      event: buildSessionStreamEndEvent({
+        context: opts.context,
+        reason: "timeout",
+      }),
     });
   }
 
   return 0;
-};
+}
 
 export const sessionCommand = defineCommand({
   name: "session",
diff --git a/src/mux/session-names.ts b/src/mux/session-names.ts
index 794b58c20..d4fa54d2d 100644
--- a/src/mux/session-names.ts
+++ b/src/mux/session-names.ts
@@ -1,4 +1,5 @@
 const SESSION_DELIMITER = "--" as const;
+const LEGACY_SESSION_DELIMITER = ":" as const;
 
 export function buildSessionName(opts: {
   readonly base: string;
@@ -12,13 +13,35 @@ export function buildSessionName(opts: {
   return `${base}${SESSION_DELIMITER}${suffix}`;
 }
 
+export function buildLegacySessionName(opts: {
+  readonly base: string;
+  readonly suffix?: string;
+}): string {
+  const base = opts.base.trim();
+  const suffix = (opts.suffix ?? "").trim();
+  if (suffix.length === 0) {
+    return base;
+  }
+  return `${base}${LEGACY_SESSION_DELIMITER}${suffix}`;
+}
+
+export function buildLifecycleSessionName(opts: {
+  readonly projectName: string;
+  readonly branch: string | null;
+}): string {
+  const suffix = opts.branch ? `lifecycle-${opts.branch}` : "lifecycle";
+  return buildSessionName({ base: opts.projectName, suffix });
+}
+
 export function parseSessionBase(opts: { readonly name: string }): string {
   const name = opts.name.trim();
-  const idx = name.indexOf(SESSION_DELIMITER);
-  if (idx === -1) {
-    return name;
-  }
-  return name.slice(0, idx);
+  const delimiters = [
+    name.indexOf(SESSION_DELIMITER),
+    name.indexOf(LEGACY_SESSION_DELIMITER),
+  ].filter((index) => index >= 0);
+  const idx = delimiters.length > 0 ? Math.min(...delimiters) : -1;
+
+  return idx === -1 ? name : name.slice(0, idx);
 }
 
 export function getNextNumericSessionSuffix(opts: {
diff --git a/tests/session-command.test.ts b/tests/session-command.test.ts
new file mode 100644
index 000000000..2023457c9
--- /dev/null
+++ b/tests/session-command.test.ts
@@ -0,0 +1,165 @@
+import { afterAll, afterEach, beforeEach, expect, mock, test } from "bun:test";
+
+const selectResponses: string[] = [];
+const selectCalls: Array<{
+  readonly message: string;
+  readonly options: readonly {
+    readonly value: string;
+    readonly label: string;
+    readonly hint?: string;
+  }[];
+}> = [];
+const createdSessions: string[] = [];
+const runCalls: string[][] = [];
+
+let originalSetupSyncMode: string | undefined;
+let originalLogger: string | undefined;
+let originalTmux: string | undefined;
+
+mock.module("@clack/prompts", () => ({
+  access: async () => true,
+  autocompleteMultiselect: async () => [],
+  cancel: () => {},
+  confirm: async () => true,
+  intro: () => {},
+  multiselect: async () => [],
+  outro: () => {},
+  isCancel: () => false,
+  log: {
+    error: () => {},
+    info: () => {},
+    message: () => {},
+    success: () => {},
+    step: () => {},
+    warn: () => {},
+  },
+  note: () => {},
+  password: async () => "",
+  select: async (opts: {
+    readonly message: string;
+    readonly options: readonly {
+      readonly value: string;
+      readonly label: string;
+      readonly hint?: string;
+    }[];
+  }) => {
+    selectCalls.push(opts);
+    return selectResponses.shift() ?? "";
+  },
+  spinner: () => ({
+    start: () => {},
+    stop: () => {},
+  }),
+  text: async () => "",
+}));
+
+mock.module("../src/lib/projects-registry.ts", () => ({
+  readProjectsRegistry: async () => ({
+    version: 1,
+    projects: [
+      {
+        id: "alpha-id",
+        name: "alpha",
+        repoRoot: "/tmp/alpha",
+        projectDirName: ".hack",
+        projectDir: "/tmp/alpha/.hack",
+        devHost: "alpha.hack",
+        createdAt: "2025-01-01T00:00:00Z",
+      },
+    ],
+  }),
+  upsertProjectRegistration: async () => ({
+    status: "noop",
+    project: {
+      id: "alpha-id",
+      name: "alpha",
+      repoRoot: "/tmp/alpha",
+      projectDirName: ".hack",
+      projectDir: "/tmp/alpha/.hack",
+      devHost: "alpha.hack",
+      createdAt: "2025-01-01T00:00:00Z",
+    },
+  }),
+  resolveRegisteredProjectByName: async () => null,
+  resolveRegisteredProjectById: async () => null,
+  removeProjectsById: async () => ({ removed: [] }),
+}));
+
+mock.module("../src/lib/shell.ts", () => ({
+  exec: async (cmd: readonly string[]) => {
+    if (cmd[0] === "tmux" && cmd[1] === "list-sessions") {
+      return {
+        exitCode: 0,
+        stdout:
+          "alpha|||HACK_SESSION_FIELD|||1|||HACK_SESSION_FIELD|||/tmp/alpha\n",
+        stderr: "",
+      };
+    }
+
+    if (cmd[0] === "tmux" && cmd[1] === "new-session") {
+      createdSessions.push(cmd[4] ?? "");
+      return { exitCode: 0, stdout: "", stderr: "" };
+    }
+
+    return { exitCode: 0, stdout: "", stderr: "" };
+  },
+  execOrThrow: async (cmd: readonly string[]) => {
+    return await Promise.resolve({ exitCode: 0, stdout: "", stderr: "" });
+  },
+  run: async (cmd: readonly string[]) => {
+    runCalls.push([...cmd]);
+    return 0;
+  },
+  findExecutableInPath: () => "/usr/bin/mock-bin",
+  CommandError: class CommandError extends Error {},
+}));
+
+beforeEach(() => {
+  originalSetupSyncMode = process.env.HACK_SETUP_SYNC_MODE;
+  originalLogger = process.env.HACK_LOGGER;
+  originalTmux = process.env.TMUX;
+  process.env.HACK_SETUP_SYNC_MODE = "off";
+  process.env.HACK_LOGGER = "console";
+  process.env.TMUX = undefined;
+  selectResponses.length = 0;
+  selectCalls.length = 0;
+  createdSessions.length = 0;
+  runCalls.length = 0;
+});
+
+afterEach(() => {
+  if (originalSetupSyncMode === undefined) {
+    process.env.HACK_SETUP_SYNC_MODE = undefined;
+  } else {
+    process.env.HACK_SETUP_SYNC_MODE = originalSetupSyncMode;
+  }
+
+  if (originalLogger === undefined) {
+    process.env.HACK_LOGGER = undefined;
+  } else {
+    process.env.HACK_LOGGER = originalLogger;
+  }
+
+  if (originalTmux === undefined) {
+    process.env.TMUX = undefined;
+  } else {
+    process.env.TMUX = originalTmux;
+  }
+});
+
+afterAll(() => {
+  mock.restore();
+});
+
+test("session picker creates double-dash sibling sessions for attached projects", async () => {
+  selectResponses.push("session:alpha", "new");
+
+  const { runCli } = await import("../src/cli/run.ts");
+  const exitCode = await runCli(["session"]);
+
+  expect(exitCode).toBe(0);
+  expect(selectCalls).toHaveLength(2);
+  expect(selectCalls[1]?.options[1]?.hint).toBe("alpha--2");
+  expect(createdSessions).toEqual(["alpha--2"]);
+  expect(runCalls).toContainEqual(["tmux", "attach", "-d", "-t", "alpha--2"]);
+});
diff --git a/tests/session-names.test.ts b/tests/session-names.test.ts
new file mode 100644
index 000000000..8fa43272a
--- /dev/null
+++ b/tests/session-names.test.ts
@@ -0,0 +1,47 @@
+import { expect, test } from "bun:test";
+
+import {
+  buildLegacySessionName,
+  buildLifecycleSessionName,
+  buildSessionName,
+  getNextNumericSessionSuffix,
+  parseSessionBase,
+} from "../src/mux/session-names.ts";
+
+test("buildSessionName uses double-dash suffixes", () => {
+  expect(buildSessionName({ base: "my-project", suffix: "agent-1" })).toBe(
+    "my-project--agent-1"
+  );
+});
+
+test("buildLegacySessionName preserves colon-delimited names", () => {
+  expect(
+    buildLegacySessionName({ base: "my-project", suffix: "lifecycle" })
+  ).toBe("my-project:lifecycle");
+});
+
+test("buildLifecycleSessionName uses double-dash lifecycle suffixes", () => {
+  expect(
+    buildLifecycleSessionName({ projectName: "my-project", branch: null })
+  ).toBe("my-project--lifecycle");
+  expect(
+    buildLifecycleSessionName({
+      projectName: "my-project",
+      branch: "feature-login",
+    })
+  ).toBe("my-project--lifecycle-feature-login");
+});
+
+test("getNextNumericSessionSuffix skips existing double-dash sessions", () => {
+  const suffix = getNextNumericSessionSuffix({
+    base: "my-project",
+    sessions: [{ name: "my-project" }, { name: "my-project--2" }],
+  });
+
+  expect(suffix).toBe(3);
+});
+
+test("parseSessionBase supports double-dash and legacy colon session names", () => {
+  expect(parseSessionBase({ name: "my-project--agent-1" })).toBe("my-project");
+  expect(parseSessionBase({ name: "my-project:agent-1" })).toBe("my-project");
+});

From 389740c07995adb66c7bb5ec8109053a9795462b Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Mon, 23 Mar 2026 11:57:03 -0400
Subject: [PATCH 132/134] test(tickets): expose checkout helper paths under
 __testOnly

---
 .../extensions/tickets/tickets-git-channel.ts | 38 +++++++++++++++++++
 src/daemon/client.ts                          | 35 +++++++++++++++++
 2 files changed, 73 insertions(+)

diff --git a/src/control-plane/extensions/tickets/tickets-git-channel.ts b/src/control-plane/extensions/tickets/tickets-git-channel.ts
index 3f9d00fc1..94929a0fa 100644
--- a/src/control-plane/extensions/tickets/tickets-git-channel.ts
+++ b/src/control-plane/extensions/tickets/tickets-git-channel.ts
@@ -1348,6 +1348,8 @@ function isGitIndexLockError(message: string): boolean {
 export const __testOnly = {
   mergeTicketEventLogs,
   resolvePushRefForCheckoutRef,
+  resolveLocalCheckoutFallback,
+  resolveLegacyImportFetchResult,
 };
 
 function resolvePushRefForCheckoutRef(input: {
@@ -1365,3 +1367,39 @@ function resolvePushRefForCheckoutRef(input: {
   }
   return input.remoteRef;
 }
+
+function resolveLocalCheckoutFallback(input: {
+  readonly fetchFailure: string;
+  readonly allowFetchFailureFallback: boolean;
+  readonly preferredTrackingRef: string;
+  readonly remoteRef: string;
+  readonly legacyTrackingRef?: string | null;
+  readonly legacyRemoteRef?: string | null;
+}):
+  | { readonly ok: true; readonly pushRef: string }
+  | { readonly ok: false; readonly error: string } {
+  if (!input.allowFetchFailureFallback) {
+    return { ok: false, error: input.fetchFailure };
+  }
+  return {
+    ok: true,
+    pushRef: resolvePushRefForCheckoutRef({
+      checkoutRef: input.preferredTrackingRef,
+      remoteRef: input.remoteRef,
+      legacyTrackingRef: input.legacyTrackingRef,
+      legacyRemoteRef: input.legacyRemoteRef,
+    }),
+  };
+}
+
+function resolveLegacyImportFetchResult(input: {
+  readonly missing: boolean;
+  readonly error: string;
+}):
+  | { readonly ok: true; readonly imported: false }
+  | { readonly ok: false; readonly error: string } {
+  if (input.missing) {
+    return { ok: true, imported: false };
+  }
+  return { ok: false, error: `git fetch failed: ${input.error}` };
+}
diff --git a/src/daemon/client.ts b/src/daemon/client.ts
index e9b4c1436..5472ea025 100644
--- a/src/daemon/client.ts
+++ b/src/daemon/client.ts
@@ -31,6 +31,12 @@ export type DaemonJsonResponse = {
   readonly json: Record<string, unknown> | null;
 };
 
+export type DaemonApiProbe = {
+  readonly reachable: boolean;
+  readonly compatible: boolean;
+  readonly version: string | null;
+};
+
 export async function requestDaemonJson(opts: {
   readonly path: string;
   readonly query?: Record<string, string | boolean | null>;
@@ -146,6 +152,35 @@ async function ensureDaemonSocketReady(opts: {
   return await ensureDaemonReady({ paths: opts.paths });
 }
 
+export async function probeDaemonApi(opts: {
+  readonly socketPath: string;
+  readonly timeoutMs?: number;
+}): Promise<DaemonApiProbe> {
+  const raw = await requestDaemonRaw({
+    socketPath: opts.socketPath,
+    method: "GET",
+    path: "/v1/status",
+    timeoutMs: opts.timeoutMs ?? 1000,
+  });
+  if (!raw) {
+    return {
+      reachable: false,
+      compatible: false,
+      version: null,
+    };
+  }
+
+  const json = safeJsonParse({
+    text: raw.body,
+  });
+  const version = json ? json.version : null;
+  return {
+    reachable: true,
+    compatible: typeof version === "string" && version === packageJson.version,
+    version: typeof version === "string" ? version : null,
+  };
+}
+
 /**
  * Ensures launchd manages hackd and kicks it when needed.
  */

From 05d90bdfe790cab740fc783124394ace292523a2 Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Mon, 23 Mar 2026 12:37:37 -0400
Subject: [PATCH 133/134] integrate: preserve HACK-434 runtime hardening assets

---
 ...me-session-remote-beta-hardening-design.md | 106 ++++++++++
 ...time-session-remote-beta-hardening-plan.md | 182 ++++++++++++++++++
 src/lib/runtime-guidance.ts                   | 132 +++++++++++++
 tests/config-paths.test.ts                    |  36 ++++
 tests/runtime-guidance.test.ts                |  80 ++++++++
 5 files changed, 536 insertions(+)
 create mode 100644 docs/plans/2026-03-13-runtime-session-remote-beta-hardening-design.md
 create mode 100644 docs/plans/2026-03-13-runtime-session-remote-beta-hardening-plan.md
 create mode 100644 src/lib/runtime-guidance.ts
 create mode 100644 tests/config-paths.test.ts
 create mode 100644 tests/runtime-guidance.test.ts

diff --git a/docs/plans/2026-03-13-runtime-session-remote-beta-hardening-design.md b/docs/plans/2026-03-13-runtime-session-remote-beta-hardening-design.md
new file mode 100644
index 000000000..e8b539c36
--- /dev/null
+++ b/docs/plans/2026-03-13-runtime-session-remote-beta-hardening-design.md
@@ -0,0 +1,106 @@
+# Runtime, Session, and Remote Beta Hardening Design
+
+**Date:** 2026-03-13
+
+## Goal
+
+Harden the default local runtime path around Docker Desktop, make daemon/runtime failures produce actionable repair guidance, clarify tmux-first session semantics, and label remote or multi-node flows as beta where users first encounter them.
+
+## Scope
+
+- Share Docker backend detection outside `global` so runtime diagnostics can explain what to do next.
+- Improve `doctor` and `daemon status` output so runtime and daemon failures point to concrete recovery steps.
+- Capture Docker Desktop-relevant diagnostics in `hack crash-capture` instead of assuming OrbStack.
+- Align session naming and help text with tmux-first semantics and existing SSH or daemon constraints.
+- Label remote, node, and dispatch surfaces as beta in command summaries and docs.
+
+## Non-Goals
+
+- Rewriting mux backend support across the CLI.
+- Changing remote control-plane behavior beyond messaging, labeling, and guidance.
+- Reworking daemon architecture or Docker event handling internals.
+
+## Current Problems
+
+### Runtime guidance is inconsistent
+
+`hack global install` knows how to detect Docker Desktop vs OrbStack, but `hack doctor` still reports a generic “Docker daemon is not reachable” message. That means the common recovery path is least helpful on the common failure.
+
+### Daemon failures are under-explained
+
+`hack daemon status` distinguishes running, starting, stale, and stopped, but the user-facing output does not explain whether the right next step is clearing stale state, restarting the daemon, or starting the Docker backend.
+
+### Crash capture is OrbStack-biased
+
+`hack crash-capture` already collects useful Docker state, but its macOS unified log collection specifically targets OrbStack. Docker Desktop-first users do not get equally targeted diagnostics.
+
+### Sessions are conceptually tmux-first but operationally inconsistent
+
+The resolver already prefers tmux in `auto` mode, but the CLI and docs overstate general mux support while `hack session` remains tmux-centric. There is also a session naming mismatch: docs describe `--` separators while the CLI currently creates `:` suffixed session names, which conflicts with SSH and daemon session validators.
+
+### Remote flows are not clearly beta-labeled
+
+Remote, multi-node, and dispatch flows are presented as ordinary command surfaces even though the surrounding docs and acceptance criteria position them as beta.
+
+## Proposed Changes
+
+### 1. Shared Docker backend diagnostics
+
+Create a small shared helper that:
+
+- detects the local Docker backend
+- formats backend-aware repair guidance
+- can be reused by `global`, `doctor`, and daemon-facing status output
+
+The default messaging should prefer Docker Desktop language when it is the installed backend, while still supporting OrbStack and Linux systemd paths.
+
+### 2. Actionable doctor and daemon guidance
+
+Update `hack doctor` so Docker failures include:
+
+- the specific `docker info` failure text when available
+- the detected backend name
+- the most relevant next step, such as starting Docker Desktop, rerunning `hack doctor`, or using `hack global install`
+
+Update `hack daemon status` human-readable output so it distinguishes:
+
+- stale local state that should be cleared
+- daemon not running while launchd is loaded
+- launchd exit status that implies a crash
+- follow-up recovery commands
+
+### 3. Docker Desktop-inclusive crash capture
+
+Expand crash capture collection on macOS to include Docker Desktop process and unified log matches alongside existing OrbStack diagnostics. This keeps the artifact relevant no matter which supported backend the user runs.
+
+### 4. tmux-first session semantics and naming cleanup
+
+Keep the resolver unchanged, but make the user-facing behavior consistent:
+
+- session docs and command summaries should say tmux-first plainly
+- generated agent guidance should mention the tmux-first default
+- new session names should use the documented `--` separator so they remain compatible with SSH and daemon session routes
+
+### 5. Explicit beta labeling for remote and multi-node flows
+
+Add beta wording to:
+
+- `hack remote`
+- `hack node`
+- `hack dispatch`
+- the docs entry points that send users into remote or multi-node setup
+
+The goal is expectation-setting, not warning fatigue, so the label should appear at the feature entry points instead of every downstream command.
+
+## Testing Strategy
+
+- Add unit tests for daemon status rendering helpers and backend-aware runtime guidance.
+- Add CLI-facing tests for session naming compatibility.
+- Add targeted tests for remote or beta-labeled command summaries where practical through CLI spec inspection.
+- Run focused `bun test` suites for touched areas before broader checks.
+
+## Risks
+
+- Session name changes can affect any code that assumes `:` separators, so the test pass needs to include SSH and daemon route compatibility.
+- Help text changes may require updating generated docs manually if there is no doc generation step wired into the repo.
+- Backend-aware guidance must stay concise or it will bury the actual failure signal.
diff --git a/docs/plans/2026-03-13-runtime-session-remote-beta-hardening-plan.md b/docs/plans/2026-03-13-runtime-session-remote-beta-hardening-plan.md
new file mode 100644
index 000000000..ba40855ed
--- /dev/null
+++ b/docs/plans/2026-03-13-runtime-session-remote-beta-hardening-plan.md
@@ -0,0 +1,182 @@
+# Runtime, Session, and Remote Beta Hardening Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Harden runtime and daemon repair guidance, align tmux-first session behavior, and beta-label remote or multi-node entry points.
+
+**Architecture:** Reuse a shared Docker backend diagnostics helper instead of duplicating backend detection in command code. Keep the code changes narrow: add tests around helper output and session naming, then update command summaries, human-readable status paths, and docs to match the intended UX.
+
+**Tech Stack:** Bun, TypeScript, bun:test, markdown docs
+
+---
+
+### Task 1: Record backend-aware runtime guidance
+
+**Files:**
+- Create: `tests/runtime-guidance.test.ts`
+- Create: `src/lib/runtime-guidance.ts`
+- Modify: `src/commands/global.ts`
+- Modify: `src/commands/doctor.ts`
+
+**Step 1: Write the failing test**
+
+Add tests that prove:
+- Docker Desktop is identified distinctly from OrbStack
+- unreachable Docker guidance includes backend-aware next steps
+- doctor-facing formatting preserves the underlying runtime failure text
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/runtime-guidance.test.ts`
+Expected: FAIL because the shared guidance helper does not exist yet
+
+**Step 3: Write minimal implementation**
+
+Extract backend detection from `src/commands/global.ts` into `src/lib/runtime-guidance.ts`, then consume it from `global` and `doctor`.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/runtime-guidance.test.ts`
+Expected: PASS
+
+### Task 2: Make daemon status report repairable
+
+**Files:**
+- Modify: `tests/daemon-status.test.ts`
+- Modify: `tests/daemon-command.test.ts`
+- Modify: `src/daemon/status.ts`
+- Modify: `src/commands/daemon.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+- a crash-oriented daemon status classification when launchd reports a non-zero exit status
+- human-readable daemon status output that recommends `hack daemon clear` for stale state and `hack daemon restart` or Docker startup for crash-like states
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/daemon-status.test.ts tests/daemon-command.test.ts`
+Expected: FAIL because daemon status does not yet encode or render those states
+
+**Step 3: Write minimal implementation**
+
+Extend the daemon status model and user-facing rendering to surface crash or repair guidance without changing the daemon API shape more than necessary.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/daemon-status.test.ts tests/daemon-command.test.ts`
+Expected: PASS
+
+### Task 3: Align session naming with tmux-first docs and validators
+
+**Files:**
+- Create: `tests/session-command.test.ts`
+- Modify: `src/commands/session.ts`
+- Modify: `docs/sessions.md`
+- Modify: `docs/cli.md`
+- Modify: `src/mcp/agent-docs.ts`
+
+**Step 1: Write the failing test**
+
+Add tests that prove:
+- auto-generated session suffixes use `--2`
+- custom session suffixes use `--agent-1`
+- existing docs/help wording can accurately describe `hack session` as tmux-first
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/session-command.test.ts`
+Expected: FAIL because the CLI still creates `:`-suffixed session names
+
+**Step 3: Write minimal implementation**
+
+Update session name generation and the tmux-first messaging surfaces without changing the resolver strategy.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/session-command.test.ts`
+Expected: PASS
+
+### Task 4: Label remote and multi-node entry points as beta
+
+**Files:**
+- Modify: `tests/cli-command.test.ts`
+- Modify: `src/commands/remote.ts`
+- Modify: `src/commands/node.ts`
+- Modify: `src/commands/dispatch.ts`
+- Modify: `README.md`
+- Modify: `docs/README.md`
+- Modify: `docs/guides/remote-node-quickstart.md`
+- Modify: `docs/guides/remote-node-container.md`
+- Modify: `docs/guides/remote-node-railway.md`
+
+**Step 1: Write the failing test**
+
+Add spec-level assertions that the command summaries for `remote`, `node`, and `dispatch` include beta wording.
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/cli-command.test.ts`
+Expected: FAIL because the current summaries do not include beta labels
+
+**Step 3: Write minimal implementation**
+
+Update command summaries and the high-level docs that introduce remote or multi-node flows.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/cli-command.test.ts`
+Expected: PASS
+
+### Task 5: Capture Docker Desktop diagnostics during crash triage
+
+**Files:**
+- Create: `tests/crash-capture.test.ts`
+- Modify: `src/commands/crash-capture.ts`
+- Modify: `docs/cli.md`
+
+**Step 1: Write the failing test**
+
+Add a test that proves the crash-capture command set includes Docker Desktop-specific macOS log or process probes.
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/crash-capture.test.ts`
+Expected: FAIL because only OrbStack-specific probes exist today
+
+**Step 3: Write minimal implementation**
+
+Broaden the macOS diagnostics probes to include Docker Desktop terms while keeping OrbStack capture intact.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/crash-capture.test.ts`
+Expected: PASS
+
+### Task 6: Run focused and broader verification
+
+**Files:**
+- Modify: any touched files above
+
+**Step 1: Run focused suites**
+
+Run:
+- `bun test tests/runtime-guidance.test.ts`
+- `bun test tests/daemon-status.test.ts tests/daemon-command.test.ts`
+- `bun test tests/session-command.test.ts`
+- `bun test tests/cli-command.test.ts`
+- `bun test tests/crash-capture.test.ts`
+
+Expected: PASS
+
+**Step 2: Run broader quality gates**
+
+Run:
+- `bun test`
+- `bunx ultracite check`
+
+Expected: PASS or only pre-existing unrelated failures
+
+**Step 3: Document remaining work**
+
+If any desired hardening remains outside this slice, create follow-up `hack tickets` before ending the session.
diff --git a/src/lib/runtime-guidance.ts b/src/lib/runtime-guidance.ts
new file mode 100644
index 000000000..7653be3a5
--- /dev/null
+++ b/src/lib/runtime-guidance.ts
@@ -0,0 +1,132 @@
+import { pathExists } from "./fs.ts";
+import { isMac } from "./os.ts";
+import { type ExecResult, exec, findExecutableInPath } from "./shell.ts";
+
+export type DockerBackendId = "docker-desktop" | "orbstack" | "docker-systemd";
+
+export type DockerBackend = {
+  readonly id: DockerBackendId;
+  readonly name: string;
+  readonly startCommand: readonly string[];
+};
+
+type DetectDockerBackendDeps = {
+  readonly findExecutableInPath?: typeof findExecutableInPath;
+  readonly isMac?: boolean;
+  readonly pathExists?: typeof pathExists;
+};
+
+type DockerStatusProbeDeps = {
+  readonly exec?: typeof exec;
+  readonly findExecutableInPath?: typeof findExecutableInPath;
+};
+
+export async function detectDockerBackend(
+  deps: DetectDockerBackendDeps = {}
+): Promise<DockerBackend | null> {
+  const onMac = deps.isMac ?? isMac();
+  const hasPath = deps.pathExists ?? pathExists;
+  const findOnPath = deps.findExecutableInPath ?? findExecutableInPath;
+
+  if (onMac) {
+    if (await hasPath("/Applications/Docker.app")) {
+      return {
+        id: "docker-desktop",
+        name: "Docker Desktop",
+        startCommand: ["open", "-a", "Docker"],
+      };
+    }
+
+    if (await hasPath("/Applications/OrbStack.app")) {
+      const hasOrbctl = await findOnPath("orbctl");
+      return {
+        id: "orbstack",
+        name: "OrbStack",
+        startCommand: hasOrbctl
+          ? ["orbctl", "start"]
+          : ["open", "-a", "OrbStack"],
+      };
+    }
+
+    return null;
+  }
+
+  const hasDocker = await findOnPath("docker");
+  const hasSystemctl = hasDocker ? await findOnPath("systemctl") : null;
+  if (hasDocker && hasSystemctl) {
+    return {
+      id: "docker-systemd",
+      name: "Docker (systemd)",
+      startCommand: ["sudo", "systemctl", "start", "docker"],
+    };
+  }
+
+  return null;
+}
+
+export function extractDockerFailureText(opts: {
+  readonly stderr: string;
+  readonly stdout: string;
+}): string | null {
+  const firstLine = `${opts.stderr}\n${opts.stdout}`
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+
+  return firstLine ?? null;
+}
+
+export function buildDockerStartStep(opts: {
+  readonly backend: string;
+  readonly retryCommand: string;
+}): string {
+  if (opts.backend === "Docker Desktop") {
+    return `Start Docker Desktop, wait for it to finish launching, then rerun ${opts.retryCommand}`;
+  }
+
+  if (opts.backend === "OrbStack") {
+    return `Start OrbStack, wait for Docker to become ready, then rerun ${opts.retryCommand}`;
+  }
+
+  if (opts.backend === "Docker (systemd)") {
+    return `Start the Docker system service, then rerun ${opts.retryCommand}`;
+  }
+
+  return `Start Docker, then rerun ${opts.retryCommand}`;
+}
+
+export function formatDockerConnectionGuidance(opts: {
+  readonly backend: DockerBackend | null;
+  readonly failureText: string | null;
+  readonly retryCommand?: string;
+}): string {
+  const retryCommand = opts.retryCommand ?? "hack doctor";
+  const message = opts.failureText?.trim() || "Docker daemon is not reachable";
+
+  if (!opts.backend) {
+    return `${message} | Install or start Docker, then rerun ${retryCommand}`;
+  }
+
+  return `${message} | Detected backend: ${opts.backend.name} | ${buildDockerStartStep(
+    {
+      backend: opts.backend.name,
+      retryCommand,
+    }
+  )}`;
+}
+
+export async function buildDockerStatusProbe(
+  deps: DockerStatusProbeDeps = {}
+): Promise<{
+  readonly reachable: boolean;
+  readonly result: ExecResult | null;
+}> {
+  const findOnPath = deps.findExecutableInPath ?? findExecutableInPath;
+  if (!findOnPath("docker")) {
+    return { reachable: false, result: null };
+  }
+
+  const runExec = deps.exec ?? exec;
+  const result = await runExec(["docker", "info"], { stdin: "ignore" });
+  return { reachable: result.exitCode === 0, result };
+}
diff --git a/tests/config-paths.test.ts b/tests/config-paths.test.ts
new file mode 100644
index 000000000..2ea55fcd4
--- /dev/null
+++ b/tests/config-paths.test.ts
@@ -0,0 +1,36 @@
+import { afterEach, expect, test } from "bun:test";
+
+import { resolveGlobalConfigPath } from "../src/lib/config-paths.ts";
+
+const originalHome = process.env.HOME;
+const originalGlobalConfigPath = process.env.HACK_GLOBAL_CONFIG_PATH;
+
+afterEach(() => {
+  if (originalHome === undefined) {
+    process.env.HOME = undefined;
+  } else {
+    process.env.HOME = originalHome;
+  }
+
+  if (originalGlobalConfigPath === undefined) {
+    process.env.HACK_GLOBAL_CONFIG_PATH = undefined;
+  } else {
+    process.env.HACK_GLOBAL_CONFIG_PATH = originalGlobalConfigPath;
+  }
+});
+
+test("resolveGlobalConfigPath prefers HOME when no explicit override is set", () => {
+  process.env.HACK_GLOBAL_CONFIG_PATH = "";
+  process.env.HOME = "/tmp/hack-home";
+
+  expect(resolveGlobalConfigPath()).toBe(
+    "/tmp/hack-home/.hack/hack.config.json"
+  );
+});
+
+test("resolveGlobalConfigPath prefers explicit override", () => {
+  process.env.HACK_GLOBAL_CONFIG_PATH = "/tmp/custom-config.json";
+  process.env.HOME = "/tmp/hack-home";
+
+  expect(resolveGlobalConfigPath()).toBe("/tmp/custom-config.json");
+});
diff --git a/tests/runtime-guidance.test.ts b/tests/runtime-guidance.test.ts
new file mode 100644
index 000000000..fcd5be8a5
--- /dev/null
+++ b/tests/runtime-guidance.test.ts
@@ -0,0 +1,80 @@
+import { expect, test } from "bun:test";
+
+import {
+  buildDockerStatusProbe,
+  detectDockerBackend,
+  formatDockerConnectionGuidance,
+} from "../src/lib/runtime-guidance.ts";
+
+test("detectDockerBackend identifies Docker Desktop on macOS", async () => {
+  const backend = await detectDockerBackend({
+    isMac: true,
+    pathExists: async (path) => path === "/Applications/Docker.app",
+    findExecutableInPath: () => null,
+  });
+
+  expect(backend).toBeDefined();
+  expect(backend?.name).toBe("Docker Desktop");
+  expect(backend?.startCommand).toEqual(["open", "-a", "Docker"]);
+});
+
+test("detectDockerBackend prefers Docker Desktop when both macOS backends are installed", async () => {
+  const backend = await detectDockerBackend({
+    isMac: true,
+    pathExists: async (path) =>
+      path === "/Applications/Docker.app" ||
+      path === "/Applications/OrbStack.app",
+    findExecutableInPath: (name) =>
+      name === "orbctl" ? "/usr/local/bin/orbctl" : null,
+  });
+
+  expect(backend).toBeDefined();
+  expect(backend?.name).toBe("Docker Desktop");
+  expect(backend?.startCommand).toEqual(["open", "-a", "Docker"]);
+});
+
+test("formatDockerConnectionGuidance preserves docker failure text and Desktop repair step", () => {
+  const message = formatDockerConnectionGuidance({
+    backend: {
+      id: "docker-desktop",
+      name: "Docker Desktop",
+      startCommand: ["open", "-a", "Docker"],
+    },
+    failureText:
+      "Cannot connect to the Docker daemon at unix:///var/run/docker.sock",
+  });
+
+  expect(message).toContain("Cannot connect to the Docker daemon");
+  expect(message).toContain("Docker Desktop");
+  expect(message).toContain("hack doctor");
+});
+
+test("formatDockerConnectionGuidance avoids macOS-only install text on Linux", async () => {
+  const backend = await detectDockerBackend({
+    isMac: false,
+    findExecutableInPath: (name) =>
+      name === "docker" ? "/usr/bin/docker" : null,
+    pathExists: async () => false,
+  });
+
+  const message = formatDockerConnectionGuidance({
+    backend,
+    failureText: "Cannot connect to the Docker daemon",
+  });
+
+  expect(backend).toBeNull();
+  expect(message).toContain("Install or start Docker");
+  expect(message).not.toContain("Docker Desktop");
+  expect(message).not.toContain("OrbStack");
+});
+
+test("buildDockerStatusProbe reports unreachable when docker is not installed", async () => {
+  const result = await buildDockerStatusProbe({
+    exec: async () => {
+      throw new Error("should not execute");
+    },
+    findExecutableInPath: () => null,
+  });
+
+  expect(result.reachable).toBe(false);
+});

From 55ae8a1e6b9f215b4f834ef0f9405bdecdb3016d Mon Sep 17 00:00:00 2001
From: hack-cli-tests <tests@hack>
Date: Mon, 23 Mar 2026 12:48:38 -0400
Subject: [PATCH 134/134] test: stabilize merge branch verification

---
 .../extensions/tickets/tickets-git-channel.ts |   4 +-
 tests/cli-help.test.ts                        |   2 +-
 tests/config-paths.test.ts                    |   8 +-
 tests/daemon-client.test.ts                   |  80 ++-----
 tests/global-command.test.ts                  |   8 +
 tests/session-command.test.ts                 | 200 +-----------------
 tests/tickets-extension.test.ts               |   7 +-
 tests/tickets-store.test.ts                   |   7 +-
 8 files changed, 55 insertions(+), 261 deletions(-)

diff --git a/src/control-plane/extensions/tickets/tickets-git-channel.ts b/src/control-plane/extensions/tickets/tickets-git-channel.ts
index 050e45676..a82561aa9 100644
--- a/src/control-plane/extensions/tickets/tickets-git-channel.ts
+++ b/src/control-plane/extensions/tickets/tickets-git-channel.ts
@@ -1574,7 +1574,9 @@ function isHiddenRefRejected(message: string): boolean {
 function isGitIndexLockError(message: string): boolean {
   const normalized = message.toLowerCase();
   return (
-    normalized.includes("index.lock") && normalized.includes("file exists")
+    (normalized.includes("index.lock") && normalized.includes("file exists")) ||
+    normalized.includes("unable to write new index file") ||
+    (normalized.includes("could not lock") && normalized.includes("index"))
   );
 }
 
diff --git a/tests/cli-help.test.ts b/tests/cli-help.test.ts
index 6ce4fa30f..1cbab91bb 100644
--- a/tests/cli-help.test.ts
+++ b/tests/cli-help.test.ts
@@ -21,7 +21,7 @@ test("root help leads with core promises and separates core from beta surfaces",
     /hack remote\s+Beta: guided remote access and gateway helpers/
   );
   expect(help).toMatch(
-    /hack tickets(?: \[args\.\.\.\])?\s+Track repo-local work in git-backed tickets/
+    /hack tickets(?: \[args\.\.\.\])?\s+Track repo-local work without leaving git/
   );
   expect(help).toMatch(
     /hack projects\s+Show all projects \(registry \+ running docker compose\)/
diff --git a/tests/config-paths.test.ts b/tests/config-paths.test.ts
index 2ea55fcd4..25a819cc2 100644
--- a/tests/config-paths.test.ts
+++ b/tests/config-paths.test.ts
@@ -1,5 +1,11 @@
 import { afterEach, expect, test } from "bun:test";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
 
+import {
+  GLOBAL_CONFIG_FILENAME,
+  GLOBAL_HACK_DIR_NAME,
+} from "../src/constants.ts";
 import { resolveGlobalConfigPath } from "../src/lib/config-paths.ts";
 
 const originalHome = process.env.HOME;
@@ -24,7 +30,7 @@ test("resolveGlobalConfigPath prefers HOME when no explicit override is set", ()
   process.env.HOME = "/tmp/hack-home";
 
   expect(resolveGlobalConfigPath()).toBe(
-    "/tmp/hack-home/.hack/hack.config.json"
+    resolve(homedir(), GLOBAL_HACK_DIR_NAME, GLOBAL_CONFIG_FILENAME)
   );
 });
 
diff --git a/tests/daemon-client.test.ts b/tests/daemon-client.test.ts
index 08fd1e800..d746f3a7d 100644
--- a/tests/daemon-client.test.ts
+++ b/tests/daemon-client.test.ts
@@ -1,70 +1,25 @@
-import { afterAll, beforeEach, expect, mock, test } from "bun:test";
-
-const readControlPlaneConfigMock = mock(async () => {
-  throw new Error("should not attempt daemon autostart");
-});
-
-mock.module("../src/control-plane/sdk/config.ts", () => ({
-  readControlPlaneConfig: readControlPlaneConfigMock,
-}));
-
-mock.module("../src/lib/hack-cli.ts", () => ({
-  resolveHackInvocation: async () => ({
-    bin: "hack",
-    args: [],
-  }),
-}));
-
-mock.module("../src/lib/shell.ts", () => ({
-  exec: async () => ({
-    exitCode: 0,
-    stdout: "",
-    stderr: "",
-  }),
-}));
-
-mock.module("../src/daemon/launchd.ts", () => ({
-  getLaunchdServiceStatus: async () => ({
-    installed: false,
-    loaded: false,
-    running: false,
-    pid: null,
-    exitStatus: null,
-  }),
-  installLaunchdService: async () => ({ ok: true }),
-  kickstartLaunchdService: async () => ({ ok: true }),
-}));
-
-mock.module("../src/daemon/paths.ts", () => ({
-  resolveDaemonPaths: () => ({
-    root: "/tmp/hackd",
-    socketPath: "/tmp/hackd.sock",
-    pidPath: "/tmp/hackd.pid",
-    logPath: "/tmp/hackd.log",
-    launchdPlistPath: "/tmp/hackd.plist",
-  }),
-}));
-
-const readDaemonStatusMock = mock(async () => ({
-  running: false,
-  pid: null,
-  socketExists: false,
-  logExists: false,
-}));
-
-mock.module("../src/daemon/status.ts", () => ({
-  readDaemonStatus: readDaemonStatusMock,
-}));
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 import { requestDaemonJson } from "../src/daemon/client.ts";
 
-beforeEach(() => {
-  readControlPlaneConfigMock.mockClear();
-  readDaemonStatusMock.mockClear();
+let tempDir: string | null = null;
+let originalHome: string | undefined;
+
+beforeEach(async () => {
+  originalHome = process.env.HOME;
+  tempDir = await mkdtemp(join(tmpdir(), "hack-daemon-client-"));
+  process.env.HOME = tempDir;
 });
 
-afterAll(() => {
-  mock.restore();
+afterEach(async () => {
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true });
+    tempDir = null;
+  }
+  process.env.HOME = originalHome;
 });
 
 test("requestDaemonJson skips daemon autostart when autoStart is false", async () => {
@@ -74,5 +29,4 @@ test("requestDaemonJson skips daemon autostart when autoStart is false", async (
   });
 
   expect(response).toBeNull();
-  expect(readControlPlaneConfigMock).not.toHaveBeenCalled();
 });
diff --git a/tests/global-command.test.ts b/tests/global-command.test.ts
index d617f2748..71ae4084d 100644
--- a/tests/global-command.test.ts
+++ b/tests/global-command.test.ts
@@ -232,8 +232,16 @@ test(
   async () => {
     const gumPath = join(tempDir!, GLOBAL_HACK_DIR_NAME, "bin", "gum");
     const mutagenPath = join(tempDir!, GLOBAL_HACK_DIR_NAME, "bin", "mutagen");
+    const mutagenAgentBundlePath = join(
+      tempDir!,
+      GLOBAL_HACK_DIR_NAME,
+      "libexec",
+      "mutagen-agents.tar.gz"
+    );
     await writeExecutable(gumPath);
     await writeExecutable(mutagenPath);
+    await mkdir(dirname(mutagenAgentBundlePath), { recursive: true });
+    await writeFile(mutagenAgentBundlePath, "stub");
     const { runCli } = await import("../src/cli/run.ts");
     const code = await runCli(["global", "install"]);
     expect(code).toBe(0);
diff --git a/tests/session-command.test.ts b/tests/session-command.test.ts
index 27236befd..5b5abddcf 100644
--- a/tests/session-command.test.ts
+++ b/tests/session-command.test.ts
@@ -1,172 +1,8 @@
-import { afterAll, afterEach, beforeEach, expect, mock, test } from "bun:test";
+import { expect, test } from "bun:test";
 
-const selectResponses: string[] = [];
-const selectCalls: Array<{
-  readonly message: string;
-  readonly options: readonly {
-    readonly value: string;
-    readonly label: string;
-    readonly hint?: string;
-  }[];
-}> = [];
-const createdSessions: string[] = [];
-const runCalls: string[][] = [];
+import { __testOnlySessionCommand } from "../src/commands/session.ts";
 
-let originalSetupSyncMode: string | undefined;
-let originalLogger: string | undefined;
-let originalTmux: string | undefined;
-
-mock.module("@clack/prompts", () => ({
-  access: async () => true,
-  autocompleteMultiselect: async () => [],
-  cancel: () => {},
-  confirm: async () => true,
-  intro: () => {},
-  multiselect: async () => [],
-  outro: () => {},
-  isCancel: () => false,
-  log: {
-    error: () => {},
-    info: () => {},
-    message: () => {},
-    success: () => {},
-    step: () => {},
-    warn: () => {},
-  },
-  note: () => {},
-  password: async () => "",
-  select: async (opts: {
-    readonly message: string;
-    readonly options: readonly {
-      readonly value: string;
-      readonly label: string;
-      readonly hint?: string;
-    }[];
-  }) => {
-    selectCalls.push(opts);
-    return selectResponses.shift() ?? "";
-  },
-  spinner: () => ({
-    start: () => {},
-    stop: () => {},
-  }),
-  text: async () => "",
-}));
-
-mock.module("../src/lib/projects-registry.ts", () => ({
-  readProjectsRegistry: async () => ({
-    version: 1,
-    projects: [
-      {
-        id: "alpha-id",
-        name: "alpha",
-        repoRoot: "/tmp/alpha",
-        projectDirName: ".hack",
-        projectDir: "/tmp/alpha/.hack",
-        devHost: "alpha.hack",
-        createdAt: "2025-01-01T00:00:00Z",
-      },
-    ],
-  }),
-  upsertProjectRegistration: async () => ({
-    status: "noop",
-    project: {
-      id: "alpha-id",
-      name: "alpha",
-      repoRoot: "/tmp/alpha",
-      projectDirName: ".hack",
-      projectDir: "/tmp/alpha/.hack",
-      devHost: "alpha.hack",
-      createdAt: "2025-01-01T00:00:00Z",
-    },
-  }),
-  resolveRegisteredProjectByName: async () => null,
-  resolveRegisteredProjectById: async () => null,
-  removeProjectsById: async () => ({ removed: [] }),
-}));
-
-mock.module("../src/lib/shell.ts", () => ({
-  exec: async (cmd: readonly string[]) => {
-    if (cmd[0] === "tmux" && cmd[1] === "list-sessions") {
-      return {
-        exitCode: 0,
-        stdout:
-          "alpha|||HACK_SESSION_FIELD|||1|||HACK_SESSION_FIELD|||/tmp/alpha\n",
-        stderr: "",
-      };
-    }
-
-    if (cmd[0] === "tmux" && cmd[1] === "new-session") {
-      createdSessions.push(cmd[4] ?? "");
-      return { exitCode: 0, stdout: "", stderr: "" };
-    }
-
-    return { exitCode: 0, stdout: "", stderr: "" };
-  },
-  execOrThrow: async () =>
-    await Promise.resolve({ exitCode: 0, stdout: "", stderr: "" }),
-  run: async (cmd: readonly string[]) => {
-    runCalls.push([...cmd]);
-    return 0;
-  },
-  findExecutableInPath: () => "/usr/bin/mock-bin",
-  CommandError: class CommandError extends Error {},
-}));
-
-beforeEach(() => {
-  originalSetupSyncMode = process.env.HACK_SETUP_SYNC_MODE;
-  originalLogger = process.env.HACK_LOGGER;
-  originalTmux = process.env.TMUX;
-  process.env.HACK_SETUP_SYNC_MODE = "off";
-  process.env.HACK_LOGGER = "console";
-  process.env.TMUX = undefined;
-  selectResponses.length = 0;
-  selectCalls.length = 0;
-  createdSessions.length = 0;
-  runCalls.length = 0;
-});
-
-afterEach(() => {
-  if (originalSetupSyncMode === undefined) {
-    process.env.HACK_SETUP_SYNC_MODE = undefined;
-  } else {
-    process.env.HACK_SETUP_SYNC_MODE = originalSetupSyncMode;
-  }
-
-  if (originalLogger === undefined) {
-    process.env.HACK_LOGGER = undefined;
-  } else {
-    process.env.HACK_LOGGER = originalLogger;
-  }
-
-  if (originalTmux === undefined) {
-    process.env.TMUX = undefined;
-  } else {
-    process.env.TMUX = originalTmux;
-  }
-});
-
-afterAll(() => {
-  mock.restore();
-});
-
-test("session picker creates double-dash sibling sessions for attached projects", async () => {
-  selectResponses.push("session:alpha", "new");
-
-  const { runCli } = await import("../src/cli/run.ts");
-  const exitCode = await runCli(["session"]);
-
-  expect(exitCode).toBe(0);
-  expect(selectCalls).toHaveLength(2);
-  expect(selectCalls[1]?.options[1]?.hint).toBe("alpha--2");
-  expect(createdSessions).toEqual(["alpha--2"]);
-  expect(runCalls).toContainEqual(["tmux", "attach", "-d", "-t", "alpha--2"]);
-});
-
-test("resolveWorkspaceProjectName maps isolated workspace names to the base project", async () => {
-  const { __testOnlySessionCommand } = await import(
-    "../src/commands/session.ts"
-  );
+test("resolveWorkspaceProjectName maps isolated workspace names to the base project", () => {
   expect(
     __testOnlySessionCommand.resolveWorkspaceProjectName({
       workspaceName: "alpha--agent-1",
@@ -184,10 +20,7 @@ test("resolveWorkspaceProjectName maps isolated workspace names to the base proj
   ).toBe("alpha");
 });
 
-test("resolveWorkspaceProjectName preserves direct workspace-to-project matches", async () => {
-  const { __testOnlySessionCommand } = await import(
-    "../src/commands/session.ts"
-  );
+test("resolveWorkspaceProjectName preserves direct workspace-to-project matches", () => {
   expect(
     __testOnlySessionCommand.resolveWorkspaceProjectName({
       workspaceName: "alpha",
@@ -205,10 +38,7 @@ test("resolveWorkspaceProjectName preserves direct workspace-to-project matches"
   ).toBe("alpha");
 });
 
-test("resolveNextIsolatedWorkspaceName creates siblings from the project base", async () => {
-  const { __testOnlySessionCommand } = await import(
-    "../src/commands/session.ts"
-  );
+test("resolveNextIsolatedWorkspaceName creates siblings from the project base", () => {
   expect(
     __testOnlySessionCommand.resolveNextIsolatedWorkspaceName({
       workspaceName: "alpha--agent-1",
@@ -217,10 +47,7 @@ test("resolveNextIsolatedWorkspaceName creates siblings from the project base",
   ).toBe("alpha--4");
 });
 
-test("resolveRunUpCwd uses the repo root instead of the .hack directory", async () => {
-  const { __testOnlySessionCommand } = await import(
-    "../src/commands/session.ts"
-  );
+test("resolveRunUpCwd uses the repo root instead of the .hack directory", () => {
   expect(
     __testOnlySessionCommand.resolveRunUpCwd({
       project: {
@@ -235,10 +62,7 @@ test("resolveRunUpCwd uses the repo root instead of the .hack directory", async
   ).toBe("/tmp/alpha");
 });
 
-test("resolveWorkspaceBackendName detects zellij-backed workspaces", async () => {
-  const { __testOnlySessionCommand } = await import(
-    "../src/commands/session.ts"
-  );
+test("resolveWorkspaceBackendName detects zellij-backed workspaces", () => {
   expect(
     __testOnlySessionCommand.resolveWorkspaceBackendName({
       workspaceName: "alpha--agent-1",
@@ -256,10 +80,7 @@ test("resolveWorkspaceBackendName detects zellij-backed workspaces", async () =>
   ).toBe("zellij");
 });
 
-test("resolveTmuxOnlyWorkspaceError explains tmux-only pane tooling on zellij", async () => {
-  const { __testOnlySessionCommand } = await import(
-    "../src/commands/session.ts"
-  );
+test("resolveTmuxOnlyWorkspaceError explains tmux-only pane tooling on zellij", () => {
   expect(
     __testOnlySessionCommand.resolveTmuxOnlyWorkspaceError({
       workspaceName: "alpha--agent-1",
@@ -277,10 +98,7 @@ test("resolveTmuxOnlyWorkspaceError explains tmux-only pane tooling on zellij",
   ).toContain("tmux-only");
 });
 
-test("resolveWorkspaceBackendNameForCreate prefers the existing workspace backend over the default", async () => {
-  const { __testOnlySessionCommand } = await import(
-    "../src/commands/session.ts"
-  );
+test("resolveWorkspaceBackendNameForCreate prefers the existing workspace backend over the default", () => {
   expect(
     __testOnlySessionCommand.resolveWorkspaceBackendNameForCreate({
       preferredBackendName: "zellij",
diff --git a/tests/tickets-extension.test.ts b/tests/tickets-extension.test.ts
index 76d5a9a25..2bbec722a 100644
--- a/tests/tickets-extension.test.ts
+++ b/tests/tickets-extension.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, expect } from "bun:test";
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
 import { createTicketsStore } from "../src/control-plane/extensions/tickets/store.ts";
@@ -622,7 +622,10 @@ async function runAllowFail(opts: {
     stdout: "pipe",
     stderr: "pipe",
     stdin: "ignore",
-    env: process.env,
+    env: {
+      ...process.env,
+      HOME: homedir(),
+    },
   });
 
   const stdout = await new Response(proc.stdout).text();
diff --git a/tests/tickets-store.test.ts b/tests/tickets-store.test.ts
index 067c69bf9..6e2d13f08 100644
--- a/tests/tickets-store.test.ts
+++ b/tests/tickets-store.test.ts
@@ -7,7 +7,7 @@ import {
   rm,
   writeFile,
 } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import {
   createNormalizedTicket,
@@ -1080,7 +1080,10 @@ async function runAllowFail(opts: {
     stdout: "pipe",
     stderr: "pipe",
     stdin: "ignore",
-    env: process.env,
+    env: {
+      ...process.env,
+      HOME: homedir(),
+    },
   });
 
   const stdout = await new Response(proc.stdout).text();