wizard: Instructions file for Codex

AGENTS.md — PostHog Wizard

Instructions for all agents (and humans) working in this repo. This is the single source of truth; CLAUDE.md just points here. User-facing docs: https://posthog.com/docs/ai-engineering/ai-wizard

The PostHog wizard (npx @posthog/wizard) is a CLI that adds PostHog to a user's project using an AI agent. It authenticates the user, detects their framework, runs an agent that integrates the SDK and instruments events, and walks the user through their first dashboard. All from the terminal.

Design discipline

This codebase follows a specific design discipline: product knowledge never enters infrastructure code. The runner pipeline, the TUI store, the detection loop, and the prompt assembler are machinery. They don't know what PostHog is. They don't know what a framework is. They execute a pipeline driven by typed configuration surfaces.

Each domain has a dedicated boundary:

• Frameworks → FrameworkConfig in src/services/frameworks/<name>/
• Integration knowledge → markdown skills in the context-mill repo
• Security policy → YARA-X rules in the warlock sibling repo. The wizard wires the scanner through SDK hooks and Pi tool events; see security boundaries. Gateway admission and required safety prompts live in ai-gateway. To disable scanning in the field without a release, see the kill-switch runbook: docs/runbooks/warlock-kill-switch.md. ONLY USE THIS IF ABSOLUTELY NECESSARY.
• Agent → src/agent/. Layer source outside it imports it only through @agent (values) and @agent/types (types); see src/agent/README.md
• Shared → src/shared/, library code with no upward imports. It also holds process-global state: the log file, the analytics client, the exit cleanup list and the process's one OAuth login session (@shared/oauth-session); see src/shared/README.md
• Host → src/host/ (@host/*), how the hosts end a run: startHostExit, wizardAbort and registerShutdown. Every wizardAbort call passes the presenter that shows its outro. A host resolves an exit code and only the CLI calls process.exit. It imports env and shared only. Headless, the TUI, the CLI and the e2e harness may import it. The agent and the programs may not; see src/host/README.md
• Services → src/services/, part of the program layer: what programs consume, such as the session store, detection, the framework configs, the codebase scan and the tool catalog. It imports env, shared, the agent and the program contract (@programs/program-contract, in src/programs/program-contract/), which sits below it and imports no service. Code outside it imports a service through its entry, @services/<service>; see src/services/README.md
• Programs → one folder per program in src/programs/<id>/, which other layer source enters only through its index.ts, plus runProgram. A program is an agent run; see src/programs/README.md and the developer interfaces
• Tools → src/tools/ (@tools, one entry), the commands that run no agent: mcp add, mcp remove, mcp tutorial, slack, doctor, provision, cli add and skill list. A tool may import env, shared and the @agent entry (the MCP tutorial's prompt stream only), never the programs, host, TUI, headless or CLI, and no program imports it. Its screens live in src/tui/tools/<id>/, run by runTuiTool; every tool runner resolves an exit code. See src/tools/README.md
• TUI → the interactive host (runTui), screens, primitives and the screen store in src/tui/, which other layers enter only through its one entry, @tui (src/tui/index.ts); see src/tui/README.md. Each program's flow, deck and screens live in src/tui/programs/<id>/, and each tool's in src/tui/tools/<id>/, entered through its index module; the TUI core reaches them only through the TUI program and tool registries. A program's flow uses a step a tool also shows, such as the MCP install, by its core screen id
• Headless → the host with no screens (runHeadless) and LoggingUI in src/headless/, which other layers enter only through its one entry, @headless (src/headless/index.ts); see src/headless/README.md. The two hosts share only the kind of session store they build, SessionStore in @programs, and the host layer; neither loads the other's code, and each calls runProgram; see what calls what
• CLI → commands, runners and the choice of host in src/cli/, the only layer that imports both the TUI and headless, each through its entry. bin.ts checks the Node version and loads main.ts, which imports the CLI through its entry, @cli (src/cli/index.ts); see src/cli/README.md
• Layers → one tsconfig project per layer folder, on TypeScript project references, and pnpm typecheck is tsc -b. A project's references name the layers it may import, so importing a file of any other fails with TS6307. Outside the TUI, ink, react, @inkjs/ui and ink-testing-library resolve to a fence that fails every import form. ESLint rules in pnpm lint close the paths the compiler can't see: a relative import that leaves its layer's folder and a deep alias outside its own layer; a .tsbuild/ or node_modules/ path in an import, re-export, import() or typeof import(); any import of module or node:module; a bare require; and triple-slash path references; see layer boundaries and import aliases. Code outside a layer imports it only through its public entries. Each layer's tests sit in its project, so a test deep-imports only its own layer and mocks another through its entry, except that it may mock a service's internal module by its @services/* path.