maxritter · maxritter · May 28, 2026 · May 27, 2026 · May 27, 2026 · May 27, 2026
diff --git a/.gitignore b/.gitignore
@@ -243,18 +243,21 @@ benchmarks/**
 skill-creator
 spec-annotate
 changes-header
+review-output.json
 apm.yml
 .playwright-*/
 .apm
 .agents
 .codegraph
 .vercel
 .codex
+.review
 .mypy_cache
 .mcp.json
 demo
 skills-lock.json
 sx.json
+context-hud
 .env**
 playwright/
 .claude.backup.*

diff --git a/README.md b/README.md
diff --git a/console/src/cli/adapters/codex.ts b/console/src/cli/adapters/codex.ts
diff --git a/console/src/cli/adapters/index.ts b/console/src/cli/adapters/index.ts
diff --git a/console/src/cli/handlers/context.ts b/console/src/cli/handlers/context.ts
diff --git a/console/src/cli/handlers/session-init.ts b/console/src/cli/handlers/session-init.ts
diff --git a/console/src/cli/hook-command.ts b/console/src/cli/hook-command.ts
diff --git a/console/src/services/sqlite/SessionStore.ts b/console/src/services/sqlite/SessionStore.ts
diff --git a/console/src/services/sqlite/migrations/runner.ts b/console/src/services/sqlite/migrations/runner.ts
diff --git a/console/src/services/sqlite/sessions/create.ts b/console/src/services/sqlite/sessions/create.ts
diff --git a/console/src/services/worker-types.ts b/console/src/services/worker-types.ts
diff --git a/console/src/services/worker/CodexSessionReader.ts b/console/src/services/worker/CodexSessionReader.ts
diff --git a/console/src/services/worker/PaginationHelper.ts b/console/src/services/worker/PaginationHelper.ts
diff --git a/console/src/services/worker/SessionJsonlService.ts b/console/src/services/worker/SessionJsonlService.ts
diff --git a/console/src/services/worker/http/routes/DataRoutes.ts b/console/src/services/worker/http/routes/DataRoutes.ts
diff --git a/console/src/services/worker/http/routes/ExtensionRoutes.ts b/console/src/services/worker/http/routes/ExtensionRoutes.ts
diff --git a/console/src/services/worker/http/routes/ExtensionTypes.ts b/console/src/services/worker/http/routes/ExtensionTypes.ts
diff --git a/console/src/services/worker/http/routes/SessionRoutes.ts b/console/src/services/worker/http/routes/SessionRoutes.ts
diff --git a/console/src/services/worker/http/routes/SettingsRoutes.ts b/console/src/services/worker/http/routes/SettingsRoutes.ts
diff --git a/console/src/services/worker/http/routes/UsageRoutes.ts b/console/src/services/worker/http/routes/UsageRoutes.ts
diff --git a/console/src/services/worker/http/routes/utils/planFileReader.ts b/console/src/services/worker/http/routes/utils/planFileReader.ts
diff --git a/console/src/services/worker/usage/aggregator.ts b/console/src/services/worker/usage/aggregator.ts
diff --git a/console/src/services/worker/usage/claude-parser.ts b/console/src/services/worker/usage/claude-parser.ts
diff --git a/console/src/services/worker/usage/codex-parser.ts b/console/src/services/worker/usage/codex-parser.ts
diff --git a/console/src/services/worker/usage/pricing.ts b/console/src/services/worker/usage/pricing.ts
diff --git a/console/src/services/worker/usage/yield.ts b/console/src/services/worker/usage/yield.ts
diff --git a/console/src/shared/SettingsDefaultsManager.ts b/console/src/shared/SettingsDefaultsManager.ts
diff --git a/console/src/shared/hook-constants.ts b/console/src/shared/hook-constants.ts
diff --git a/console/src/shared/transcript-parser.ts b/console/src/shared/transcript-parser.ts
diff --git a/console/src/ui/viewer/App.tsx b/console/src/ui/viewer/App.tsx
diff --git a/console/src/ui/viewer/components/CommandPalette.tsx b/console/src/ui/viewer/components/CommandPalette.tsx
diff --git a/console/src/ui/viewer/components/ui/AgentBadge.tsx b/console/src/ui/viewer/components/ui/AgentBadge.tsx
diff --git a/console/src/ui/viewer/components/ui/index.ts b/console/src/ui/viewer/components/ui/index.ts
diff --git a/console/src/ui/viewer/constants/shortcuts.ts b/console/src/ui/viewer/constants/shortcuts.ts
diff --git a/console/src/ui/viewer/hooks/useExtensions.ts b/console/src/ui/viewer/hooks/useExtensions.ts
diff --git a/console/src/ui/viewer/hooks/useHotkeys.ts b/console/src/ui/viewer/hooks/useHotkeys.ts
diff --git a/console/src/ui/viewer/hooks/useStats.ts b/console/src/ui/viewer/hooks/useStats.ts
diff --git a/console/src/ui/viewer/hooks/useUsage.ts b/console/src/ui/viewer/hooks/useUsage.ts
diff --git a/console/src/ui/viewer/layouts/Sidebar/SidebarNav.tsx b/console/src/ui/viewer/layouts/Sidebar/SidebarNav.tsx
diff --git a/console/src/ui/viewer/views/Dashboard/RecentActivity.tsx b/console/src/ui/viewer/views/Dashboard/RecentActivity.tsx
diff --git a/console/src/ui/viewer/views/Dashboard/RecentRequirements.tsx b/console/src/ui/viewer/views/Dashboard/RecentRequirements.tsx
diff --git a/console/src/ui/viewer/views/Dashboard/RecentSessions.tsx b/console/src/ui/viewer/views/Dashboard/RecentSessions.tsx
diff --git a/console/src/ui/viewer/views/Dashboard/RecentSpecs.tsx b/console/src/ui/viewer/views/Dashboard/RecentSpecs.tsx
diff --git a/console/src/ui/viewer/views/Documentation/index.tsx b/console/src/ui/viewer/views/Documentation/index.tsx
diff --git a/console/src/ui/viewer/views/Extensions/ExtensionDetail.tsx b/console/src/ui/viewer/views/Extensions/ExtensionDetail.tsx
diff --git a/console/src/ui/viewer/views/Extensions/ExtensionsGrid.tsx b/console/src/ui/viewer/views/Extensions/ExtensionsGrid.tsx
diff --git a/console/src/ui/viewer/views/Extensions/ExtensionsView.tsx b/console/src/ui/viewer/views/Extensions/ExtensionsView.tsx
diff --git a/console/src/ui/viewer/views/Help/index.tsx b/console/src/ui/viewer/views/Help/index.tsx
diff --git a/console/src/ui/viewer/views/Memories/MemoryCard.tsx b/console/src/ui/viewer/views/Memories/MemoryCard.tsx
diff --git a/console/src/ui/viewer/views/Memories/index.tsx b/console/src/ui/viewer/views/Memories/index.tsx
diff --git a/console/src/ui/viewer/views/Requirements/index.tsx b/console/src/ui/viewer/views/Requirements/index.tsx
diff --git a/console/src/ui/viewer/views/Sessions/SessionCard.tsx b/console/src/ui/viewer/views/Sessions/SessionCard.tsx
diff --git a/console/src/ui/viewer/views/Sessions/SessionDetail.tsx b/console/src/ui/viewer/views/Sessions/SessionDetail.tsx
diff --git a/console/src/ui/viewer/views/Sessions/SessionTimeline.tsx b/console/src/ui/viewer/views/Sessions/SessionTimeline.tsx
diff --git a/console/src/ui/viewer/views/Sessions/index.tsx b/console/src/ui/viewer/views/Sessions/index.tsx
diff --git a/console/src/ui/viewer/views/Settings/sections/SpecWorkflowSection.tsx b/console/src/ui/viewer/views/Settings/sections/SpecWorkflowSection.tsx
diff --git a/console/src/ui/viewer/views/Settings/sections/_shared.tsx b/console/src/ui/viewer/views/Settings/sections/_shared.tsx
diff --git a/console/src/ui/viewer/views/Spec/SpecHeaderCard.tsx b/console/src/ui/viewer/views/Spec/SpecHeaderCard.tsx
diff --git a/console/src/ui/viewer/views/Spec/index.tsx b/console/src/ui/viewer/views/Spec/index.tsx
diff --git a/console/src/ui/viewer/views/Usage/ModelCostBreakdown.tsx b/console/src/ui/viewer/views/Usage/ModelCostBreakdown.tsx
diff --git a/console/src/ui/viewer/views/Usage/index.tsx b/console/src/ui/viewer/views/Usage/index.tsx
diff --git a/console/src/ui/viewer/views/index.ts b/console/src/ui/viewer/views/index.ts
diff --git a/console/src/utils/logger.ts b/console/src/utils/logger.ts
@@ -49,7 +49,8 @@ export type Component =
   | "CLEANUP"
   | "DATA"
   | "VECTOR_DB_GUARD"
