Worktree-first development + agent experience overhaul

.claude/settings.json

@@ -16,7 +16,10 @@
     "hack": {
       "type": "stdio",
       "command": "hack",
-      "args": ["mcp", "serve"]
+      "args": [
+        "mcp",
+        "serve"
+      ]
     }
   }
 }

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

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

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

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

.cursor/mcp.json

@@ -2,7 +2,10 @@
   "mcpServers": {
     "hack": {
       "command": "hack",
-      "args": ["mcp", "serve"]
+      "args": [
+        "mcp",
+        "serve"
+      ]
     }
   }
 }

.cursor/rules/hack.mdc

@@ -2,61 +2,86 @@
 # Auto-generated by 'hack setup cursor' - do not remove these markers
 # BEGIN HACK INTEGRATION
 
-This project uses `hack` for local runtime orchestration (compose + DNS/TLS + logs + sessions).
+Hack v3 is local-first. This project uses `hack` for local runtime orchestration (compose + DNS/TLS + logs + sessions).
 Prefer `hack` when shell access is available. Use MCP only when shell access is unavailable.
 
-## Core Rules
-- Use `hack` CLI for start/stop/open/logs/run/session/tickets workflows.
-- Do not run raw `docker compose up/down/logs` for normal project operations.
-- Treat `.hack/.internal` and `.hack/.branch` as hack-managed artifacts; avoid manual edits there.
-- Use lifecycle/startup config in `.hack/hack.config.json` instead of ad-hoc host process tabs.
-- Use `--json` for machine-readable output when available.
-- If state is inconsistent, run `hack doctor` then `hack doctor --fix` before manual repairs.
-- For hostname routing, only services with Caddy labels on `hack-dev` are exposed (not every compose service).
-- Use `.hack.gy` alias hosts for OAuth-style callback validation when `.hack` is rejected by providers.
-
-## Managed Files
-- Source-of-truth: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.json`.
-- Generated/local-only: `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`, `.hack/.internal/lifecycle/*`.
-- Manage dynamic host mappings with `hack internal extra-hosts ...` (not manual file edits).
-
-## Quick Reference
-```bash
-hack init
-hack up --detach
-hack up -d
-hack open --json
-hack open <sub>
-hack logs --pretty
-hack logs <service>
-hack logs --json --no-follow
-hack logs --loki --since 2h --pretty
-hack run <service> <cmd...>
-hack restart
-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>
-hack up --branch <name> --detach
-hack open --branch <name>
-hack logs --branch <name>
-hack down --branch <name>
-hack setup sync --all-scopes
-```
-
-## MCP (optional)
-- Install only for no-shell clients: `hack setup mcp`
-- Project-level hack commands auto-check integration drift and attempt auto-sync by default.
-- Use `HACK_SETUP_SYNC_MODE=warn` (warn only) or `HACK_SETUP_SYNC_MODE=off` (disable).
-- Refresh generated MCP/docs/instructions: `hack setup sync --all-scopes`
+## Product boundary
+
+- Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
+- Removed surfaces: hosted auth/account/org/team flows, web dashboard, built-in GitHub workflows, and built-in Linear sync.
+- Experimental and unsupported: remote/gateway/node/dispatch commands. They are hidden from default help (list with `hack help --all`) and warn on use; do not use them unless explicitly requested.
+
+## Operating rules
+
+- Prefer `hack` over raw `docker` / `docker compose` for project workflows.
+- Do not start/stop services from Docker Desktop UI for `hack`-managed projects.
+- Treat `.hack/.internal` and `.hack/.branch` as hack-managed artifacts; do not hand-edit generated files there.
+- Use `--json` for machine-readable output when available; `hack up/down/restart/doctor --json` emit an `{ok, data | error: {code, message}}` envelope with stable E_* error codes.
+- Scripted/agent runs: pass `--no-interactive` (or set `HACK_NO_INTERACTIVE=1`) so commands never block on prompts — they apply documented defaults or fail fast with E_INTERACTIVE_REQUIRED.
+- Use MCP only when shell access is unavailable.
+- If runtime state looks wrong, run `hack doctor`, then `hack doctor --fix` before manual repair.
+
+## Project files (managed vs generated)
+
+- Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
+- Worktree-local env override files: `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml`.
+- Local-only files: `.hack.secret.key`, optional `.hack/.env` compatibility output, `.hack/.env.state.json`, and `.hack/.internal/` (runtime/local machine state; keep gitignored).
+- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
+- Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
+- Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
+- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
+
+## Linked git worktrees
+
+- Secret key inherits from the primary checkout automatically through the shared git common dir; set `HACK_ENV_SECRET_KEY` for CI or detached environments.
+- `hack up` in a linked worktree defaults to a branch instance named after the worktree's git branch; opt out with config `worktree.auto_branch=false` or an explicit `--branch`.
+- `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
+
+## Standard workflow
+
+- If `.hack/` is missing: `hack init`
+- Start services: `hack up --detach` (or `hack up -d`)
+- Check status: `hack ps` or `hack status`
+- Open app URL: `hack open --json`
+- Restart: `hack restart`
+- Stop services: `hack down`
+
+## Running things (decision guide)
+
+- One-off command in a fresh service container (deps started as needed): `hack run <service> <cmd...>`.
+- Command inside an already-running service container: `hack exec <service> -- <cmd...>`.
+- Host script that needs hack-stored env: `hack host exec --env <overlay> --scope <service> -- <cmd...>` — this is THE way to run repo scripts; never read .env files directly.
+- Interactive host shell with injected env: `hack host shell --env <overlay> --scope <service>`.
+- Call a service over HTTP (from the host or between containers): use its Caddy hostname `https://<sub>.<dev_host>`; discover routable URLs with `hack open --json`.
+
+## Lifecycle + startup
+
+- Put host setup in `.hack/hack.config.json` under `startup`/`lifecycle` (not ad-hoc terminal tabs).
+- Use `lifecycle.up.before` for pre-start hooks and `lifecycle.processes` for long-running host tasks.
+- For fixed-port host helpers such as SSM tunnels or local proxies, set `singleton.ports` and usually `onConflict: "adopt"` so Hack reuses a healthy existing listener instead of starting duplicate tunnel stacks.
+- `singleton` is a listener guard, not process ownership transfer; adopted external processes are left running on `hack down`.
+- Inspect lifecycle status via `hack projects --details` and stream via `hack logs <service-or-process>`.
+
+## Host-side env helpers
+
+- One-off host command with injected env: `hack host exec --env qa --scope api -- bun db:migrate`
+- Host commands default to a host-local env view; use `--target compose` when you explicitly want container-oriented addresses.
+- `--scope` selects which env scope to inject; it does not move execution into that service container.
+- Interactive host shell with injected env: `hack host shell --env qa --scope api`
+- Run inside an already-running service container: `hack exec api -- bun test`
+
+## Agent integration maintenance
+
+- Project-level hack commands auto-check integration drift and attempt auto-sync (docs/skills/MCP).
+- Set `HACK_SETUP_SYNC_MODE=warn` to only warn, or `HACK_SETUP_SYNC_MODE=off` to disable.
+- Refresh project + user integrations: `hack setup sync --all-scopes`
+- Audit integration state only: `hack setup sync --all-scopes --check`
+- Remove generated integration artifacts: `hack setup sync --all-scopes --remove`
+- After upgrading CLI: `hack update` then `hack setup sync --all-scopes`
+- When changing hack itself: interface or behavior changes must update docs/ in the same change (regenerate the CLI reference with `bun run docs:cli-reference`).
+
+## Optional extensions
+
+- A local git-backed tickets extension exists (`hack tickets`) — only use it when the project explicitly uses it.
 
 # END HACK INTEGRATION

.hack/hack.config.json

@@ -5,13 +5,13 @@
   "controlPlane": {
     "extensions": {
       "dance.hack.github": {
-        "enabled": true
+        "enabled": false
       },
       "dance.hack.tickets": {
-        "enabled": true
+        "enabled": false
       },
       "dance.hack.linear": {
-        "enabled": true
+        "enabled": false
       }
     },
     "gateway": {