@posthog/wizard 2.80.0 → 2.81.0

package/README.md

@@ -34,7 +34,7 @@ The wizard uses **AI models from Anthropic or OpenAI**, routed through PostHog's
 - **AI opt-in**: for existing organizations in interactive runs, the wizard checks `is_ai_data_processing_approved` and waits for approval before agent work. CI and signup runs bypass this interactive gate.
 - **Prefer your own AI?** The wizard's integration knowledge ships as a context-mill skill you can download and run inside your own agent.
 
-The wizard's "Privacy & data usage" menu (intro screen) and the `[I]` shortcut on the auth screen surface the same information in-terminal.
+The wizard's "Privacy & data" menu (intro screen) and the `[I]` shortcut on the auth screen surface the same information in-terminal.
 
 ## MCP Commands
 
@@ -47,8 +47,15 @@ npx @posthog/wizard@latest mcp add
 
 # Remove PostHog MCP server from supported clients
 npx @posthog/wizard@latest mcp remove
+
+# Try the PostHog MCP with your agent, no install needed
+npx @posthog/wizard@latest mcp tutorial
 ```
 
+These, `slack`, `doctor`, `provision`, `cli add` and `skill list` are tools:
+commands that do their job without an agent run. See
+[src/tools](src/tools/README.md).
+
 ## Wizard programs
 
 The wizard's commands are grouped into **programs** — self-contained agentic jobs that install, audit, or wire up a specific piece of PostHog. They're powered by skills from the [context mill](https://github.com/PostHog/context-mill).
@@ -61,7 +68,7 @@ Running the wizard with no arguments installs PostHog into your project. It dete
 npx @posthog/wizard@latest
 ```
 
-Powered by the `posthog-integration` program. Most other programs below build on it (they declare `requires: ['posthog-integration']`) and will offer to run it first if PostHog isn't already set up.
+Powered by the `posthog-integration` program. Most other programs below build on it and declare `requires: ['posthog-integration']`.
 
 ### Self-driving
 
@@ -76,16 +83,17 @@ If PostHog isn't already installed, the wizard runs the default integration firs
 ### Audit
 
 Audit an existing PostHog integration for correctness and best practices. The
-`audit` command is a **family**. With no subcommand it runs the **events**
-audit (the default); pass a subcommand to run a specific one:
+`audit` command is a **family**. With no subcommand, an interactive terminal
+runs the audit the skill menu marks as the default (today **all**); pass a
+subcommand to run a specific one:
 
 ```bash
-# Runs the events audit (the default) — no subcommand needed
+# Runs the default audit — no subcommand needed
 npx @posthog/wizard@latest audit
 
 # Or run a specific audit directly
-npx @posthog/wizard@latest audit events           # event capture quality + cost (default)
-npx @posthog/wizard@latest audit all              # comprehensive audit across every area
+npx @posthog/wizard@latest audit events           # event capture quality + cost
+npx @posthog/wizard@latest audit all              # comprehensive audit across every area (default)
 npx @posthog/wizard@latest audit autocapture      # autocapture setup + cost
 npx @posthog/wizard@latest audit feature-flags    # feature flag usage + cost
 npx @posthog/wizard@latest audit identify         # your $identify implementation
@@ -98,9 +106,9 @@ new audits appear without a wizard release (`web-analytics` is wizard-native).
 
 > **`audit <subcommand>` chooses an audit area — it does not take a skill name.**
 > The audit subcommands above *are* context-mill skills promoted to commands (via
-> a `cli: role: command` block); [`wizard skill <skill-name>`](#run-a-single-skill)
+> a `cli: role: command` block); [`wizard skill <skill-name>`](#run-skill)
 > runs a skill that hasn't been promoted. Same machinery, two surfaces.
-> (`wizard audit --help` still labels the positional `[skill]` — read it as "pick
+> (`wizard audit --help` labels the positional `[skill]` — read it as "pick
 > a subcommand.")
 
 ### Revenue Analytics
@@ -112,7 +120,7 @@ npx @posthog/wizard@latest revenue-analytics
 ```
 
 Requires PostHog and Stripe SDKs already installed. Supports `--ci` with the
-same flags as the main wizard. (Renamed from `revenue` in the CLI overhaul.)
+same flags as the main wizard.
 
 ### Data Warehouse
 
@@ -166,16 +174,16 @@ route review to their owning team instead.
 | `src/programs/self-driving/` | `@PostHog/team-self-driving` |
 | `src/programs/warehouse-source/` | `@PostHog/team-warehouse-sources` |
 | `src/programs/web-analytics-doctor/` | `@PostHog/team-web-analytics` |
