@trenchwork/erosolar 1.1.36 → 1.1.38

package/README.md

@@ -3,17 +3,19 @@
 [![npm version](https://img.shields.io/npm/v/@trenchwork/erosolar)](https://www.npmjs.com/package/@trenchwork/erosolar)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-A multi-provider terminal agent for coding work and authorized offensive
-security research. Default backend is DeepSeek-V4-Pro (via a shared
-key gated by Erosolar Auth, no key bundled in the package), with
-Anthropic / OpenAI / Google / xAI / Qwen / Ollama as opt-in providers.
-
-This README documents the **current shipped state** of the CLI: the
-agent loop, capability surface, profiles, rulebook system, MCP
-integration, artifact store, and the auth-gated key fetch. Sections
-toward the end cover architecture and contribution. Examples,
-"try asking…" hints, and onboarding fluff are deliberately absent —
-[CLAUDE.md](CLAUDE.md) is strict about that.
+A multi-provider terminal agent for coding work and authorized
+offensive-security research. Default backend is **DeepSeek-V4-Pro**
+via a shared key gated by Erosolar Auth (no key bundled in the npm
+tarball); Anthropic / OpenAI / Google / xAI / Qwen / Ollama are opt-in
+providers with bring-your-own keys.
+
+This README documents the **current shipped state** of the CLI — the
+auth-gated boot, profiles, capability surface, MCP integration,
+artifact store, and operational knobs. Examples, "try asking…" hints,
+and onboarding fluff are deliberately absent ([CLAUDE.md](CLAUDE.md)
+is strict about that). Deep technical reference lives in
+[`docs/ENGINEERING.md`](docs/ENGINEERING.md); security model and
+threat boundaries live in [`SECURITY.md`](SECURITY.md).
 
 ---
 
@@ -23,12 +25,12 @@ toward the end cover architecture and contribution. Examples,
 npm install -g @trenchwork/erosolar
 ```
 
-Two CLI binaries land on `$PATH`, both pointing to the same entry:
+Two binaries land on `$PATH` and point at the same entry:
 
 - `erosolar` — preferred
 - `trenchwork` — alternate name
 
-Node ≥ 20 required (`"engines": { "node": ">=20.0.0" }`).
+Node ≥ 20 required.
 
 ### First-run boot
 
@@ -38,64 +40,47 @@ erosolar
 
 On first launch the CLI:
 
-1. Pops a browser tab to `https://trenchwork.org/auth?port=…`. You sign in
-   with **Google SSO** (Erosolar Auth — Firebase Auth under the hood,
-   project `erosolar-1b0db`). SSO is enforced both at the web auth
-   page and at the Firestore-rule layer
+1. Opens a browser tab to `https://ero.solar/auth?port=…`. Sign in with
+   **Google SSO** (Firebase Auth, project `erosolar-1b0db`). SSO is
+   enforced both at the auth page and at the Firestore rule layer
    (`request.auth.token.firebase.sign_in_provider == 'google.com'`).
 2. Stores a Firebase ID token + refresh token at `~/.erosolar/auth.json`
-   (`0o600`). The refresh token is long-lived; the ID token is auto-
-   renewed before expiry.
+   (`0o600`). The refresh token is long-lived; the ID token rotates
+   automatically before expiry.
 3. **Approval gate.** The CLI checks `approved_users/{your-email}` in
-   Firestore. The package ships offsec capabilities (Kali tools /
-   AFL++ / gdb / pwntools / Ghidra MCP), so only allowlisted emails
-   can launch. If your email isn't approved, the CLI writes a
-   pending request to `approval_requests/{uid}` for the operator to
-   review and exits with a clear message — re-run after the request
-   is approved.
+   Firestore. The package ships offsec capabilities (Kali tools, AFL++,
+   gdb, pwntools, Ghidra), so only allowlisted emails can launch. If
+   your email isn't approved, the CLI writes a pending request to
+   `approval_requests/{uid}` and exits with a clear message — re-run
+   once the operator approves.
 4. Fetches the shared DeepSeek API key from Firestore at
-   `shared_secrets/deepseek` and writes it into `process.env.DEEPSEEK_API_KEY`
-   for the duration of the process. **Nothing lands on disk.** Reads
-   are gated by Firestore rules to authenticated *and approved*
-   users only; writes are admin-only.
-5. Starts the interactive Ink-based shell.
+   `shared_secrets/deepseek` and writes it into the process env for the
+   duration of the run. **Nothing lands on disk.** Reads are gated to
+   authenticated + approved users; writes are admin-only.
+5. Starts the Ink-based interactive shell.
 
 ### Requesting approval
 
-Sign in once via Google SSO. The CLI will detect that your email
-isn't on the allowlist and file a pending request at
-`approval_requests/{uid}`. The operator reviews the queue and
-adds your email via:
+Sign in once via Google SSO. The CLI files a pending request at
+`approval_requests/{uid}`. The operator reviews and approves with:
 
 ```sh
 node scripts/approve-user.mjs <your-email>
 ```
 
-You can re-run `erosolar` once the operator confirms approval.
-
-### Approval gate — admin operations
-
-Adding a user (uses the Firebase CLI's stored OAuth token; bypasses
-Firestore rules via owner privileges):
-
-```sh
-node scripts/approve-user.mjs alice@example.com
-```
-
-Inspecting pending requests via Firebase Console:
-[Firestore → `approval_requests`](https://console.firebase.google.com/project/erosolar-1b0db/firestore/data/~2Fapproval_requests)
+Re-run `erosolar` after approval is confirmed.
 
 ### Bring-your-own key
 
-If you'd rather use your own DeepSeek key (or any other provider key),
-the Firestore fetch is skipped. Resolution order is:
+If `DEEPSEEK_API_KEY` is set in env, the Firestore fetch is skipped.
+Resolution order:
 
 1. `process.env.DEEPSEEK_API_KEY` (env override always wins)
-2. `~/.erosolar/secrets.json` (set in-CLI via `/key sk-…` or `/secrets`)
+2. `~/.erosolar/secrets.json` (set in-CLI via `/key sk-…` or `/secrets set`)
 3. Firestore `shared_secrets/deepseek` (the post-login fallback)
 
-Same chain applies to `TAVILY_API_KEY` and any other provider key the
-shared-secrets module knows about.
+The same chain applies to `TAVILY_API_KEY` and any provider key the
+shared-secrets module recognises.
 
 ### Modes
 
@@ -103,7 +88,7 @@ shared-secrets module knows about.
 erosolar                        # interactive
 erosolar -q "explain X"         # one-shot, prints answer, exits
 git diff | erosolar             # pipe mode — stdin becomes the prompt
-erosolar --profile variant-research "<goal>"   # use a non-default profile
+erosolar --profile variant-research "<goal>"
 erosolar --self-test            # provider/auth/capability smoke test
 ```
 
@@ -111,45 +96,62 @@ erosolar --self-test            # provider/auth/capability smoke test
 
 ## Profiles
 
-A **profile** binds a system prompt template, default model/provider,
-and a [rulebook](#rulebooks) (a phase-structured guidance document the
-LLM reads from its system prompt).
+A **profile** binds a system prompt template, default model + provider,
+and a [rulebook](#rulebooks) (a phase-structured guidance document
+inlined into the system prompt). Switch via `--profile <name>` or the
+`EROSOLAR_PROFILE` environment variable. Three profiles ship:
 
 ### `erosolar-code` (default)
 
-General-purpose terminal agent for coding work. Default model
-`deepseek-v4-pro`, default provider `deepseek`. The full default tool
-inventory is mounted: filesystem (Read/Write/Edit/MultiEdit), Bash,
-Glob/Grep/Search, Git (status/log/diff/show/blame), TodoWrite, Memory
-(save/load/list/delete), Skills, NotebookEdit, WebSearch/WebExtract,
-HITL, plus any MCP servers you declare in `mcp.json`. Rulebook at
+General-purpose terminal agent for coding, builds, tests, sysadmin,
+package management. Default model `deepseek-v4-pro`, default provider
+`deepseek`. Coding tool inventory only — the offsec capabilities are
+withheld so the model's tool list isn't padded with sqlmap / ROP-search
+in normal sessions. Rulebook:
 [`agents/erosolar-code.rules.json`](agents/erosolar-code.rules.json).
 
 ### `variant-research`
 
 Authorized offsec / vulnerability-research surface. Walks the standard
 n-day-to-0-day pivot: recon → vulnerable+patched binary acquisition →
-patch diff (Ghidra MCP) → variant search → fuzz campaign (AFL++) →
-crash triage (gdb/pwndbg) → PoC development (pwntools) → coordinated
-disclosure. Rulebook at
+patch diff (Ghidra) → variant search → fuzz campaign (AFL++) → crash
+triage (gdb/pwndbg) → PoC development (pwntools) → coordinated
+disclosure. Rulebook:
 [`agents/variant-research.rules.json`](agents/variant-research.rules.json).
 
 The disclosure terminal is **pinned to coordinated channels**
 (HackerOne / Bugcrowd / vendor PSIRT / CERT-CC / internal write-up /
 90-day published advisory). The rulebook contains an explicit
-`vr.r.no_brokerage` rule: it is not a vector for selling unreported
+`vr.r.no_brokerage` rule — it is not a vector for selling unreported
 exploits.
 
-Operator authorizes targets — the CLI does not second-guess argv or
-target identifiers. The companion research workspace lives at
-[`Aroxora/patchpivot`](https://github.com/Aroxora/patchpivot) (private):
-a target portfolio, per-investigation findings dirs, and a disclosure
-log all driven by this profile.
+The companion research workspace is [`Aroxora/patchpivot`](https://github.com/Aroxora/patchpivot)
+(private): target portfolio, per-investigation findings dirs, and a
+disclosure log driven by this profile.
 
 ```sh
 erosolar --profile variant-research "investigate the patch at <commit-url>"
 ```
 
+### `engagement-delivery`
+
+Sibling of `variant-research` running the same eight-phase VR workflow,
+but the terminal phase delivers to an **authorized engagement
+recipient** — a U.S. government contract / task order, a U.S. defense
+prime under contract, or a published bug-bounty program. The rulebook
+adds an intake phase that requires an active engagement identifier in
+the artifact store before any other phase advances; missing engagement
+id → halt + prompt operator. Rulebook:
+[`agents/engagement-delivery.rules.json`](agents/engagement-delivery.rules.json).
+
+```sh
+erosolar --profile engagement-delivery "<task>"
+```
+
+Both `variant-research` and `engagement-delivery` get the offsec
+capability surface. `erosolar-code` does not. Gating lives in
+`src/runtime/profileGates.ts`.
+
 ---
 
 ## Capability surface
@@ -162,82 +164,92 @@ Capabilities are typed wrappers around external tools, registered in
 | Family | Tools |
 |---|---|
 | Filesystem | `Read`, `Write`, `Edit`, `MultiEdit`, `Glob`, `Grep`, `Search` |
-| Process | `Bash` (with bracketed-paste-safe stdin and 1MB stdout cap) |
-| Git | `git_status`, `git_log`, `git_diff`, `git_show`, `git_blame`, `git_revert` |
+| Process | `Bash` (bracketed-paste-safe stdin, 1MB stdout cap) |
+| Git | `git_status`, `git_log`, `git_diff`, `git_show`, `git_blame`, `git_revert`, full enhanced-git surface |
 | Memory | `memory_save`, `memory_load`, `memory_list`, `memory_delete` |
-| Planning | `TodoWrite` (state + plan-formatter integration) |
-| Skills | `Skill`, `list_skills` (loads `.erosolar/skills/<name>/SKILL.md`) |
+| Planning | `TodoWrite` (state + plan-formatter integration), `PlanMode` |
+| Skills | `Skill`, `list_skills` (loads `~/.erosolar/skills/<name>/SKILL.md`) |
 | Web | `WebSearch`, `WebExtract` (Tavily under the hood) |
 | Sub-agent | `spawn_agent`, `agent_status`, `agent_output`, `agent_stop` |
 | Notebook | `NotebookEdit` |
 | HITL | `hitl_decision`, `hitl_approve`, `hitl_choose` |
+| Worktree | `worktree_create`, `worktree_remove`, `worktree_list` |
+| Monitor | `monitor_start`, `monitor_stop` (long-running command observers) |
+| Schedule | `schedule_*`, `trigger_*` (in-session reminders / cron-style triggers) |
 
-### Offensive (variant-research / when wired)
+### Offensive (variant-research / engagement-delivery only)
 
 | Capability | Module | Tools |
 |---|---|---|
 | Kali (network/web) | `kaliCapability.ts` | `kali_sqlmap`, `kali_gobuster`, `kali_ffuf`, `kali_feroxbuster`, `kali_nikto`, `kali_wpscan`, `kali_hydra`, `kali_john`, `kali_hashcat`, `kali_masscan`, `kali_amass`, `kali_subfinder` |
 | Static binary analysis | `binaryAnalysisCapability.ts` | `bin_file`, `bin_strings`, `bin_objdump`, `bin_readelf`, `bin_nm`, `bin_checksec`, `bin_ropgadget`, `bin_radare2_cmd` |
+| Headless Ghidra | `ghidraHeadlessCapability.ts` | `ghidra_analyze`, `ghidra_decompile`, `ghidra_diff` |
 | AFL++ fuzzing | `aflppCapability.ts` | `afl_compile_harness`, `afl_fuzz_start` (detached), `afl_fuzz_status` (auto-registers crashes in artifact store), `afl_fuzz_stop`, `afl_showmap`, `afl_cmin`, `afl_tmin` |
 | Crash triage | `gdbCapability.ts` | `gdb_run_with_input`, `gdb_inspect_at`, `gdb_disassemble` (pwndbg/GEF inherited from `~/.gdbinit`) |
-| Exploit development | `pwntoolsCapability.ts` | `pwn_eval`, `pwn_rop_search`, `pwn_packed` |
+| Exploit dev | `pwntoolsCapability.ts` | `pwn_eval`, `pwn_rop_search`, `pwn_packed` |
 
 The offsec capabilities are guardrail-free per
-[trenchwork.org/about](https://trenchwork.org/about) — the operator authorizes
+[ero.solar/about](https://ero.solar/about) — the operator authorizes
 their own engagements; the CLI does not validate target/argv. Install
-the underlying binaries via `kali-linux-everything` + `ghidra` on Kali
-Linux, or pull the Kali rolling repo on Debian/Ubuntu.
+the underlying binaries via `kali-linux-everything` + `ghidra` on
+Kali, or the Kali rolling repo on Debian/Ubuntu.
 
 ---
 
 ## MCP servers
 
 The CLI auto-loads MCP servers declared in `mcp.json` (or
-`mcp.json.example` as a template). Tools from each MCP server appear in
-the flat tool list with the prefix `mcp__<server>__<tool>`.
+`mcp.json.example` as a template). MCP tools appear in the flat tool
+list with the prefix `mcp__<server>__<tool>`.
 
 ```json
 {
   "mcpServers": {
-    "ghidra": {
-      "command": "python3",
-      "args": ["-m", "ghidra_mcp"],
-      "env": { "GHIDRA_INSTALL_DIR": "/usr/share/ghidra" }
-    },
+    "ghidra":          { "command": "python3", "args": ["-m", "ghidra_mcp"], "env": { "GHIDRA_INSTALL_DIR": "/usr/share/ghidra" } },
     "mcp_kali_server": { "command": "mcp-kali-server", "args": [] },
-    "metasploitmcp":   { "command": "metasploitmcp",    "args": [] },
-    "tavily":          { "command": "tavily-mcp",        "args": [] }
+    "metasploitmcp":   { "command": "metasploitmcp", "args": [] },
+    "tavily":          { "command": "tavily-mcp", "args": [] }
   }
 }
 ```
 
-The `mcp-kali-server` and `metasploitmcp` packages ship in
-`kali-linux-everything`. `ghidra-mcp` is a separate `pip install`.
-`tavily-mcp` is on npm. None are required; they're additive.
+`mcp-kali-server` and `metasploitmcp` ship in `kali-linux-everything`.
+`ghidra-mcp` is a separate `pip install`. `tavily-mcp` is on npm.
+None are required; they're additive.
 
 ---
 
 ## Slash commands
 
-In-shell commands handled before the agent loop sees them:
+Handled before the agent loop sees the input. The set below reflects
+the actual command table (`src/shell/commandRegistry.ts` plus the
+inline matchers in `src/headless/interactiveShell.ts`):
 
-| Command | Effect |
-|---|---|
-| `/help` | Lists available commands |
-| `/key <sk-…>` | Saves DeepSeek key to `~/.erosolar/secrets.json` |
-| `/secrets` | Inspect / set / unset every known provider key |
-| `/profile <name>` | Switch profile mid-session |
-| `/model <id>` | Override default model for this session |
-| `/auto on\|off\|verify` | Auto-continue mode (loops until task-complete detector says done) |
-| `/hitl on\|off` | Toggle human-in-the-loop confirmations |
-| `/debug on\|off\|status` | Toggle agent-internal debug logging |
-| `/bash <cmd>` | Run a one-shot shell command without going through the agent |
-| `/diff` | Show git diff for the current run |
-| `/revert` | Roll back files modified during the current turn |
-| `/compact` | Force a context compaction pass |
-| `/status` | Token usage, model, profile, auth state |
-| `/mcp` | List active MCP servers and their tools |
-| `/quit`, `/exit` | Leave the shell |
+| Command | Aliases | Effect |
+|---|---|---|
+| `/help` | `/h`, `/?` | Inline help panel |
+| `/model [name]` | `/m` | No arg → picker menu; arg → silent switch (`provider`, `provider model`, `provider/model`, or `model`) |
+| `/providers` |  | List configured providers |
+| `/key <sk-…>` |  | Save `DEEPSEEK_API_KEY` to `~/.erosolar/secrets.json` |
+| `/secrets [set [name]]` | `/s` | Inspect / set / unset every known provider key |
+| `/auto` | `/continue`, `/loop`, `/dual` | Cycle auto-continue mode (off → on → dual → off) |
+| `/bash <cmd>` | `/sh` | One-shot shell command, bypasses the agent |
+| `/clear` | `/c` | Clear screen, redraw welcome |
+| `/context` |  | Refresh workspace context |
+| `/sessions` |  | Session management menu |
+| `/revert [confirm]` |  | Preview / roll back files modified during the current run |
+| `/tools` |  | List active tools |
+| `/mcp` |  | MCP server + tool status |
+| `/learn` |  | Learning-system status |
+| `/debug [on\|off\|status]` |  | Toggle agent-internal debug logging |
+| `/stats` | `/status` | Session token + cost stats |
+| `/keys` | `/shortcuts`, `/kb` | Keyboard shortcuts panel |
+| `/exit` | `/quit`, `/q` | Leave the shell |
+
+Profile is selected at boot only — there is no in-session `/profile`
+switch; restart with `--profile <name>` or set `EROSOLAR_PROFILE`.
+HITL is configured per-tool through the capability's `autoPause`
+option (Option+V toggles the equivalent).
 
 ---
 
@@ -264,13 +276,13 @@ In-shell commands handled before the agent loop sees them:
 | `EROSOLAR_HOME` | Override `~/.erosolar` storage root |
 | `EROSOLAR_PROFILE` | Default profile (alternative to `--profile`) |
 | `EROSOLAR_INK_DEBUG=1` | Verbose Ink prompt + state logging on stderr |
-| `<PROFILE>_MODEL` | Per-profile default model override (e.g. `EROSOLAR_CODE_MODEL=claude-opus-4-5-20251101`) |
+| `<PROFILE>_MODEL` | Per-profile default model override (e.g. `EROSOLAR_CODE_MODEL=claude-opus-4-7`) |
 | `<PROFILE>_PROVIDER` | Per-profile default provider override |
 | `<PROFILE>_SYSTEM_PROMPT` | Per-profile system prompt override |
 | `NO_COLOR`, `FORCE_COLOR` | Standard color toggles |
-| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `DASHSCOPE_API_KEY`, `OLLAMA_BASE_URL` | Other provider credentials when you select those models |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `DASHSCOPE_API_KEY`, `OLLAMA_BASE_URL` | Other provider credentials when those models are selected |
 
-### `.erosolar/settings.json` (hooks + permissions)
+### `~/.erosolar/settings.json` (hooks + permissions)
 
 The harness reads `~/.erosolar/settings.json` (user) and
 `<workspace>/.erosolar/settings.json` (project) for hooks, allow/deny
@@ -281,19 +293,24 @@ contract.
 
 ## Variant research workflow
 
-The `variant-research` profile drives an 8-phase rulebook the LLM
-reads from its system prompt:
+The `variant-research` and `engagement-delivery` rulebooks drive the
+same eight-phase pivot the LLM reads from its system prompt:
 
 | Phase | Intent | Tools |
 |---|---|---|
 | `recon` | Identify target patch / CVE / advisory; record bug-class hypothesis | Tavily / WebSearch |
 | `acquire` | Build vulnerable + patched binaries; persist to artifact store | Bash, Git, `bin_*` |
-| `bindiff` | Diff binaries and pull decompiled C of changed functions | Ghidra MCP |
-| `variant` | Hunt the same buggy pattern in older versions / forks / siblings | Ghidra MCP, Grep |
+| `bindiff` | Diff binaries; pull decompiled C of changed functions | Ghidra MCP / `ghidra_*` |
+| `variant` | Hunt the same buggy pattern in older versions / forks / siblings | Ghidra, Grep |
 | `fuzz` | Build harness + run AFL++ campaign as detached job | `afl_*` |
-| `triage` | Classify each crash; correlate to Ghidra decomp; identify primitive | `gdb_*`, Ghidra MCP |
-| `poc` | Develop minimal reliable PoC that reproduces the primitive | `pwn_*` |
-| `disclose` | Author write-up; submit through coordinated channel | — (the rulebook lists allowed channels) |
+| `triage` | Classify each crash; correlate to decomp; identify primitive | `gdb_*`, Ghidra |
+| `poc` | Develop minimal reliable PoC reproducing the primitive | `pwn_*` |
+| `disclose` / `deliver` | Author write-up; ship through coordinated / contracted channel | — (rulebook lists allowed channels) |
+
+`engagement-delivery` adds a leading `intake` phase that gates the
+workflow on a registered engagement identifier (USG contract / task
+order, defense-prime engagement reference, or published bug-bounty
+program scope).
 
 The artifact store is the load-bearing piece: every multi-megabyte
 output (binaries, decompilations, crash corpora) is registered with a
@@ -301,9 +318,6 @@ sha256 id and tagged. The LLM passes ids around in conversation
 instead of pasting blobs into context — without this, a long workflow
 gets summarized away mid-investigation.
 
-The companion `patchpivot` repo (separate, private) holds target
-portfolios and per-investigation workspaces.
-
 ---
 
 ## Architecture
@@ -324,28 +338,33 @@ No DAG planner, no ReAct scratchpad. Multi-step planning is implicit
 in the LLM's tool calls, guided by the rulebook injected into the
 system prompt. Sub-agents (`spawn_agent` / `agent_status` /
 `agent_output` / `agent_stop`) are the long-task supervisor — anything
-that runs for hours (fuzz campaigns, large recompiles) goes detached
-and the parent polls.
+running for hours (fuzz campaigns, large recompiles) goes detached and
+the parent polls.
 
 ### Capability registry
 
 Each capability module implements `CapabilityModule` and contributes a
 flat `ToolSuite` to the runtime. Registration happens in
-`src/capabilities/index.ts`. Tools declare JSON Schema parameters,
-inputs are validated and coerced via
-`src/core/schemaValidator.ts` before the handler runs. MCP tools are
-first-class — same `ToolDefinition` shape, prefixed `mcp__`.
+`src/capabilities/index.ts`. Tools declare JSON Schema parameters;
+inputs are validated and coerced via `src/core/schemaValidator.ts`
+before the handler runs. MCP tools are first-class — same
+`ToolDefinition` shape, `mcp__<server>__` prefix.
+
+Profile-based gating (`src/runtime/profileGates.ts`) decides which
+capabilities are mounted. Cowork / productivity capabilities were
+extracted to `~/GitHub/erosolar-cowork` in 2026-05 and are not
+present in this repo (enforced by `test/capability-separation.test.ts`).
 
-### Rulebook
+### Rulebooks
 
 A rulebook (`src/contracts/schemas/agent-rules.schema.json`) is a
 phase-structured JSON document with `globalPrinciples`, `phases`, and
-per-step `entryCriteria` / `exitCriteria` / `rules`. The CLI renders
-it to markdown and inlines it into the profile's system prompt at
-boot. It is **declarative guidance**, not an enforced state machine —
-the LLM is expected to follow it; nothing in the runtime blocks a
-phase from being skipped. The rule severities (`critical` /
-`required` / `recommended`) influence how strongly the LLM treats them.
+per-step `entryCriteria` / `exitCriteria` / `rules`. The CLI renders it
+to markdown and inlines it into the profile's system prompt at boot.
+It is **declarative guidance**, not an enforced state machine — the
+LLM is expected to follow it; nothing in the runtime blocks a phase
+from being skipped. Rule severities (`critical` / `required` /
+`recommended`) influence how strongly the LLM treats them.
 
 ### Artifact store
 
@@ -361,17 +380,17 @@ compaction.
 
 `src/core/sharedSecrets.ts` — REST fetch of `shared_secrets/<name>`
 from Firestore using the user's Firebase ID token. Auto-refreshes the
-token if expired. Writes to `process.env`, no on-disk cache (a
-rotated key shouldn't get stuck stale on a user's machine). Triggered
-once at boot from `src/bin/deepseek.ts` after `requireAuth()`.
+token if expired. Writes to `process.env`, no on-disk cache (a rotated
+key shouldn't get stuck stale on a user's machine). Triggered once at
+boot from `src/bin/deepseek.ts` after `requireAuth()`.
 
 ### Context manager
 
 `src/core/contextManager.ts` — token-budget aware sliding window with
 LLM-driven summarization. Defaults: 130k max, 100k target compaction
 trigger, last 10 exchanges always preserved, file-read truncation
-keeps head + tail of large files. Uses `EROSOLAR_CODE_MODEL` (or the
-profile's default) for the summarization pass.
+keeps head + tail of large files. Uses the profile's default model for
+the summarization pass.
 
 ### HITL
 
@@ -383,6 +402,31 @@ the LLM (it decides when to ask), not the runtime — there's no
 
 ---
 
+## Companion surfaces
+
+This monorepo contains the CLI plus three companion surfaces that
+share Erosolar Auth, balance, and the model brain:
+
+- **Helia** ([`Erosolar_Browser/`](Erosolar_Browser)) — Electron +
+  Chromium browser modeled after ChatGPT Atlas, with a side-panel
+  Erosolar agent that has full page context and CDP-driven action
+  automation. Cross-platform: macOS (dmg/zip, x64+arm64), Windows
+  (NSIS + portable), Linux (AppImage + .deb). Distributed at
+  [ero.solar/helia](https://ero.solar/helia) with an S3-manifest
+  auto-updater. Current Helia version: `0.1.21`.
+- **Site** ([`site/`](site)) — Firebase-hosted marketing/portal
+  (`/about`, `/portal`, `/auth`, `/docs`, `/defense`, `/process`,
+  `/audit`, `/admin`, `/npm`, `/helia`).
+- **AWS Lambda backend** ([`aws/lambda/`](aws/lambda)) — single Lambda
+  fronted by API Gateway, Stripe checkout, Firestore for state,
+  service-account JSON pulled from AWS Secrets Manager. Replaces the
+  legacy Cloud Functions deployment; portal + CLI both call into it.
+
+Cross-surface PRs are atomic by design. See CLAUDE.md "Monorepo for
+one product, separate repos for different products" for the rule.
+
+---
+
 ## Building from source
 
 ```sh
@@ -394,38 +438,40 @@ npm test           # full jest suite
 node dist/bin/erosolar.js --self-test
 ```
 
-The `pretest` hook runs the build, and `prepublishOnly` rebuilds
-before any npm publish so the published tarball is always rebuilt
-from source.
+`pretest` runs the build, and `prepublishOnly` rebuilds before any npm
+publish so the published tarball is always rebuilt from source.
 
 ### Tests
 
 `test/**/*.test.ts` — driven by jest with the config in
-`jest.config.cjs`. Test discipline (per `CLAUDE.md`): real behavior
+`jest.config.cjs`. Test discipline (per CLAUDE.md): real behavior
 end-to-end, no mocks for things the test claims to verify. Tests for
 provider calls require credentials; those are gated by env-var
-presence and skipped (with a clear reason) when absent. Skipped !=
-passing.
+presence and skipped (with a clear reason) when absent.
+**Skipped ≠ passing.**
+
+A pre-push git hook (`scripts/git-hooks/pre-push`) runs `npm test`
+before every push. Install once per checkout:
+`git config core.hooksPath scripts/git-hooks`. Bypass in an emergency
+with `git push --no-verify`.
 
 ### Releasing
 
 `npm run release` → `scripts/create-release.sh patch` (interactive —
-checks clean git, runs tests, bumps version, builds, publishes,
-tags). For non-interactive publishes the workflow is
-`npm version patch && npm publish --access public`.
+checks clean git, runs tests, bumps version, builds, publishes, tags).
+Non-interactive publishes: `npm version patch && npm publish --access public`.
 
 ---
 
 ## Versioning + deprecation policy
 
 Semver. Patches add features and fix bugs without API breakage; minor
-bumps signal new public surfaces; major bumps signal breaking
-changes. Dev releases use the `next` dist-tag.
+bumps signal new public surfaces; major bumps signal breaking changes.
 
 Versions `1.1.16` → `1.1.19` are **deprecated** — they bundled an
-embedded DeepSeek API key that's now revoked. Any installation on
-that range will print an `npm deprecate` warning. Upgrade to ≥
-`1.1.20`.
+embedded DeepSeek API key that has been revoked. Installations on that
+range print an `npm deprecate` warning. Upgrade to ≥ `1.1.20`. The
+shared-key fetch via Firebase Auth replaces the embedded key.
 
 ---
 
@@ -436,19 +482,22 @@ that range will print an `npm deprecate` warning. Upgrade to ≥
 > reference (SSO, allowlist, revocation, profile gating, audit log,
 > threat model, residual risk).
 
-
 - The CLI is dual-use offensive-security tooling. U.S. classification
-  is EAR-controlled (CCL [ECCN 4D004](https://www.federalregister.gov/documents/2021/10/21/2021-22774/information-security-controls-cybersecurity-items)),
-  not USML/ITAR. Domestic development and use is unrestricted; export
-  controls apply to international transfer.
-- The `kaliCapability.ts` and offsec capabilities are guardrail-free.
-  Operator authorization is assumed — both for legal authorization
-  (you have permission to test the target) and ethical authorization
-  (the engagement scope covers what you're about to run).
-- Disclosure is pinned. The `variant-research` rulebook's disclose
+  is EAR-controlled (CCL [ECCN 4D004](https://www.federalregister.gov/documents/2021/10/21/2021-22774/information-security-controls-cybersecurity-items)
+  + 4E001 for development technology). Domestic development and use is
+  unrestricted; export controls apply to international transfer. Good-faith
+  security research is affirmatively protected by Van Buren (2021), the
+  DOJ May-2022 CFAA Charging Policy, and the LOC § 1201 Triennial
+  Exemption (2024).
+- `kaliCapability.ts` and the offsec capability surface are
+  guardrail-free. Operator authorization is assumed — both legal
+  authorization (you have permission to test the target) and ethical
+  authorization (the engagement scope covers what you're about to run).
+- Disclosure is pinned. The `variant-research` rulebook's `disclose`
   phase has explicit `vr.r.no_brokerage` and `vr.r.respect_embargo`
   rules. PoCs go to vendor / HackerOne / Bugcrowd / CERT-CC, not to
-  brokers.
+  brokers. `engagement-delivery` ships only to authorized contracted
+  recipients.
 - Secrets handling: the npm package ships zero embedded API keys.
   Keys come from env, user-set local file, or Firestore via Firebase
   Auth (admin-managed). Error messages are sanitized through
@@ -458,8 +507,8 @@ that range will print an `npm deprecate` warning. Upgrade to ≥
   permissions, in an `0o700` directory. Atomic writes prevent
   half-written JSON from breaking subsequent loads.
 
-See [`/about`](https://trenchwork.org/about) for the full disclosure
-including BIS / DDTC links and the relevant rulemaking.
+See [`/about`](https://ero.solar/about) for the full disclosure
+including BIS links and the relevant rulemaking.
 
 ---
 
@@ -468,8 +517,8 @@ including BIS / DDTC links and the relevant rulemaking.
 - npm: https://www.npmjs.com/package/@trenchwork/erosolar
 - Source: https://github.com/Aroxora/deepseek-coder-cli
 - Companion research workspace: `Aroxora/patchpivot` (private)
-- Helia (macOS browser companion): https://trenchwork.org/helia
-- Erosolar Auth: https://trenchwork.org/auth
-- Project context: https://trenchwork.org/about
+- Helia (browser companion, mac/win/linux): https://ero.solar/helia
+- Erosolar Auth: https://ero.solar/auth
+- Project context: https://ero.solar/about
 
 License: MIT (see [LICENSE](LICENSE)).