@nexus-cortex/cli 4.33.0 → 4.34.0

package/docs/architecture.md

@@ -1,203 +0,0 @@
-# Nexus Cortex — Architecture
-
-How the harness fits together: the monorepo layout, the orchestrator, the provider/tool/
-middleware systems, and the other core subsystems. For usage see the [User Guide](user-guide.md).
-
-## Monorepo structure
-
-```
-nexus-cortex/
-├── packages/
-│   ├── types/              # Shared TypeScript types (zero runtime deps)
-│   ├── core/               # Core orchestration library
-│   │   ├── orchestrator/   # CortexOrchestrator (main engine) + sub-agents
-│   │   ├── adapters/       # Format adapters (Messages, ChatCompletions, …)
-│   │   ├── models/         # Model registry (per-provider model cards)
-│   │   ├── tools/          # Tool definitions & registries
-│   │   ├── middleware/     # System-message, permissions, retry, mentorship, …
-│   │   ├── training/       # Auto-research: experiments, router matrix, gate
-│   │   ├── mcp/            # MCP client & server integration
-│   │   ├── system-messages/# System message auto-loading
-│   │   └── session/        # JSONL session storage
-│   ├── executors/          # Tool execution implementations
-│   ├── server/             # Express HTTP server (optional)
-│   │   └── routes/         # REST API endpoints
-│   └── cli/                # Headless cortex CLI
-└── scripts/                # Build and maintenance scripts
-```
-
-### Package build order
-
-A strict order, because core and executors form a circular dependency broken by a two-pass
-build (handled by `scripts/build.sh`):
-
-1. **types** — shared types (zero deps)
-2. **executors** — partial build (core imports fail; expected)
-3. **core** — depends on types
-4. **executors** — complete build (core now available)
-5. **server** — depends on core
-6. **cli** — headless `cortex` (depends on core)
-7. **tui** — interactive React/Ink + Chalk UIs (Release 2 — not yet published)
-
-Always build from the repo root: `npm run build`.
-
-### Direct-wired vs server mode
-
-**Direct mode (default)** — the core library is imported directly into the CLI process: zero
-network overhead, immediate access to all orchestrator features, single-process debugging.
-
-**Server mode (optional)** — an HTTP server exposes the REST API for web/mobile/remote clients
-and multi-client use.
-
-## Core systems
-
-### Cortex Orchestrator
-
-The orchestrator coordinates every AI interaction, tool execution, and session update. A
-single `processMessage` turn handles periodic review, keyword detection, system-message
-injection, context budgeting, model selection, the API call (with retry and context-rejection
-compaction), the tool-calling loop (with loop detection and orphaned-tool recovery), cache-
-metric extraction, and session persistence.
-
-```typescript
-import { CortexOrchestrator } from '@nexus-cortex/core';
-
-const orchestrator = new CortexOrchestrator({
-  modelId: 'claude-sonnet-4-6',
-  projectPath: process.cwd(),
-  mcpAutoInject: true,
-});
-
-const response = await orchestrator.processMessage({ role: 'user', content: 'Analyze this codebase' });
-```
-
-### Multi-provider system
-
-Providers are reached through a pluggable adapter layer (Messages, Chat Completions,
-GenerateContent, GenAI, Responses). Each provider is enabled by its API key. The **five major
-labs are proven end-to-end** (driven hard through the full tool loop, sub-agents, caching, and
-the benchmark harness); the smaller labs (Cloudflare Workers AI, Zhipu/GLM, Qwen, Moonshot/Kimi,
-MiniMax, Mercury) are incorporated through the same adapters but treated as preview.
-
-**Run `cortex models list` for the live, exact set** — and `cortex models providers` for the
-provider list with the API-key variable each needs.
-
-### Tool system
-
-A dual registry — immutable base tools + dynamic addon tools — plus any tools discovered from
-connected MCP servers, all with read-before-edit safety. Categories: file & notebook, search,
-shell (foreground + background), web & browser, sub-agents, git & PR, sandboxed artifacts with
-React introspection, conversation history, MCP/tool discovery, planning & UI, code & monitoring,
-auto-research, skills & commands, and an opt-in end-of-turn audit.
-
-**Run `cortex tools list` for the live, authoritative set with descriptions.**
-
-### System message management
-
-System messages auto-load from `.cortex/CORTEX.md` (project context) and numbered files under
-`.cortex/system-messages/`. `CORTEX.md` is generated on demand:
-
-```bash
-/init                                  # in the CLI
-# or programmatically:
-import { InitCortexContext } from '@nexus-cortex/core';
-await InitCortexContext.execute({ scope: 'auto', max_depth: 5 }, process.cwd());
-```
-
-It captures the project description, file tree, dependency analysis (npm/Python/Rust/Go),
-available scripts, and monorepo package structure.
-
-### MCP integration
-
-Full Model Context Protocol support. Manage via `cortex mcp …` (or `/mcp` in the UI); configure
-in `.cortex/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
-    }
-  }
-}
-```
-
-### Session management
-
-JSONL-based persistence with full state recovery: append-only JSONL in `.cortex/sessions/`,
-UUID message IDs (zero collision risk), content-addressable file checkpoints in
-`.cortex/file-history/`, helper-model auto-compaction at a configurable token threshold, and
-optional auto-resume on server start.
-
-### Sandboxed artifacts & visual workspace
-
-`CreateArtifactTool` spins up a runnable web/server app in a tmux-managed sandbox and the model
-iterates against it with real feedback: snapshots (screenshot/DOM/console/network/accessibility),
-interaction (click/type/navigate), hot-reload edits, and file transfer. React artifacts build
-from a single component (CDN or esbuild-bundled), with React-aware introspection senses
-(component tree, props, render-trace).
-
-### Sub-agents (Task)
-
-The `Task` tool dispatches work to isolated sub-agents that run in parallel, each with its own
-permission scope. Sub-agents are profiles under `.cortex/agents/*.md` (YAML frontmatter +
-instructions; project agents override personal `~/.cortex/agents/`). Set `AGENT_TMUX_MONITOR=true`
-for a live tmux pane per agent.
-
-### Auto-research (closed-loop improvement)
-
-A closed-loop experiment runner that measures a change before keeping it: build a **baseline**
-and a **candidate**, benchmark both on a graded task set, and gate a keep/discard verdict with
-real statistics (Monte-Carlo: bootstrap CI + permutation + N-aware significance, plus a held-out
-check). Inspired by [karpathy/autoresearch](https://github.com/karpathy/autoresearch). Driven by
-`cortex autoresearch` (`bench` / `experiment` / `evaluate` / `fix` / `list`). Its first
-application is the harness improving itself; the loop generalizes to other developmental-
-improvement experiments.
-
-### Permission system
-
-Tool execution is gated by a policy engine with three environment profiles in `.cortex/`
-(`permissions.dev.json` / `.test.json` / `.prod.json`) and four policy types — whitelist,
-blacklist, file-operation, bash-command — with audit logging. `YOLO=true` bypasses all of it.
-Manage at runtime via `cortex permissions …`.
-
-### Model router & reactive mentorship
-
-- **Model router** (opt-in, `MODEL_ROUTER_ENABLED`) routes `model="auto"` requests to the best
-  model for the task type using recorded benchmark history, with a multi-entry exclude list
-  (`MODEL_ROUTER_EXCLUDE`).
-- **Reactive mentorship** (opt-in, `MENTORSHIP_ENABLED`) is an AI-to-AI self-improvement loop
-  that triggers helper-model review on errors, keywords (`@ultrathink` / `@analyze` / `@rethink`),
-  turn intervals, or repeated failure patterns.
-
-## Power-user surfaces
-
-Beyond the core loop, the harness ships surfaces you'd otherwise build yourself:
-
-- **Visual agent monitoring (tmux).** Parallel sub-agents each in a live tmux pane
-  (`AGENT_TMUX_MONITOR`), plus an opt-in dashboard (`ENABLE_DASHBOARD=true`) to watch sandbox +
-  tmux sessions.
-- **Git PR agent.** `PRAgent` runs review/create/list pipelines (and `/v1/pr/*` routes), shelling
-  out safely (`execFile`, no shell) behind an opt-in repo/action allow-list and an HMAC-verified
-  webhook.
-- **Isolated git worktrees.** `WorkspaceManager` hands each agent a clean worktree (clone → branch
-  → work → cleanup) so parallel agents never clobber each other.
-- **Helper-model middleware.** A cheaper secondary model auto-compacts the conversation near the
-  context limit — *compaction first, windowing last*.
-- **Session summarization + next-action prediction.** `TURN_SUMMARY_PREDICTION` emits a post-turn
-  summary and predicted next action — handy for agent-team handoffs and autonomy loops.
-- **Deferred tool loading.** Expose only essential tools up front and let the model discover the
-  rest via `SearchTools` — a large first-turn input-token cut on big tool sets.
-
-## Extending
-
-**New tool** — define it in `packages/core/src/tools/`, add it to `BaseToolRegistry`, implement
-the executor in `packages/executors/src/implementations/`, register it in `ExecutorRegistry`,
-and rebuild.
-
-**New provider** — implement a `FormatAdapter` in `packages/core/src/adapters/`, register it in
-`AdapterRegistry`, add model cards under `packages/core/src/models/cards/`, and update the model
-registry.
-
-See `packages/*/CLAUDE.md` for per-package reading lists and the exact wiring.

package/docs/assets/nexus-cortex-hero.svg

@@ -1,140 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="688" height="543" viewBox="0 0 688 543" role="img" aria-label="Nexus Cortex">
-<rect width="688" height="543" rx="12" fill="#070707"/>
-<g transform="translate(27.7,0) scale(1.15,1)" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="16" xml:space="preserve">
-<text x="106.2" y="37" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="212.3" y="37" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="270.2" y="37" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="328.1" y="37" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="434.2" y="37" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="106.2" y="56" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="212.3" y="56" textLength="38.60" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╰──╮</text>
-<text x="270.2" y="56" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="299.2" y="56" textLength="38.60" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╭──╯</text>
-<text x="434.2" y="56" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="67.5" y="75" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="77.2" y="75" textLength="38.60" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">───╯</text>
-<text x="135.1" y="75" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="144.8" y="75" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">──╮</text>
-<text x="241.2" y="75" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="270.2" y="75" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="299.2" y="75" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="376.4" y="75" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╭──</text>
-<text x="405.3" y="75" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="434.2" y="75" textLength="38.60" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╰───</text>
-<text x="472.9" y="75" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="164.1" y="94" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╰─╮</text>
-<text x="241.2" y="94" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="270.2" y="94" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="299.2" y="94" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="357.1" y="94" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╭─╯</text>
-<text x="106.2" y="113" textLength="337.75" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">╭───────┴─────┴──┴──┴─────┴───────╮</text>
-<text x="67.5" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="77.2" y="132" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">───</text>
-<text x="106.2" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">┤</text>
-<text x="115.8" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">■</text>
-<text x="183.3" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">▀</text>
-<text x="241.2" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">▀</text>
-<text x="270.2" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">▀</text>
-<text x="299.2" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">▀</text>
-<text x="357.1" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">▀</text>
-<text x="424.6" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">■</text>
-<text x="434.2" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">├</text>
-<text x="443.9" y="132" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">───</text>
-<text x="472.9" y="132" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="106.2" y="151" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">│</text>
-<text x="144.8" y="151" textLength="260.55" lengthAdjust="spacingAndGlyphs" fill="#F8F8F2">╔═════════════════════════╗</text>
-<text x="434.2" y="151" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">│</text>
-<text x="67.5" y="170" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="77.2" y="170" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">───</text>
-<text x="106.2" y="170" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">┤</text>
-<text x="115.8" y="170" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">■</text>
-<text x="144.8" y="170" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#F8F8F2">║</text>
-<text x="395.7" y="170" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#F8F8F2">║</text>
-<text x="424.6" y="170" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">■</text>
-<text x="434.2" y="170" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">├</text>
-<text x="443.9" y="170" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">───</text>
-<text x="472.9" y="170" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="106.2" y="189" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">│</text>
-<text x="144.8" y="189" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#F8F8F2">║</text>
-<text x="395.7" y="189" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#F8F8F2">║</text>
-<text x="434.2" y="189" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">│</text>
-<text x="67.5" y="208" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="77.2" y="208" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">───</text>
-<text x="106.2" y="208" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">┤</text>
-<text x="115.8" y="208" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">■</text>
-<text x="144.8" y="208" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#F8F8F2">║</text>
-<text x="395.7" y="208" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#F8F8F2">║</text>
-<text x="424.6" y="208" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">■</text>
-<text x="434.2" y="208" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">├</text>
-<text x="443.9" y="208" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">───</text>
-<text x="472.9" y="208" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="106.2" y="227" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">│</text>
-<text x="144.8" y="227" textLength="260.55" lengthAdjust="spacingAndGlyphs" fill="#F8F8F2">╚═════════════════════════╝</text>
-<text x="434.2" y="227" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">│</text>
-<text x="67.5" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="77.2" y="246" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">───</text>
-<text x="106.2" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">┤</text>
-<text x="115.8" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">■</text>
-<text x="183.3" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">▄</text>
-<text x="241.2" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">▄</text>
-<text x="270.2" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">▄</text>
-<text x="299.2" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">▄</text>
-<text x="357.1" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">▄</text>
-<text x="424.6" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#FD971F">■</text>
-<text x="434.2" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">├</text>
-<text x="443.9" y="246" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">───</text>
-<text x="472.9" y="246" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="106.2" y="265" textLength="337.75" lengthAdjust="spacingAndGlyphs" fill="#AE81FF">╰───────┬─────┬──┬──┬─────┬───────╯</text>
-<text x="164.1" y="284" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╭─╯</text>
-<text x="241.2" y="284" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="270.2" y="284" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="299.2" y="284" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="357.1" y="284" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╰─╮</text>
-<text x="67.5" y="303" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="77.2" y="303" textLength="38.60" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">───╮</text>
-<text x="135.1" y="303" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="144.8" y="303" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">──╯</text>
-<text x="241.2" y="303" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="270.2" y="303" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="299.2" y="303" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="376.4" y="303" textLength="28.95" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╰──</text>
-<text x="405.3" y="303" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="434.2" y="303" textLength="38.60" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╭───</text>
-<text x="472.9" y="303" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="106.2" y="322" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="212.3" y="322" textLength="38.60" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╭──╯</text>
-<text x="270.2" y="322" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="299.2" y="322" textLength="38.60" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">╰──╮</text>
-<text x="434.2" y="322" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#E6DB74">│</text>
-<text x="106.2" y="341" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="212.3" y="341" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="270.2" y="341" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="328.1" y="341" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-<text x="434.2" y="341" textLength="9.65" lengthAdjust="spacingAndGlyphs" fill="#A6E22E">●</text>
-</g>
-<g transform="translate(225.4,201.7) scale(0.05244,-0.05244)" fill="#66D9EF">
-<path transform="translate(0.0,0)" d="M56 0V720H216L619 240V720H776V0H616L211 482V0Z"/>
-<path transform="translate(946.4,0)" d="M58 0V720H723V564H215V438H624V282H215V156H723V0Z"/>
-<path transform="translate(1826.8,0)" d="M46 0V53L303 360L46 667V720H207L407 483L605 720H766V667L508 360L766 54V0H605L405 236L207 0Z"/>
-<path transform="translate(2753.2,0)" d="M202 0Q161.5 0 127.75 20.0Q94 40 74.0 73.75Q54 107.5 54 148V720H209V156Q209 156 209.0 156.0Q209 156 209 156H617Q617 156 617.0 156.0Q617 156 617 156V720H774V148Q774 107.5 753.5 73.75Q733 40 699.5625 20.0Q666.125 0 626 0H202Z"/>
-<path transform="translate(3695.7,0)" d="M202 0Q161.5 0 127.75 20.0Q94 40 74.0 73.75Q54 107.5 54 148V215H209V156Q209 156 209.0 156.0Q209 156 209 156H617Q617 156 617.0 156.0Q617 156 617 156V282Q617 282 617.0 282.0Q617 282 617 282H202Q161.5 282 127.75 302.0Q94 322 74.0 355.51724137931035Q54 389.0344827586207 54 430V572Q54 612.5 74.0 646.25Q94 680 127.75 700.0Q161.5 720 202 720H626Q666.125 720 699.5625 700.0Q733 680 753.5 646.25Q774 612.5 774 572V505H617V564Q617 564 617.0 564.0Q617 564 617 564H209Q209 564 209.0 564.0Q209 564 209 564V438Q209 438 209.0 438.0Q209 438 209 438H626Q666.125 438 699.5625 418.0Q733 398 753.5 364.48275862068965Q774 330.9655172413793 774 290V148Q774 107.5 753.5 73.75Q733 40 699.5625 20.0Q666.125 0 626 0Z"/>
-</g>
-<g transform="translate(70.0,460.8) scale(0.10911,-0.10911)" fill="#8F6A00">
-<path transform="translate(0.0,0)" d="M204 0Q163 0 129.5 20.0Q96 40 76.0 73.5Q56 107 56 148V572Q56 613 76.0 646.5Q96 680 129.5 700.0Q163 720 204 720H774V564H244Q228 564 219.5 556.0Q211 548 211 531V189Q211 173 219.5 164.5Q228 156 244 156H774V0Z"/>
-<path transform="translate(877.0,0)" d="M202 0Q161.5 0 127.75 20.0Q94 40 74.0 73.75Q54 107.5 54 148V572Q54 612.5 74.0 646.25Q94 680 127.75 700.0Q161.5 720 202 720H626Q666.125 720 699.5625 700.0Q733 680 753.5 646.25Q774 612.5 774 572V148Q774 107.5 753.5 73.75Q733 40 699.5625 20.0Q666.125 0 626 0ZM209 156H617Q617 156 617.0 156.0Q617 156 617 156V564Q617 564 617.0 564.0Q617 564 617 564H209Q209 564 209.0 564.0Q209 564 209 564V156Q209 156 209.0 156.0Q209 156 209 156Z"/>
-<path transform="translate(1760.0,0)" d="M615 0 406 249H609L775 53V0ZM56 0V719H627Q667.5 719 701.25 699.0Q735 679 755.5 645.0Q776 611 776 571V385Q776 345 755.5 311.0Q735 277 701.25 257.0Q667.5 237 627 237L211 236V0ZM211 393H619Q619 393 619.0 393.0Q619 393 619 393V564Q619 564 619.0 564.0Q619 564 619 564H211Q211 564 211.0 564.0Q211 564 211 564V393Q211 393 211.0 393.0Q211 393 211 393Z"/>
-<path transform="translate(2640.0,0)" d="M302 0V564H20V720H740V564H458V0Z"/>
-<path transform="translate(3454.0,0)" d="M58 0V720H723V564H215V438H624V282H215V156H723V0Z"/>
-<path transform="translate(4274.9,0)" d="M46 0V53L303 360L46 667V720H207L407 483L605 720H766V667L508 360L766 54V0H605L405 236L207 0Z"/>
-</g>
-<g transform="translate(66.5,457.3) scale(0.10911,-0.10911)" fill="#FFC600">
-<path transform="translate(0.0,0)" d="M204 0Q163 0 129.5 20.0Q96 40 76.0 73.5Q56 107 56 148V572Q56 613 76.0 646.5Q96 680 129.5 700.0Q163 720 204 720H774V564H244Q228 564 219.5 556.0Q211 548 211 531V189Q211 173 219.5 164.5Q228 156 244 156H774V0Z"/>
-<path transform="translate(877.0,0)" d="M202 0Q161.5 0 127.75 20.0Q94 40 74.0 73.75Q54 107.5 54 148V572Q54 612.5 74.0 646.25Q94 680 127.75 700.0Q161.5 720 202 720H626Q666.125 720 699.5625 700.0Q733 680 753.5 646.25Q774 612.5 774 572V148Q774 107.5 753.5 73.75Q733 40 699.5625 20.0Q666.125 0 626 0ZM209 156H617Q617 156 617.0 156.0Q617 156 617 156V564Q617 564 617.0 564.0Q617 564 617 564H209Q209 564 209.0 564.0Q209 564 209 564V156Q209 156 209.0 156.0Q209 156 209 156Z"/>
-<path transform="translate(1760.0,0)" d="M615 0 406 249H609L775 53V0ZM56 0V719H627Q667.5 719 701.25 699.0Q735 679 755.5 645.0Q776 611 776 571V385Q776 345 755.5 311.0Q735 277 701.25 257.0Q667.5 237 627 237L211 236V0ZM211 393H619Q619 393 619.0 393.0Q619 393 619 393V564Q619 564 619.0 564.0Q619 564 619 564H211Q211 564 211.0 564.0Q211 564 211 564V393Q211 393 211.0 393.0Q211 393 211 393Z"/>
-<path transform="translate(2640.0,0)" d="M302 0V564H20V720H740V564H458V0Z"/>
-<path transform="translate(3454.0,0)" d="M58 0V720H723V564H215V438H624V282H215V156H723V0Z"/>
-<path transform="translate(4274.9,0)" d="M46 0V53L303 360L46 667V720H207L407 483L605 720H766V667L508 360L766 54V0H605L405 236L207 0Z"/>
-</g>
-<text x="344.0" y="499" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13" letter-spacing="3" fill="#75715E">HEADLESS MULTI-PROVIDER AI AGENT HARNESS</text>
-<text x="344.0" y="521" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="12" fill="#75715E">Anthropic • OpenAI • Google • XAI • DeepSeek</text>
-</svg>

package/docs/authentication.md

@@ -1,95 +0,0 @@
-# Authentication & API Keys
-
-The easiest way to add a key is the interactive setup — it runs automatically the first
-time you start `cortex`, or any time on demand:
-
-```bash
-cortex config init
-```
-
-It asks which provider you use, takes your API key, and picks a default model — saving them
-to `~/.cortex/.env` (a global config, so `cortex` works from any folder). The file is written
-user-only (`chmod 600`) and is never committed.
-
-### Where config is read from
-
-Cortex loads, in priority order: a `.env` in your current folder → the package dir →
-`~/.cortex/.env` (the global config) → plain environment variables. So you can also just
-export a variable instead of using the wizard:
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-…
-export DEFAULT_MODEL_ID=claude-sonnet-4-6
-```
-
-> **Set a `DEFAULT_MODEL_ID` that matches your key.** The built-in default is a Gemini model,
-> so an Anthropic key alone won't be used until you also set the model (the wizard does this
-> for you).
-
-## Provider API keys
-
-| Variable | Provider | Example default model |
-|----------|----------|-----------------------|
-| `ANTHROPIC_API_KEY` | Claude (Anthropic) | `claude-sonnet-4-6` |
-| `OPENAI_API_KEY` | OpenAI (GPT / o-series) | `gpt-5-mini` |
-| `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) | Google Gemini | `gemini-2.5-flash` |
-| `XAI_API_KEY` | xAI (Grok) | `grok-4.3` |
-| `DEEPSEEK_API_KEY` | DeepSeek | `deepseek-v4-pro` |
-
-Other providers (Cloudflare Workers AI, Zhipu/GLM, Qwen, Moonshot/Kimi, MiniMax, Mercury)
-use the same pattern. Run `cortex models list` for the live set.
-
-## Claude: API key *or* OAuth
-
-Claude works two ways — pick one:
-
-- **API key** — set `ANTHROPIC_API_KEY=sk-ant-…` in `.env`. Done.
-- **OAuth** — use a Claude.ai Pro/Max subscription instead of a metered API key (below).
-
-You can pin the method with `ANTHROPIC_AUTH_METHOD=auto|oauth|api-key` (default `auto`).
-The resolution order under `auto` is:
-
-```
-~/.claude/.credentials.json  →  CLAUDE_CODE_OAUTH_TOKEN  →  ANTHROPIC_API_KEY
-```
-
-### Claude OAuth setup
-
-There are two ways to provide the OAuth token; the harness checks them in this order.
-
-**1. `~/.claude/.credentials.json` (preferred)**
-
-This file is created automatically when you sign in with the Claude Code CLI:
-
-```bash
-claude login
-```
-
-If you've already done that, the harness reads it as-is — nothing else to do. It lives in
-your home directory (not the project), is written owner-only (`chmod 600`), and includes a
-refresh token so it renews itself.
-
-To create it by hand instead:
-
-```bash
-mkdir -p ~/.claude && chmod 700 ~/.claude
-cat > ~/.claude/.credentials.json <<'JSON'
-{ "claudeAiOauth": {
-    "accessToken": "sk-ant-oat01-…",
-    "refreshToken": "sk-ant-ort01-…",
-    "expiresAt": 1765400000000,
-    "scopes": ["user:inference"] } }
-JSON
-chmod 600 ~/.claude/.credentials.json
-```
-
-**2. `CLAUDE_CODE_OAUTH_TOKEN` (headless / CI)**
-
-Set a bare token in `.env` (or the environment) — handy where there's no `claude login`:
-
-```bash
-CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-…
-```
-
-The OAuth token is **never** written to any project file — keep it in the home-directory
-credentials file or in `.env`, both of which stay outside version control.