-| `src/ui/tui/decks/error-tracking-upload-source-maps/` | `@PostHog/team-error-tracking` |
-| `src/ui/tui/decks/revenue-analytics/` | `@PostHog/team-web-analytics` |
-| `src/ui/tui/decks/self-driving/` | `@PostHog/team-self-driving` |
-| `src/ui/tui/decks/warehouse-source/` | `@PostHog/team-warehouse-sources` |
+| `src/tui/programs/error-tracking-upload-source-maps/` | `@PostHog/team-error-tracking` |
+| `src/tui/programs/revenue-analytics/` | `@PostHog/team-web-analytics` |
+| `src/tui/programs/self-driving/` | `@PostHog/team-self-driving` |
+| `src/tui/programs/warehouse-source/` | `@PostHog/team-warehouse-sources` |
 
 Ownership is by directory. Programs not listed above
-(`agent-skill`, `audit`, `events-audit`, `mcp`, `migration`, `posthog-doctor`,
-`shared`, `slack`) fall through the default and are owned by
-`team-wizard-docs`. Today CODEOWNERS only auto-requests review — approval is
-not a merge gate.
+(`agent-skill`, `audit`, `error-tracking`, `migration`), the shared program code
+and the tools (`src/tools`, `src/tui/tools`) fall through the default and are
+owned by `team-wizard-docs`. Today CODEOWNERS only auto-requests review —
+approval is not a merge gate.
 
 ## Headless signup + install (agents / CI)
 
@@ -185,7 +193,9 @@ not a merge gate.
 For a fully non-interactive first-run (no existing PostHog account, no TTY,
 no browser), combine `--ci --signup --email`. The wizard provisions a new
 account, uses the returned personal API key to run the normal CI install,