-  | "FEEDBACK_POLL";
+  | "FEEDBACK_POLL"
+  | "CODEX_PARSER";
 
 interface LogContext {
   sessionId?: number;

diff --git a/console/tests/cli/codex-adapter.test.ts b/console/tests/cli/codex-adapter.test.ts
diff --git a/console/tests/cli/codex-agent-filter.test.ts b/console/tests/cli/codex-agent-filter.test.ts
diff --git a/console/tests/cli/context-handler-plan.test.ts b/console/tests/cli/context-handler-plan.test.ts
diff --git a/console/tests/cli/hook-command-failopen.test.ts b/console/tests/cli/hook-command-failopen.test.ts
diff --git a/console/tests/shared/settings-defaults-manager-output.test.ts b/console/tests/shared/settings-defaults-manager-output.test.ts
diff --git a/console/tests/shared/transcript-parser.test.ts b/console/tests/shared/transcript-parser.test.ts
diff --git a/console/tests/ui/ChangesNavigation.test.ts b/console/tests/ui/ChangesNavigation.test.ts
diff --git a/console/tests/ui/ExtensionsGrid.test.ts b/console/tests/ui/ExtensionsGrid.test.ts
diff --git a/console/tests/ui/codex-session-detail.test.ts b/console/tests/ui/codex-session-detail.test.ts
diff --git a/console/tests/ui/dashboard-agent-badges.test.tsx b/console/tests/ui/dashboard-agent-badges.test.tsx
diff --git a/console/tests/ui/spec-delete-selection.test.ts b/console/tests/ui/spec-delete-selection.test.ts
diff --git a/console/tests/ui/spec-section-rendering.test.ts b/console/tests/ui/spec-section-rendering.test.ts
diff --git a/console/tests/ui/spec-workflow-settings-copy.test.ts b/console/tests/ui/spec-workflow-settings-copy.test.ts
diff --git a/console/tests/ui/teams-navigation.test.ts b/console/tests/ui/teams-navigation.test.ts
diff --git a/console/tests/unit/services/worker/SessionJsonlService.test.ts b/console/tests/unit/services/worker/SessionJsonlService.test.ts
diff --git a/console/tests/unit/services/worker/codex-session-reader.test.ts b/console/tests/unit/services/worker/codex-session-reader.test.ts
diff --git a/console/tests/unit/services/worker/usage/aggregator.test.ts b/console/tests/unit/services/worker/usage/aggregator.test.ts
diff --git a/console/tests/unit/services/worker/usage/claude-parser.test.ts b/console/tests/unit/services/worker/usage/claude-parser.test.ts
diff --git a/console/tests/unit/services/worker/usage/codex-parser.test.ts b/console/tests/unit/services/worker/usage/codex-parser.test.ts
diff --git a/console/tests/worker/extension-routes.test.ts b/console/tests/worker/extension-routes.test.ts
diff --git a/console/tests/worker/usage-routes.test.ts b/console/tests/worker/usage-routes.test.ts
diff --git a/console/tsconfig.json b/console/tsconfig.json
@@ -12,14 +12,13 @@
     "skipLibCheck": true,
     "noEmit": true,
     "jsx": "react-jsx",
-    "baseUrl": ".",
     "paths": {
-      "@/*": ["src/*"],
-      "@ui/*": ["src/ui/viewer/*"],
-      "@services/*": ["src/services/*"],
-      "@types/*": ["src/types/*"],
-      "@utils/*": ["src/utils/*"],
-      "@shared/*": ["src/shared/*"]
+      "@/*": ["./src/*"],
+      "@ui/*": ["./src/ui/viewer/*"],
+      "@services/*": ["./src/services/*"],
+      "@types/*": ["./src/types/*"],
+      "@utils/*": ["./src/utils/*"],
+      "@shared/*": ["./src/shared/*"]
     }
   },
   "include": [

diff --git a/docs/docusaurus/docs/features/bot.md b/docs/docusaurus/docs/features/bot.md
@@ -1,11 +1,15 @@
 ---
 sidebar_position: 2
 title: Pilot Bot
-description: Persistent Pilot Bot agent — scheduled tasks, background jobs, heartbeat monitoring, and 24/7 automation running on Sonnet for cost-effective Claude operations.
+description: Persistent Claude Code automation agent — scheduled tasks, background jobs, heartbeat monitoring, and 24/7 operation running on Sonnet.
 ---
 
 # Pilot Bot
 
+:::warning Claude Code only
+Pilot Bot requires Claude Code. It is not available with Codex CLI.
+:::
+
 Persistent automation agent — scheduled tasks, background jobs, heartbeat monitoring, 24/7 operation. Always runs on Sonnet for cost-effective automation.
 
 ```bash

diff --git a/docs/docusaurus/docs/features/cli.md b/docs/docusaurus/docs/features/cli.md
@@ -1,48 +1,41 @@
 ---
 sidebar_position: 4
 title: Pilot CLI
-description: Command reference for the pilot binary at ~/.pilot/bin/pilot — session management, license activation, statusline, worktree control, and updates.
+description: Command reference for the pilot admin binary — license activation, updates, worktrees, bot mode, and customization.
 ---
 
 # Pilot CLI
 
-Command reference for the `pilot` binary at `~/.pilot/bin/pilot`.
+Admin command reference for the `pilot` binary at `~/.pilot/bin/pilot`.
 
-Run `pilot` or `ccp` with no arguments to start Claude with Pilot enhancements. Most commands support `--json` for structured output. Multiple sessions can run in parallel on the same project.
+:::note Pilot does not launch your agent
+Pilot Shell loads automatically when you run `claude` or `codex` — there is no wrapper command. The `pilot` CLI is for admin tasks only: license management, updates, worktrees, bot mode, customization, and diagnostics. Most commands support `--json` for structured output.
+:::
 
-## Session & context
+## License & auth
 
 | Command | Description |
 |---------|-------------|
-| `pilot` | Start Claude with Pilot enhancements, license check, and a one-line update banner when a newer release exists |
-| `pilot [claude-flags...]` | Start Claude with any Claude CLI flags passed through |
-| `pilot -p "prompt" [flags...]` | Headless mode — non-interactive for CI/CD, scripts |
-| `pilot run [flags...]` | Explicit alias for starting Claude |
-| `pilot agents` | Open Claude's agent view (`claude agents`) to manage multiple background sessions |
-| `ccp` | Alias for `pilot` |
-| `pilot update [--yes] [--json] [--skip-claude]` | Update both Claude Code and Pilot Shell. `pilot upgrade` is an alias — both verbs run the same flow. |
-| `pilot check-context --json` | Get current context usage percentage |
-| `pilot register-plan <path> <status>` | Associate a plan file with the current session |
-| `pilot sessions [--json]` | Show count of active Pilot sessions |
-| `pilot statusline` | Run the status line formatter (called by Claude Code) |
-| `pilot notify <type> <title> <message> [--plan-path PATH] [--json]` | Send a notification to the Console dashboard (type: `info`, `plan_approval`, `attention_needed`, `verification_complete`) |
-| `pilot skill-build <skill-dir> [--output <path>] [--dry-run] [--json]` | Build `SKILL.md` and `hashes.json` from a skill's manifest + fragments |
-| `pilot --version` | Show Pilot Shell version |
-
-:::info Update flow
-On launch, `pilot` checks both registries — GitHub releases for Pilot Shell and the npm registry for Claude Code (`@anthropic-ai/claude-code`) — and prints a one-line banner when either has a newer version. Startup never blocks on installation.
-
-Run `pilot update` (or its `pilot upgrade` alias — both verbs are interchangeable) when you're ready. The flow runs `claude update` first with a spinner, then downloads and installs the latest Pilot Shell. Pass `--skip-claude` to update only Pilot Shell, or `--yes` to skip the confirmation prompt.
-:::
+| `pilot activate <key>` | Activate a license key on this machine |
+| `pilot deactivate` | Deactivate license on this machine |
+| `pilot status [--json]` | Show current license status and tier |
+| `pilot verify [--json]` | Verify license validity (used by hooks) |
+| `pilot trial --check [--json]` | Check trial eligibility for this machine |
+| `pilot trial --start [--json]` | Start a trial (one-time per machine) |
 
-## Bot mode
+## Updates
 
 | Command | Description |
 |---------|-------------|
-| `pilot bot` | Launch Pilot Bot — persistent automation session with scheduled tasks, background jobs, and optional Telegram |
+| `pilot update [--yes] [--json]` | Update Pilot Shell. `pilot upgrade` is an alias. Pass `--yes` to skip the confirmation prompt. |
+| `pilot --version` | Show Pilot Shell version |
+
+Update Claude Code and Codex CLI through their own installers independently — `pilot update` only updates Pilot Shell itself.
 
 ## Worktree isolation
 
+Used by the `/spec` workflow to keep work isolated until verification passes. All commands work with both Claude Code and Codex sessions.
+
 | Command | Description |
 |---------|-------------|
 | `pilot worktree create --json <slug>` | Create isolated git worktree |
@@ -53,71 +46,36 @@ Run `pilot update` (or its `pilot upgrade` alias — both verbs are interchangea
 | `pilot worktree status --json` | Show active worktree info for current session |
 
 :::info Slug format
-The `<slug>` for worktree commands is the plan filename without the date prefix and `.md` extension. Example: `docs/plans/2026-02-22-add-auth.md` → `add-auth`.
+The `<slug>` is the plan filename without the date prefix and `.md` extension. Example: `docs/plans/2026-02-22-add-auth.md` → `add-auth`.
 :::
 
-## License & auth
+## Bot mode *(Claude Code only)*
 
 | Command | Description |
 |---------|-------------|
-| `pilot activate <key>` | Activate a license key on this machine |
-| `pilot deactivate` | Deactivate license on this machine |
-| `pilot status [--json]` | Show current license status and tier |
-| `pilot verify [--json]` | Verify license validity (used by hooks) |
-| `pilot trial --check [--json]` | Check trial eligibility for this machine |
-| `pilot trial --start [--json]` | Start a trial (one-time per machine) |
+| `pilot bot` | Launch [Pilot Bot](/docs/features/bot) — persistent automation session with scheduled tasks, background jobs, and optional Telegram |
 
 ## Customization (Team / Enterprise)
 
 Compose custom steps into core workflow skills and ship team rules, hooks, and agents. Source is either a git URL (team-wide) or a local directory (personal). See [Customization](/docs/features/customization) for the full overlay schema.
 
 | Command | Description |
 |---------|-------------|
-| `pilot customize install <source> [--branch <b>] [--subfolder <p>] [--json]` | Install and apply. `<source>` = git URL or local directory path. `--branch` applies to git sources only. |
+| `pilot customize install <source> [--branch <b>] [--subfolder <p>] [--json]` | Install and apply. `<source>` = git URL or local directory path. |
 | `pilot customize update [--json]` | Re-apply — pulls git sources, reads local sources in place |
 | `pilot customize status [--json]` | Show active source, file counts, and drift warnings |
 | `pilot customize diff <skill>/<step-id> [--json]` | Unified diff between pinned replacement and current upstream |
 | `pilot customize remove [--json]` | Delete pack files and regenerate pristine `SKILL.md` |
 
-## Claude CLI flag passthrough
-
-Pilot forwards any unrecognized flags directly to the Claude CLI — all current and future Claude Code flags work out of the box, no Pilot update required.
-
-```bash
-# Any Claude CLI flag works directly
-pilot --channels plugin:telegram@claude-plugins-official
-pilot --model opus --verbose
-pilot --resume
-pilot --continue
-
-# 'run' is an explicit alias — same behavior
-pilot run --channels plugin:telegram@claude-plugins-official
-```
-
-Pilot only intercepts its own subcommands (`activate`, `status`, `worktree`, etc.) and flags (`--version`, `--skip-update-check`). Everything else passes through to `claude`.
-
-## Headless mode
-
-Run Pilot non-interactively with `-p` (or `--print`). Wraps `claude -p` with license validation and the Pilot plugin — use it in CI/CD pipelines, scripts, or automated workflows.
-
-```bash
-# Basic usage
-pilot -p "What does the auth module do?"
+## Internal commands
 
-# Structured JSON output
-pilot -p "Summarize this project" --output-format json
+Called by hooks and the Console — you rarely need to run these directly.
 
-# Auto-approve specific tools
-pilot -p "Run tests and fix failures" --allowedTools "Bash,Read,Edit"
-
-# With channels
-pilot --channels plugin:telegram@claude-plugins-official -p "Check messages"
-
-# Continue a previous conversation
-pilot -p "Now focus on the database queries" --continue
-
-# Minimal startup (skip hooks, plugins, MCP auto-discovery)
-pilot -p "Summarize this file" --bare --allowedTools "Read"
-```
-
-All [Claude Code CLI flags](https://code.claude.com/docs/en/cli-reference) work with `-p`, including `--output-format`, `--allowedTools`, `--continue`, `--resume`, `--channels`, `--append-system-prompt`, `--json-schema`, and `--bare`. Pilot-specific flags like `--skip-update-check` are stripped automatically.
+| Command | Description |
+|---------|-------------|
+| `pilot check-context --json` | Get current context usage percentage |
+| `pilot register-plan <path> <status>` | Associate a plan file with the current session |
+| `pilot sessions [--json]` | Show count of active Pilot sessions |
+| `pilot statusline` | Status line formatter *(Claude Code only — called by Claude Code's statusLine hook)* |
+| `pilot notify <type> <title> <message> [--plan-path PATH] [--json]` | Send a notification to the Console dashboard (type: `info`, `plan_approval`, `attention_needed`, `verification_complete`) |
+| `pilot skill-build <skill-dir> [--output <path>] [--dry-run] [--json]` | Build `SKILL.md` and `hashes.json` from a skill's manifest + fragments |
diff --git a/docs/docusaurus/docs/features/console.md b/docs/docusaurus/docs/features/console.md
@@ -15,7 +15,7 @@ $ open http://localhost:41777
 ```
 
 :::tip Custom port
-The default port `41777` is configurable. Open the **Settings** tab and edit the **Console → Worker Port** field, then click **Save Port** (or edit `CLAUDE_PILOT_WORKER_PORT` in `~/.pilot/memory/settings.json` directly). Restart Pilot for the change to take effect — the launcher, status line, hooks (session_end, pre_compact, dashboard notifications), MCP server, and installer all read the same setting and will follow it.
+The default port `41777` is configurable. Open the **Settings** tab and edit the **Console → Worker Port** field, then click **Save Port** (or edit `CLAUDE_PILOT_WORKER_PORT` in `~/.pilot/memory/settings.json` directly). Restart your `claude` or `codex` session for the change to take effect.
 :::
 
 ## Views
@@ -25,15 +25,15 @@ Each view that supports project filtering has an inline **Project Filter** dropd
 | View | Description |
 |------|-------------|
 | **Dashboard** | Global command center — 8 clickable stat cards (Projects, Sessions, Active, Memories, Extensions, Requirements, Specifications, Changes), 4 recent-item cards with "Show all" links, active specs as pills in the top bar, notification bell in the top right. |
-| **Sessions** | Browse past sessions with search. Copy a session ID and run `/resume <session-id>` to jump back in — all context, files, and conversation history restored. |
+| **Sessions** | Browse past sessions with search. Copy a session ID and run `/resume <session-id>` in Claude Code to jump back in (Claude Code only). |
 | **Memories** | Observations (decisions, discoveries, bugfixes) with type filters and search. Each memory links back to the session it came from. |
 | **Requirements** | PRD documents with view/annotate modes. Selected opens as a tab, others live in a Previous dropdown. |
 | **Specifications** | Spec plans with task progress, phase tracking (PENDING/COMPLETE/VERIFIED), and iteration history. Hosts Plan Annotation and Spec Sharing (below). |
 | **Extensions** | All extensions — local, plugin, remote — with team sharing via git (push, pull, diff), color-coded categories, and scope filtering. |
 | **Changes** | Git diff viewer with staged/unstaged files, branch info, worktree context. Hosts Code Review and Spec Task Correlation (below). |
 | **Usage** | Daily token costs, model routing breakdown (Opus vs Sonnet), and usage trends. |
-| **Help** | Embedded pilot-shell.com documentation — full technical reference without leaving the Console. |
 | **Settings** | Spec workflow toggles (branch isolation, ask questions, plan approval, Model Switching), reviewer toggles. See [Settings](#settings) below. |
+| **Documentation** | Embedded pilot-shell.com documentation — full technical reference without leaving the Console. |
 
 ## Plan Annotation
 
@@ -94,36 +94,36 @@ The **+** button and text selection both work on the normal review page and on s
 
 ## Notifications
 
-The Console sends real-time alerts via Server-Sent Events when Claude needs your input or a significant phase completes — no need to watch the terminal.
+The Console sends real-time alerts via Server-Sent Events when your agent needs input or a significant phase completes — no need to watch the terminal.
 
 - Plan requires your approval — review and respond
 - Spec phase completed — implementation done, verification starting
-- Clarification needed — Claude is waiting for design decisions
+- Clarification needed — the agent is waiting for design decisions
 - Session ended — completion summary with observation count
 
 ## Settings
 
-The Settings tab (`localhost:41777/#/settings`, or your custom port) is a single scrollable page with two stacked sections: **Spec Workflow** and **Console**. Toggle preferences save to `~/.pilot/config.json`. The **Console → Worker Port** field saves to `~/.pilot/memory/settings.json` and lets you move the Console off `41777` if it conflicts with another service. Both changes take effect after restarting Pilot.
+The Settings tab (`localhost:41777/#/settings`, or your custom port) is a single scrollable page with two stacked sections: **Spec Workflow** and **Console**. Toggle preferences save to `~/.pilot/config.json`. The **Console → Worker Port** field saves to `~/.pilot/memory/settings.json` and lets you move the Console off `41777` if it conflicts with another service. Both changes take effect after restarting your session.
 
-:::info Model selection lives in Claude Code
-Pilot doesn't manage model preferences — pick your model with `/model sonnet[1m]`, `/model opus[1m]`, or an explicit Anthropic ID like `/model claude-opus-4-6`. See [Model Routing](./model-routing.md) for the recommended flow.
+:::info Model selection lives in the agent
+Pilot doesn't manage model preferences. Set the model with Claude Code's `/model` command or Codex's `codex --model <name>` / `~/.codex/config.toml`. See [Model Routing](./model-routing.md).
 :::
 
 ### Spec Workflow → Review Agents
 
-Two Claude sub-agents run in separate context windows during `/spec`. Toggle each on or off; the sub-agent model is hard-coded to Sonnet because sub-agents do not support 1M context.
+Two review agents run during `/spec` on Claude Code and Codex. Toggle each on or off; Claude Code runs them as Claude sub-agents, and Codex runs them as managed custom agents installed under `~/.codex/agents/`.
 
 | Agent | Default | Role |
 |-------|---------|------|
 | **Spec Review** | On | Validates plans before implementation. Checks alignment with requirements, flags risky assumptions. |
 | **Changes Review** | On | Reviews code after implementation. Checks compliance, security, test coverage, goal achievement. |
 
-**Codex adversarial reviewers (optional)** — OpenAI Codex agents that provide an independent second opinion.
+**Codex Companion Reviewers (optional, Claude Code only)** — OpenAI Codex plugin reviewers that provide an independent second opinion while you are working inside Claude Code.
 
 | Agent | Default | Role |
 |-------|---------|------|
-| **Codex Spec Review** | Off | Adversarial plan review — second opinion before implementation. |
-| **Codex Changes Review** | Off | Adversarial code review — second opinion after implementation. |
+| **Codex Companion Spec Review** | Off | Plugin plan review — second opinion before implementation. |
+| **Codex Companion Changes Review** | Off | Plugin code review — second opinion after implementation. |
 
 ### Spec Workflow → Automation
 
@@ -134,12 +134,12 @@ Four toggles control user interaction points during `/spec`. Disable all four fo
 | **Branch Isolation** | On | Asks how to isolate `/spec` changes (new branch or worktree) | Always works on the current branch |
 | **Ask Questions** | On | Asks clarifying questions during planning | Planning makes autonomous default choices |
 | **Plan Approval** | On | Requires your approval before implementation starts | Implementation begins automatically after planning |
-| **Model Switching** | On | Pauses after plan approval. Option A: run `/model sonnet[1m]`, type any prompt — resumes with planning context in the new model (Claude Code will confirm; carries extra cost). Option B: run `/clear` then `/spec <plan path>` — fresh session, lower cost. | Plan → implement → verify runs continuously on whichever model is active |
+| **Model Switching** *(Claude Code only)* | On | Pauses after plan approval. Option A: run `/model sonnet[1m]`, type any prompt — resumes with planning context in the new model. Option B: run `/clear` then `/spec <plan path>` — fresh session, lower cost. | Plan → implement → verify runs continuously on whichever model is active |
 
 With all four off, `/spec add user authentication` plans, implements, and verifies the feature end-to-end without checkpoints on whichever model is currently active.
 
 :::warning Token usage in autonomous mode
-No checkpoints means Claude executes the entire workflow without asking. Make sure your prompt is specific enough to avoid misinterpretation. You can always interrupt with Escape.
+No checkpoints means your agent executes the entire workflow without asking. Make sure your prompt is specific enough to avoid misinterpretation. You can always interrupt with Escape.
 :::
 
 ### Config file
@@ -165,4 +165,4 @@ All settings are stored in `~/.pilot/config.json`:
 }
 ```
 
-You can edit `~/.pilot/config.json` directly — the Settings UI is a convenience wrapper. Changes require a Claude Code restart.
+You can edit `~/.pilot/config.json` directly — the Settings UI is a convenience wrapper. Changes take effect after restarting your session.