package/docs/configuration.md

@@ -1,185 +0,0 @@
-# Configuration reference
-
-Every Nexus Cortex setting is an environment variable, read from `.env` (or the process environment) at startup.
-
-> **Canonical sources:** [`.env.example`](../.env.example) is the annotated template, and `packages/core/src/config/SettingsSchema.ts` is the schema (defaults + valid choices). This page mirrors them for browsing — if anything here disagrees, those win.
-
-Per-launch overrides win — e.g. `DEFAULT_MODEL_ID=grok-4.3 PORT=4100 node packages/server/dist/index.js`. Booleans are the literal strings `true`/`false`. Only API keys are required; every other variable has a proven-optimal default.
-
-#### API keys & authentication
-
-Set the keys for the providers you use; leave the rest blank. A model is only available if its provider key is present.
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `ANTHROPIC_API_KEY` | — | Claude (Fable/Opus/Sonnet/Haiku) models. |
-| `OPENAI_API_KEY` | — | GPT / o-series models. |
-| `GOOGLE_API_KEY` | — | Gemini models (legacy key; `GEMINI_API_KEY` takes priority). |
-| `GEMINI_API_KEY` | — | Preferred Gemini key; falls back to `GOOGLE_API_KEY`. |
-| `XAI_API_KEY` | — | xAI Grok models. |
-| `DEEPSEEK_API_KEY` | — | DeepSeek models (the default model's provider). |
-| `NVIDIA_API_KEY` | — | Reserved for NVIDIA-hosted models (no standalone NVIDIA cards are registered yet; NVIDIA models are currently reached via Cloudflare). |
-| `INCEPTION_API_KEY` | — | Inception Labs Mercury diffusion models (`mercury-2`). |
-| `CLOUDFLARE_API_TOKEN` | — | Cloudflare Workers AI (`@cf/*` models). Requires `CLOUDFLARE_ACCOUNT_ID`. |
-| `CLOUDFLARE_ACCOUNT_ID` | — | Cloudflare account ID (paired with the token above). |
-| `DASHSCOPE_API_KEY` | — | Alibaba Qwen (DashScope) — `qwen-*` models. |
-| `MINIMAX_API_KEY` | — | MiniMax — `minimax-*` models. |
-| `MOONSHOT_API_KEY` | — | Moonshot AI (Kimi) — `moonshot-*` / `kimi-*` models. |
-| `ZHIPU_API_KEY` | — | Zhipu AI (GLM) — `glm-*` models. |
-| `HUGGINGFACE_API_KEY` | — | Reserved for Hugging Face Inference (`HUGGINGFACE_TOKEN` also accepted; cards exist but are not registered in the default build yet). |
-| `ANTHROPIC_AUTH_METHOD` | `auto` | `auto` (oauth→key) \| `oauth` \| `api-key`. `.env.example` ships `api-key`; use `oauth` with a Claude.ai Max subscription. |
-| `CLAUDE_CODE_OAUTH_TOKEN` | — | OAuth token override (alternative to `~/.claude/.credentials.json`). |
-
-#### Model selection
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `DEFAULT_MODEL_ID` | `deepseek-v4-pro` | Primary model — any registry ID or alias (`cortex models list`). |
-| `HELPER_MODEL_ID` | `deepseek-v4-flash` | Cheaper model for compaction & mentorship. |
-| `WEB_TOOLS_MODEL` | `gemini-2.5-flash` | Model backing `WebSearch`/`WebFetch`; provider auto-detected from the ID prefix. |
-
-#### System
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `DEBUG` | `false` | Verbose logging (system-message assembly, routes). Toggle at runtime via `/debug`. |
-| `USE_EMOJI` | `false` | Allow emoji in CLI output. |
-| `PROJECT_PATH` | cwd | Project root the tools operate on. |
-| `PROJECT_ROOT` | `PROJECT_PATH`/cwd | Explicit override of the project root (set by the server at startup). |
-
-#### Reactive mentorship (AI-to-AI self-improvement)
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `MENTORSHIP_ENABLED` | `false` | Master switch for the mentorship system. |
-| `MENTORSHIP_TRIGGER_ON_ERROR` | `true` | Trigger helper-model review on tool errors (only applies when mentorship is enabled). |
-| `MENTORSHIP_ERROR_THRESHOLD` | `medium` | Minimum severity to trigger: `low` \| `medium` \| `high`. |
-| `MENTORSHIP_KEYWORDS_ENABLED` | `false` | React to `@ultrathink` / `@analyze` / `@rethink`. |
-| `MENTORSHIP_CUSTOM_KEYWORDS` | — | Comma-separated extra trigger keywords. |
-| `MENTORSHIP_HELPER_MODEL` | `deepseek-v4-flash` | Model used for mentorship, overriding `HELPER_MODEL_ID` (`.env.example` ships a Cloudflare Gemma override). |
-| `MENTORSHIP_TURN_BASED_ENABLED` | `false` | Periodic review every N turns. |
-| `MENTORSHIP_TURN_INTERVAL` | `10` | Turns between periodic reviews (1–50). |
-| `MENTORSHIP_INTERLEAVED_THINKING` | `false` | Inject thinking for non-reasoning models. |
-| `MENTORSHIP_PATTERN_DETECTION` | `false` | Detect repeated failure patterns. |
-| `MENTORSHIP_PATTERN_THRESHOLD` | `3` | Similar errors needed to flag a pattern (2–10). |
-| `MENTORSHIP_ACTIVE_DISCOVERY` | `false` | Proactive mentorship discovery (runtime flag). |
-| `TURN_SUMMARY_PREDICTION` | `false` | Post-turn summary + next-action prediction via the helper model. |
-
-#### Context management
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `ANTHROPIC_PROMPT_CACHING` | `true` | Enable Anthropic prompt caching (up to ~90% input-token savings). |
-| `CONTEXT_BUDGET_STRATEGY` | `priority-based` | `priority-based` (keeps tool pairs) or `sliding-window` (dumb recency). |
-
-#### Session
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `SESSION_STORAGE_DIR` | `.cortex/sessions` | Where JSONL session files are written. |
-| `MCP_AUTO_INJECT` | `false` | Auto-inject connected MCP servers' tools into every turn. |
-| `SYSTEM_MESSAGE_DOC_MAX_BYTES` | `0` | Per-doc byte cap for injected project docs (CORTEX.md, MEMORY.md). `0` = unlimited. |
-
-#### Loop control
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `MAX_TOOL_ITERATIONS` | `50` | Max tool executions per turn. |
-| `MAX_CONSECUTIVE_ERRORS` | `3` | Stop the turn after this many consecutive all-error iterations. |
-| `TOOL_BUDGET_SOFT` | `15` | Soft per-turn tool-call budget (decisiveness brake). |
-| `TOOL_TIMEOUT_MS` | `120000` | Per-tool execution timeout (ms). |
-| `MAX_LOOP_REPETITIONS` | `5` | Identical tool calls before loop detection breaks the turn. |
-
-#### Provider tooling
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `ENABLE_SERVER_SIDE_TOOLS` | `true` | xAI/OpenAI hosted server-side tools (hybrid is ~20–26% faster). |
-| `XAI_API_MODE` | `messages` | xAI request surface: `messages` (CC-style) or `responses` (server-side tools). |
-| `OPENAI_API_MODE` | `chat/completions` | OpenAI request surface: `chat/completions` or `responses` (opt into hosted server-side tools). |
-| `ENABLE_DEFERRED_TOOL_LOADING` | `true` | Load only essential tools up front; discover the rest via `SearchTools` (~77% first-turn input-token cut). |
-| `ENABLE_PTC` | `false` | Programmatic tool calling (compose tool calls in a script). |
-| `ENABLE_LOCAL_CODE_EXECUTION` | `false` | Allow local code-execution tooling. |
-
-#### Model router (auto model selection)
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `MODEL_ROUTER_ENABLED` | `false` | Auto-route `model="auto"` requests from benchmark history. |
-| `MODEL_ROUTER_STRATEGY` | `auto` | `auto` (classify the prompt) or `matrix-only` (require an explicit task type). |
-| `MODEL_ROUTER_RECORD` | `true` | Record turn metrics to `.cortex/router-matrix.jsonl` (independent of routing being on). |
-| `MODEL_ROUTER_EXCLUDE` | `grok*` | Comma list of model IDs the router must never pick; trailing `*` = prefix wildcard. |
-| `MODEL_ROUTER_EXPLORATION` | `false` | Posterior-sampling explore/exploit instead of a greedy pick. |
-| `ROUTER_MIN_CONFIDENCE` | `0.3` | Min task-classification confidence (0–1) before `auto` routes; below it, inherit the parent model. |
-| `ROUTER_MIN_SAMPLES` | `3` | Min benchmark samples a task type needs before `auto` trusts its recommendation. |
-
-#### End-of-turn audit / training substrate (opt-in)
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `CORTEX_ENDTURN_GATE` | `false` | `true` = mandatory `EndTurn` self-audit + graded training records. Off = the tool is hidden. |
-
-#### Decision store (prior recall)
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `CORTEX_RECORD_DECISIONS` | `true` | Append each tool decision to `.cortex/decisions.jsonl`. |
-| `CORTEX_LOOKUP_PRIOR_DECISIONS` | `true` | Inject prior decisions as a `<system-reminder>` before tool use. |
-| `CORTEX_DECISIONS_MAX_BYTES` | `2097152` | Rotation cap (bytes) for `decisions.jsonl` (default 2 MB). |
-| `CORTEX_GIT_CONTEXT` | `true` | Per-turn "Repository State" note (branch/status/recent commits + cross-agent staleness warnings). |
-
-#### Orchestrator mode
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `CORTEX_MODE` | `persistent` | `persistent` \| `stateless` (clean per request) \| `server` (HTTP client). |
-| `CORTEX_SERVER_URL` | `http://localhost:4000` | Server endpoint when `CORTEX_MODE=server`. |
-
-#### Agent workspace
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `AGENT_TMUX_MONITOR` | `false` | tmux visual monitoring for parallel agent teams (one live pane per agent). |
-
-#### Git / PR access control
-
-Governs the `PRAgent` & `WorkspaceManager` tools and the `/v1/pr/*` routes. Input-format validation (which blocks shell/argument injection) is **always** on; the allow-lists are opt-in defense-in-depth.
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `GIT_ALLOWED_REPOS` | — (all) | Comma list of `owner/repo` (supports `owner/*`, `*`). Unset = all repos allowed + a startup warning. Restrict for shared deployments, e.g. `me/app,me/*`. |
-| `GIT_ALLOWED_ACTIONS` | — (all) | Comma list of allowed actions: `review,list,create,post-review,clone,worktree,diff,cleanup,status`. |
-| `GIT_AUTH_TOKEN` | — | Token for gh/git. Injected into the subprocess env (`GH_TOKEN`/`GITHUB_TOKEN`) only — never on argv or in a URL. Unset = use `gh`'s own auth. |
-| `GIT_HOST` | `github.com` | GitHub Enterprise host for the git/PR tools. |
-| `GITHUB_WEBHOOK_SECRET` | — | HMAC secret for `/v1/pr/webhook` (`X-Hub-Signature-256`). Unset = the webhook is disabled (401). |
-
-#### Server lifecycle
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `PORT` | `4000` | HTTP server port (falls back to the next free port if taken). |
-| `AUTO_RESUME` | `false` | `true` = resume the most recent session on boot. |
-| `RESUME_SESSION_ID` | — | Resume a specific session UUID (overrides `AUTO_RESUME`). |
-| `SERVER_IDLE_TIMEOUT` | `0` | Seconds of inactivity before auto-shutdown. `0` = never (always-on daemon). |
-| `SHUTDOWN_GRACE_MS` | `10000` | Max ms to drain in-flight connections on shutdown (`0` = wait indefinitely). |
-| `ENABLE_DASHBOARD` | `false` | Eagerly start the sandbox+tmux dashboard (binds an extra port). Tools still start it lazily when needed. |
-| `DASHBOARD_PORT` | `4001` | Dashboard port (whether started eagerly or lazily). |
-
-#### Runtime flags & debug
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `YOLO` | `false` | Auto-approve **all** tool executions (bypasses the permission system). |
-| `DEBUG_PAYLOAD` | `false` | Log raw API request/response payloads. |
-| `DEBUG_SYSTEM_MESSAGES` | `false` | Verbose system-message assembly logging (also on with `DEBUG=true`). |
-| `DEBUG_THINKING` | `false` | Show thinking/reasoning in the CLI. On Anthropic adaptive-thinking models, `true` requests summarized reasoning and **bills extra output tokens**; `false` keeps it omitted ($0). |
-| `ENABLE_SMOKE_TESTS` | `false` | Run real-API smoke tests instead of mocked ones. |
-
-#### Tool & path overrides
-
-| Variable | Default | What it does / how to use it |
-|----------|---------|------------------------------|
-| `CHROMIUM_BIN` | auto | Override the Chromium binary for web/browse tools. |
-| `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` | auto | Alternate Chromium path honored by Playwright. |
-| `TMUX_BIN` | auto | Override the tmux binary for visual agent monitoring. |
-| `GOOGLE_CLOUD_PROJECT` | — | Vertex AI project (only when using Vertex instead of the Gemini API). |