-and wires PostHog into the project at `--install-dir`:
+and wires PostHog into the project at `--install-dir`. Like every `--ci` run, it
+needs the gateway token file from [local
+credentials](docs/local-dev.md#credentials-for-local-ci-and-headless-runs):
 
 ```bash
 npx @posthog/wizard@latest --ci --signup \
@@ -193,8 +203,7 @@ npx @posthog/wizard@latest --ci --signup \
   --install-dir .
 ```
 
-Optional flags: `--name "Your Name"`, `--region eu` (default `us`),
-`--integration nextjs` (else auto-detected).
+Optional flags: `--name "Your Name"`, `--region eu` (default `us`).
 
 ### Provision only
 
@@ -210,11 +219,12 @@ npx @posthog/wizard@latest provision --email user@example.com --region us
 npx @posthog/wizard@latest provision --email user@example.com --region eu --json
 ```
 
-Success prints the full `ProvisioningResult` (`projectApiKey`, `host`,
-`projectId`, `accountId`, `accessToken`, `refreshToken`, and
-`personalApiKey` if present). Failure exits 1; in `--json` mode the error
-is emitted to stderr as `{"error":"...","code":"..."}`, with `code` set to
-`email_exists` when the address is already registered.
+Success prints `projectApiKey`, `host`, `projectId`, `accountId`, `accessToken`,
+`refreshToken`, and `personalApiKey` if present. `--json` prints the full
+`ProvisioningResult`, which also has `expiresAt` and `oauthClientId`. Failure
+exits 1; in `--json` mode the error is emitted to stderr as
+`{"error":"...","code":"..."}`, with `code` set to `email_exists` when the
+address is already registered.
 
 > ⚠️ **Output contains live credentials.** Pipe it into a secrets store —
 > do not let it be captured by shared CI logs. Mask the step output or
@@ -231,7 +241,7 @@ The following CLI arguments are available:
 | `--debug`         | Enable verbose logging                                           | boolean | `false` |                                                      | `POSTHOG_WIZARD_DEBUG`         |
 | `--signup`        | Create a new PostHog account during setup                        | boolean | `false` |                                                      | `POSTHOG_WIZARD_SIGNUP`        |
 | `--install-dir`   | Directory to install PostHog in                                  | string  |         |                                                      | `POSTHOG_WIZARD_INSTALL_DIR`   |
-| `--ci`            | Enable CI mode for non-interactive execution                     | boolean | `false` |                                                      | `POSTHOG_WIZARD_CI`            |
+| `--ci`            | Enable CI mode for non-interactive execution (dev and test builds only) | boolean | `false` |                                                      | `POSTHOG_WIZARD_CI`            |
 | `--api-key`       | PostHog personal API key (phx_xxx) for authentication            | string  |         |                                                      | `POSTHOG_WIZARD_API_KEY`       |
 | `--no-telemetry`  | Disable wizard run-state telemetry                               | boolean | `false` |                                                      | `POSTHOG_WIZARD_NO_TELEMETRY`  |
 
@@ -241,8 +251,9 @@ The following CLI arguments are available:
 **CI mode is available only in development/test builds.** Published builds
 reject `--ci`; use an interactive terminal for `npx @posthog/wizard@latest`.
 
-Local CI runs require a PostHog personal API key **and a separate gateway
-token file**, plus the target project ID. See
+Local CI runs require a PostHog personal API key for MCP access **and a
+separate gateway token file** holding the gateway service key from 1Password,
+plus the target project ID. See
 [local credentials](docs/local-dev.md#credentials-for-local-ci-and-headless-runs)
 for setup and the CI secret names. With both secrets configured:
 
@@ -257,7 +268,6 @@ When running in CI mode (`--ci`):
 - Bypasses OAuth login flow (uses personal API key directly)
 - Auto-selects defaults for all prompts
 - Skips MCP server installation
-- Auto-continues on git warnings (uncommitted/untracked files)
 - Auto-consents to AI usage
 
 The CLI args override environment variables in CI mode.
@@ -279,8 +289,8 @@ health_issue:read wizard_session:read wizard_session:write wizard_run:write
 
 The source of truth is `WIZARD_OAUTH_SCOPES` in `src/shared/constants.ts`, which
 documents why each scope is needed — if this block drifts, trust the code.
-Some programs request more on top (`PROGRAM_SCOPE_ADDITIONS` in
-`src/programs/oauth/program-scopes.ts`); the default integration flow adds
+Some programs request more on top (`oauthScopeAdditions` on the program's
+config); the default integration flow adds
 `integration:read` and `external_data_source:read` /
 `external_data_source:write`.
 
@@ -294,12 +304,11 @@ for limits, shutdown behavior, migration compatibility, and deployment checks.
 ### OAuth app scope ceiling
 
 Both the interactive and cloud Wizard OAuth apps must allow `wizard_run:write`
-in every deployed region. Existing tokens need renewed authorization; refresh
-does not add the grant. Run synchronization needs no read scope.
+in every deployed region. Run synchronization needs no read scope.
 
 The wizard's OAuth app on the PostHog side caps the scopes its tokens may
 carry (`OAuthApplication.scopes`). Any scope requested in this repo (see
-`src/programs/oauth/program-scopes.ts`) must be grantable under that ceiling, or
+the programs' `oauthScopeAdditions`) must be grantable under that ceiling, or
 `/authorize` drops it and the call that needs it 403s.
 
 **A granted token can be narrower than the request even with a correct
@@ -309,8 +318,8 @@ are clamped silently (`clamp_scopes_to_ceiling`) — neither path errors;
 `/oauth/token` just returns a smaller `scope`. So never assume the token
 carries what was requested: the token response's `scope` field is the truth.
 The wizard diffs granted vs requested at login (`missingOAuthScopes` in
-`src/shared/utils/oauth.ts`), warns the user which permissions are missing, and emits
-`wizard: oauth grant narrowed` so narrowed runs are countable in analytics.
+`src/programs/oauth/tokens.ts`), warns the user which permissions are missing, and
+emits `wizard: oauth grant narrowed` so narrowed runs are countable in analytics.
 The diff also rides on the session (`credentials.missingScopes`), so when a
 run does fail on a scope-gated step, the error names the missing permission
 and the fix instead of the generic report-a-bug line.
@@ -406,10 +415,103 @@ that conventional code implies.
 If you want to use this code as a starting place for your own project, here's a
 quick explainer on its structure.
 
-## Entrypoint: `run.ts`
+## What calls what
+
+```mermaid
+%%{init: {"block": {"padding": 20}}}%%
+block-beta
+  columns 18
+  user["a user at a terminal"]:3 ci["CI or a sandbox"]:3 embedder["your program"]:3 space:3 toolUser["a user or a script"]:3 caller["your code or a test"]:3
+  cliBand["src/cli   picks a host, owns the signals and the exit"]:6 space:12
+  runWizard["runWizard"]:3 runWizardCI["runWizardCI<br/>runWizardHeadless"]:3 space:6 toolCmd["src/cli<br/>a tool's command"]:3 space:3
+  hostBand["src/tui · src/headless   the two hosts"]:6 space:12
+  runTui["runTui"]:3 runHeadless["runHeadless"]:3 space:6 runTool["runTuiTool<br/>or an @tools runner"]:3 space:3
+  wizardStore["WizardStore<br/>display over the store"]:3 space:15
+  programsBand["@programs"]:12 space:6
+  tuiStore["SessionStore"]:3 headlessStore["SessionStore"]:3 ownStore["SessionStore"]:3 detect["detectProjectsWithAgent"]:3 space:6
+  tuiRun["runProgram"]:3 headlessRun["runProgram"]:3 ownRun["runProgram"]:3 space:9
+  agentBand["@agent"]:18
+  tuiAgent["runAgent"]:3 headlessAgent["runAgent"]:3 ownAgent["runAgent"]:3 detectAgent["runAgent"]:3 mcpStream["streamMcpPrompt"]:3 callerAgent["runAgent"]:3
+
+  user --> runWizard
+  runWizard --> runTui
+  runTui --> wizardStore
+  wizardStore --> tuiStore
+  tuiStore --> tuiRun
+  tuiRun --> tuiAgent
+
+  ci --> runWizardCI
+  runWizardCI --> runHeadless
+  runHeadless --> headlessStore
+  headlessStore --> headlessRun
+  headlessRun --> headlessAgent
+
+  embedder -- "builds and owns the store" --> ownStore
+  ownStore --> ownRun
+  ownRun --> ownAgent
+
+  detect --> detectAgent
+
+  toolUser --> toolCmd
+  toolCmd --> runTool
+  runTool -- "the MCP tutorial only" --> mcpStream
+
+  caller -- "runAgent(config, input)" --> callerAgent
+
+  classDef code fill:#3b82f626,stroke:#3b82f6,stroke-width:2px
+  classDef ext fill:none,stroke:#9ca3af,stroke-dasharray:4 3
+  classDef band fill:#3b82f640,stroke:none
+  class runWizard,runWizardCI,runTui,runHeadless,wizardStore,tuiStore,headlessStore,ownStore,tuiRun,headlessRun,ownRun,tuiAgent,headlessAgent,ownAgent,detect,detectAgent,toolCmd,runTool,mcpStream,callerAgent code
+  class user,ci,embedder,toolUser,caller ext
+  class cliBand,hostBand,programsBand,agentBand band
+```
 
-The entrypoint for this tool is `run.ts`. Use this file to interpret arguments
-and set up the general flow of the application.
+Each column is one way in, read top to bottom. A box that repeats across columns
+is the same code. The CLI calls one of two hosts, the TUI or headless. They
+share only the kind of session store they build: each builds its own, calls
+`runProgram` with it, and `runProgram` writes the run into it. The TUI draws its
+screens from the `WizardStore` on top of its store, and headless prints and
+streams the run.
+
+A tool's command runs no program. The CLI calls the TUI's `runTuiTool` for the
+tool's screens, or a console runner from `@tools`. Only the MCP tutorial reaches
+the agent, through `streamMcpPrompt`. The TUI's intro can also hand off to a
+tool's screens, such as `doctor`, in the same process. See
+[src/tools](src/tools/README.md).
+
+Detection calls `runAgent` directly. `detectProjectsWithAgent` builds its own
+run config for a project scan. It runs from a program's `ciPreRun`, which
+`runProgram` calls as a CI run's detection, and from the TUI's detect screens.
+
+Dashed boxes are callers that build against a checkout of this repository, not
+the npm package. Your program can build a store and call
+`runProgram(id, { store })` itself. Your code can call `runAgent` with no
+program at all.
+
+| Box                               | What it is                                                                                                              | Where                                                                  |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `runWizard`                       | Builds the launch values from the arguments and starts the TUI host                                                     | [src/cli/runners](src/cli/runners/run-wizard.ts)                       |
+| `runWizardCI · runWizardHeadless` | Checks the non-interactive arguments and starts the headless host                                                       | [src/cli/runners](src/cli/runners)                                     |
+| `a tool's command`                | Parses the tool's arguments and calls its runner                                                                        | [src/cli/commands](src/cli/commands)                                   |
+| `runTui`                          | The full-screen wizard: OAuth login, the WizardAsk screen as the answerer, the flow's screens as the workflow           | [src/tui/run.ts](src/tui/run.ts)                                       |
+| `runHeadless`                     | A run with no screens: API-key login, no answerer, log lines and the task stream                                        | [src/headless/run.ts](src/headless/run.ts)                             |
+| `runTuiTool`                      | Shows a tool's screens on their own store and resolves the code a screen exits with; it runs no program                 | [src/tui/run-tool.ts](src/tui/run-tool.ts)                             |
+| `@tools` runner                   | A tool that runs on the console, such as `addMCPServerToClientsStep`, `runDoctorReport`, `runProvision` or `listSkills` | [src/tools](src/tools/README.md)                                       |
+| `WizardStore`                     | The TUI's own state (the screens' answers), router, gates, overlays and display state, over its session store           | [src/tui/store.ts](src/tui/store.ts)                                   |
+| `SessionStore`                    | Launch values, detection, the login and the run's progress; each host builds its own                                    | [src/programs/session](src/programs/session)                           |
+| `runProgram`                      | Runs a registered program: detection, readiness, login, the host's steps, then each agent run                           | [src/programs/run-program.ts](src/programs/run-program.ts)             |
+| `detectProjectsWithAgent`         | A project scan: one `runAgent` call per attempt, with its own route and deadline                                        | [src/programs/detection/agentic.ts](src/programs/detection/agentic.ts) |
+| `runAgent`                        | One agent run from a `RunConfig` and `RunInput`; complete on its own                                                    | [src/agent](src/agent/README.md)                                       |
+| `streamMcpPrompt`                 | The MCP tutorial's prompt stream: one prompt against the PostHog MCP server, with its own SDK call                      | [src/agent/mcp-prompt-streaming.ts](src/agent/mcp-prompt-streaming.ts) |
+
+## Entrypoint: `bin.ts`
+
+The entrypoint for this tool is `bin.ts`. It checks the Node version, and only
+then loads `main.ts` with a dynamic import, so no dependency runs on an old
+Node. `main.ts` sets the HTTP/1.1 dispatcher, restores any Claude settings
+backup an interrupted run left behind, and calls `runCli()` from
+`src/cli/index.ts`. `runCli` registers each command on the yargs setup in
+`src/cli/wizard.ts` and runs the one that `process.argv` names.
 
 ## Analytics
 
@@ -435,8 +537,8 @@ set `POSTHOG_WIZARD_NO_TELEMETRY=1`) to disable either remote transport.
 Supporting agent sessions after we leave is important. There are plenty of ways
 to break or misconfigure PostHog, so guarding against this is key.
 
-`src/shared/utils/rules/add-editor-rules.ts` demonstrates how to dynamically construct
-rules files and store them in the project's `.cursor/rules` directory.
+`src/shared/utils/rules/` holds per-framework rule templates in Markdown. No
+code reads them or writes them into a project today.
 
 ## Prompts and LLM interactions
 
@@ -447,12 +549,13 @@ existing code at scale and then modify it reliably.
 
 _If_ they are well prompted.
 
-`src/lib/prompts.ts` demonstrates how to wrap a deterministic fence around a
-chaotic process. Every wizard session gets the same prompt, tailored to the
-specific files in the project.
+`src/agent/agent-prompt.ts` demonstrates how to wrap a deterministic fence
+around a chaotic process. Every wizard session gets the same prompt, tailored to
+the specific files in the project.
 
-These prompts are channeled using `src/shared/utils/query.ts` to an LLM interface we
-host. This gives us more control: we can be certain of the model version and
+These prompts go to the PostHog LLM gateway, an LLM interface we
+host, with a scoped token that `src/agent/gateway-session.ts` mints for each
+run. This gives us more control: we can be certain of the model version and
 provider which interpret the prompts and modify the files. This way, we can find
 the right tools for the job and again, apply them consistently.
 
@@ -493,45 +596,73 @@ Built with [tsdown](https://tsdown.dev/) (Rolldown). `pnpm build` bundles `bin.t
 
 ### Environment variables
 
-**Build-time (locked).** `NODE_ENV` is replaced with `"production"` at compile time. It cannot be overridden at runtime. All URLs, OAuth client IDs, and dev-mode code paths resolve to their production values unconditionally.
+**Build-time (locked).** `pnpm build` replaces `NODE_ENV` with `"production"` at compile time. It cannot be overridden at runtime. All URLs, OAuth client IDs, and dev-mode code paths resolve to their production values. `pnpm build:ci` inlines `ci` instead, which keeps dev and test flags such as `--ci`.
 
 To add a new build-time constant, add it to `env` in `tsdown.config.ts` and export it from `src/env.ts`.
 
-**Runtime (allowlisted).** Runtime env reads go through `runtimeEnv()` in `src/env.ts`, which only accepts keys in the `RuntimeEnvKey` union:
+**Runtime (allowlisted).** Most runtime env reads go through `runtimeEnv()` in `src/env.ts`, which only accepts keys in the `RuntimeEnvKey` union:
 
 | Variable | Purpose |
 |---|---|
 | `POSTHOG_WIZARD_BENCHMARK_CONFIG` | Path to benchmark config file |
 | `POSTHOG_WIZARD_BENCHMARK_FILE` | Output path for benchmark results |
 | `POSTHOG_WIZARD_LOG_DIR` | Log directory override |
-| `POSTHOG_WIZARD_DEBUG` / `DEBUG` | Enable debug output |
+| `POSTHOG_WIZARD_RUN_ID` | Assigned cloud WizardRun id |
+| `POSTHOG_TASK_RUN_ID`, `POSTHOG_TASK_ID`, `POSTHOG_HANDOFF_OUTPUT_PATH` | The PostHog task run that launched the wizard |
+| `WIZARD_CI_GATEWAY_TOKEN_FILE`, `WIZARD_CI_GATEWAY_URL` | The gateway token and URL for `--ci` runs |
+| `WIZARD_CI_FLAG_OVERRIDES`, `WIZARD_CI_EXCLUDE_TASKS` | Flag and task overrides for CI builds |
 | `MCP_URL` | Override MCP server URL |
-| `POSTHOG_API_KEY` | API key for MCP subprocess auth |
-| `TERM`, `TERM_PROGRAM`, `CI`, etc. | Terminal/platform detection |
-| `APPDATA`, `XDG_CONFIG_HOME` | Platform path resolution |
+| `APPDATA`, `XDG_CONFIG_HOME`, `OPENCODE_CONFIG_DIR` | Platform path resolution |
 
 To add a new runtime env var, add its key to `RuntimeEnvKey` in `src/env.ts`.
+The CLI reads every `POSTHOG_WIZARD_*` variable as an option and rejects unknown
+ones, so a CLI run with `POSTHOG_WIZARD_BENCHMARK_CONFIG`,
+`POSTHOG_WIZARD_BENCHMARK_FILE` or `POSTHOG_WIZARD_WARLOCK_DISABLED` set exits
+with `Unknown argument`. `POSTHOG_WIZARD_LOG_FILE` is the exception: it is the
+env form of `--log-file`, a declared option that moves the debug log from its
+default, `posthog-wizard.log` in the temp directory.
 
-**Direct `process.env` access** is only used for subprocess environment writes (e.g. `agent-interface.ts` setting `ANTHROPIC_BASE_URL`), vendored code, and tests.
+**Direct `process.env` access** covers terminal detection (`TERM`, `TERM_PROGRAM`, `CI`, …), subprocess environment writes (e.g. `agent-interface.ts` setting `ANTHROPIC_BASE_URL`), a few launch-time reads, vendored code, and tests.
 
 ### Import aliases
 
-Path aliases defined in `tsconfig.build.json`, resolved by tsdown:
+Path aliases defined in `tsconfig.base.json`, resolved by tsdown and `tsx`:
 
 | Alias | Maps to |
 |---|---|
 | `@env` | `src/env.ts` |
-| `@lib/*` | `src/lib/*` |
-| `@agent` | `src/agent/index.ts`, the agent's runtime entry; the only agent import outside `src/agent` besides types |
+| `@shared/*` | `src/shared/*` |
+| `@utils/*` | `src/shared/utils/*` |
+| `@host/*` | `src/host/*`, how a run ends (`startHostExit`, `wizardAbort`, `registerShutdown`), for headless, the TUI, the CLI and the e2e harness |
+| `@agent` | `src/agent/index.ts`, the agent's runtime entry |
 | `@agent/types` | `src/agent/types.ts`, type-only |
-| `@agent/*` | `src/agent/*`, inside `src/agent` and its tests only |
+| `@agent/*` | `src/agent/*`, for the agent's tests. The agent imports its own modules by relative path, and no other layer maps it |
 | `@programs` | `src/programs/index.ts`, the programs runtime entry |
 | `@programs/types` | `src/programs/types.ts`, type-only |
-| `@programs/*` | `src/programs/*`, retained for internal imports and tracked migration edges |
-| `@shared/*` | `src/shared/*` |
-| `@utils/*` | `src/shared/utils/*` |
-| `@ui/*` | `src/ui/*` |
-| `@steps/*` | `src/steps/*` |
+| `@programs/<id>` | `src/programs/<id>/index.ts`, one program's entry. Other layers reach nothing else in a program folder |
+| `@programs/*` | `src/programs/*`. Other layers reach only the `@programs/<id>` entries; the programs import their own code by relative path, and only their tests use this alias |
+| `@tools` | `src/tools/index.ts`, the tools' one entry: the commands that run no agent. The TUI and the CLI import it; programs never do |
+| `@tui` | `src/tui/index.ts`, the TUI's one entry, for the CLI and the e2e harness |
+| `@tui/*` | `src/tui/*`. Only the TUI's own projects may use it |
+| `@headless` | `src/headless/index.ts`, headless's one entry, for the CLI |
+| `@cli` | `src/cli/index.ts`, the CLI's one entry, for `main.ts` |
+| `@cli/*` | `src/cli/*`. Only the CLI may use it |
+| `@e2e-harness/*` | `e2e-harness/*`, for the harness, scripts and tests |
+
+Each layer's tsconfig project `references` only the layers it may import, so
+`pnpm typecheck` rejects an import of any other. Outside the TUI, `ink`,
+`react`, `@inkjs/ui` and `ink-testing-library` resolve to a fence that fails
+every import form, and no layer imports JSON. `pnpm lint` rejects the paths the
+compiler can't see: a relative import that leaves its layer's folder, a deep
+alias outside its own layer, a `.tsbuild/` or `node_modules/` path, `module`
+loaders and a bare `require`, triple-slash references, and the hosts importing
+the agent's runtime. See
+[layer boundaries](.claude/skills/wizard-development/references/ARCHITECTURE.md#layer-boundaries)
+for what each layer may import and why each rule exists. Code outside a layer
+imports it only through the entries above. The e2e harness, scripts and
+`docs/examples` are one layer project, `e2e-harness/tsconfig.json`. Tests follow
+the same rule: each layer's tests sit in its project, and a test mocks another
+layer through its entry.
 
 ## Running locally
 
@@ -554,12 +685,12 @@ pnpm run dev
 This builds, links globally, and watches for changes. Leave it running - any `.ts` file changes will auto-rebuild. Then from any project:
 
 ```bash
-wizard --integration=nextjs
+wizard
 
 # Point individual services at local dev servers:
-wizard --integration=nextjs --local-context-mill   # skills from localhost:8765
-wizard --integration=nextjs --local-mcp            # MCP from localhost:8787
-wizard --integration=nextjs --local-dev            # context-mill + MCP + PostHog
+wizard --local-context-mill   # skills from localhost:8765
+wizard --local-mcp            # MCP from localhost:8787
+wizard --local-dev            # context-mill + MCP + PostHog
 ```
 
 See [`docs/local-dev.md`](docs/local-dev.md) for the full catalog.
@@ -613,7 +744,8 @@ Example prompt — explore against
 >    for any setup question, then `run_agent` at auth.
 > 4. Poll `read_state` until `integration` is `done` (or `failed` — then report
 >    `integrationError`), snapshotting as the run screen progresses.
-> 5. Finish the tail: dismiss outro / mcp / slack, then `keep_skills`.
+> 5. Finish the tail: `dismiss_outro`, `set_mcp_outcome`, then
+>    `keep_skills`.
 >
 > Then show me the saved snapshots in order, the screen path, whether `posthog`
 > landed in the app, and anything that broke.
@@ -635,7 +767,7 @@ The entry point is `evaluateWizardReadiness()`, which only blocks on skill downl
 | Decision            | Meaning                                                         |
 | ------------------- | --------------------------------------------------------------- |
 | `yes`               | Skills are reachable — proceed without outage warnings.         |
-| `no`                | Neither skills origin is reachable — do not run.                |
+| `no`                | Neither skills origin is reachable. Interactive runs show the outage and stop; non-interactive runs report it and continue. |
 
 ### Module layout
 
@@ -649,8 +781,8 @@ The entry point is `evaluateWizardReadiness()`, which only blocks on skill downl
 
 ## What blocks a run
 
-The `DEFAULT_WIZARD_READINESS_CONFIG` in `readiness.ts` controls this. It has
-two arrays:
+The `DEFAULT_WIZARD_READINESS_CONFIG` in `readiness.ts` controls this. Its type
+has two arrays, and the default sets only `downBlocksRun`:
 
 - **`downBlocksRun`** — if any of these report status **Down**, readiness is
   **No**.
@@ -686,7 +818,7 @@ This repo includes a helper script to run a full end‑to‑end smoke test of th
   - Cloning `wizard-workbench` next to this repo (so it lives at `../wizard-workbench`).
 - Set `POSTHOG_PERSONAL_API_KEY` either in your shell or in `../wizard-workbench/.env`.
 - Set `WIZARD_CI_GATEWAY_TOKEN_FILE` to an absolute path containing the separate
-  AI gateway token. See [local credentials](docs/local-dev.md#credentials-for-local-ci-and-headless-runs).
+  gateway service key from 1Password. See [local credentials](docs/local-dev.md#credentials-for-local-ci-and-headless-runs).
 - Set `POSTHOG_WIZARD_PROJECT_ID` to the intended test project and
   `POSTHOG_WIZARD_REGION` to `us` or `eu` (CI uses `us`). The helper also accepts
   `POSTHOG_PROJECT_ID` and `POSTHOG_REGION` as fallback names.

package/dist/{PickerMenu-m4CCPX4f.js → PickerMenu-BGGeYqd-.js}

@@ -1,8 +1,28 @@
-import { $ as wordWrap, it as Icons, rt as Colors } from "./mint-failure-C0HyvEwO.js";
 import { Box, Text, useInput, useStdout } from "ink";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
 import Fuse from "fuse.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/tui/styles.ts
+const Colors = {
+	primary: "cyan",
+	accent: "#DC9300",
+	titleColor: "#3D2800",
+	success: "green",
+	error: "red",
+	muted: "gray"
+};
+const Icons = {
+	diamond: "◆",
+	diamondOpen: "◇",
+	check: "✔",
+	warning: "⚠",
+	squareFilled: "◼",
+	squareOpen: "◻",
+	triangleRight: "▶",
+	triangleSmallRight: "▸",
+	bullet: "•"
+};
+//#endregion
 //#region src/tui/primitives/picker-filter.ts
 /**
 * Filter-as-you-type matching for PickerMenu. Split out from the component so the
@@ -122,6 +142,86 @@ const ConfirmButton = ({ label = "Confirm", focused, count }) => {
 	});
 };
 //#endregion
+//#region src/tui/primitives/content-types.ts
+/** Type guard for lines blocks. */
+function isLinesBlock(block) {
+	return typeof block !== "string" && "type" in block && block.type === "lines";
+}
+/** Type guard for clear blocks. */
+function isClearBlock(block) {
+	return typeof block !== "string" && "type" in block && block.type === "clear";
+}
+/** Type guard for object blocks (text or node content). */
+function isObjectBlock(block) {
+	return typeof block !== "string" && !("type" in block);
+}
+//#endregion
+//#region src/tui/primitives/layout-helpers.ts
+/**
+* Estimate the number of terminal rows a content block will occupy,
+* including 1 row of marginBottom.
+*/
+function estimateBlockHeight(block, availableWidth) {
+	if (typeof block === "string") return wordWrap(block, availableWidth).length + 1;
+	if (isClearBlock(block)) return 0;
+	if (isLinesBlock(block)) return block.lines.length + 1;
+	if (isObjectBlock(block)) {
+		if (typeof block.content === "string") return wordWrap(block.content, availableWidth).length + 1;
+		return 4;
+	}
+	return 1;
+}
+/**
+* Given all blocks, the active index, available width, and a row budget,
+* return [startIdx, endIdx] — the range of blocks to render.
+*
+* Always includes activeIdx. Walks backward to include as many completed
+* blocks as fit within maxHeight.
+*/
+function computeVisibleRange(blocks, activeIdx, availableWidth, maxHeight) {
+	const budget = Math.max(4, maxHeight - 2);
+	let totalHeight = estimateBlockHeight(blocks[activeIdx], availableWidth);
+	let start = activeIdx;
+	for (let i = activeIdx - 1; i >= 0; i--) {
+		if (isClearBlock(blocks[i])) break;
+		const h = estimateBlockHeight(blocks[i], availableWidth);
+		if (totalHeight + h > budget) break;
+		totalHeight += h;
+		start = i;
+	}
+	return [start, activeIdx];
+}
+/**
+* Word-wrap text at clean word boundaries. Always returns pre-wrapped text
+* joined with \n — this avoids Ink's native wrap which can leave leading
+* spaces on continuation lines.
+*
+* Uses a 1-char safety margin so slight width estimate mismatches don't
+* cause Ink to re-wrap our already-wrapped lines.
+*/
+function wordWrap(text, availableWidth) {
+	const safeWidth = Math.max(10, availableWidth - 1);
+	const words = text.split(/\s+/);
+	const lines = [];
+	let currentLine = "";
+	for (const word of words) if (currentLine.length + word.length + 1 > safeWidth && currentLine.length > 0) {
+		lines.push(currentLine);
+		currentLine = word;
+	} else currentLine += (currentLine.length > 0 ? " " : "") + word;
+	if (currentLine.length > 0) lines.push(currentLine);
+	return lines;
+}
+/**
+* Word-wrap text and return only the last `maxRows` lines.
+* Used for intra-block truncation when a single text block exceeds the viewport.
+* Also used for normal rendering to avoid Ink's leading-space wrap artifacts.
+*/
+function wrapAndTruncate(text, availableWidth, maxRows) {
+	const lines = wordWrap(text, availableWidth);
+	if (lines.length <= maxRows) return lines.join("\n");
+	return lines.slice(-maxRows).join("\n");
+}
+//#endregion
 //#region src/tui/hooks/useStdoutDimensions.ts
 /**
 * useStdoutDimensions — Returns [columns, rows] and re-renders on terminal resize.
@@ -753,6 +853,6 @@ const MultiPickerMenu = ({ message, options, centered = false, columns = 1, opti
 	});
 };
 //#endregion
-export { useStdoutDimensions as a, useKeyboardHintsContext as i, useKeyBindings as n, ConfirmButton as o, KeyboardHintsProvider as r, PromptLabel as s, PickerMenu as t };
+export { useStdoutDimensions as a, wrapAndTruncate as c, isObjectBlock as d, ConfirmButton as f, Icons as h, useKeyboardHintsContext as i, isClearBlock as l, Colors as m, useKeyBindings as n, computeVisibleRange as o, PromptLabel as p, KeyboardHintsProvider as r, wordWrap as s, PickerMenu as t, isLinesBlock as u };
 
-//# sourceMappingURL=PickerMenu-m4CCPX4f.js.map
+//# sourceMappingURL=PickerMenu-BGGeYqd-.js.map