{"owner":"JuliusBrussee","repo":"caveman","hasSkills":true,"totalSkillsCount":99,"totalTokensCount":137303,"categories":["marketplace","plugin-manifest","root-instruction","claude-rule","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":[".claude-plugin/marketplace.json",".claude-plugin/plugin.json",".cursor-plugin/plugin.json","AGENTS.md","CLAUDE.md","browse/CLAUDE.md","engine/AGENTS.md","engine/CLAUDE.md","evals/README.md","extension/AGENTS.md","extension/CLAUDE.md","integrations/CLAUDE.md","mcp/AGENTS.md","mcp/CLAUDE.md","mem/AGENTS.md","mem/CLAUDE.md","packages/cli/AGENTS.md","packages/cli/CLAUDE.md","packages/cli/README.md","packages/middleware/python/README.md","packages/middleware/typescript/README.md","packages/pi-extension/README.md","packages/sdk/parity/AGENTS.md","packages/sdk/parity/CLAUDE.md","packages/sdk/python/AGENTS.md","packages/sdk/python/CLAUDE.md","packages/sdk/python/README.md","packages/sdk/typescript/AGENTS.md","packages/sdk/typescript/CLAUDE.md","packages/sdk/typescript/README.md","packages/shared/contracts/AGENTS.md","packages/shared/contracts/CLAUDE.md","packages/shared/contracts/conformance/README.md","packages/shared/contracts/openapi/middleware.openapi.json","packages/subagent-tax/README.md","plugins/caveman/.codex-plugin/plugin.json","plugins/caveman/skills/cavecrew/SKILL.md","plugins/caveman/skills/caveman-compress/SKILL.md","plugins/caveman/skills/caveman-stats/SKILL.md","plugins/caveman/skills/caveman/SKILL.md","plugins/caveman/skills/caveman/agents/openai.yaml","plugins/caveman/skills/megacave/SKILL.md","plugins/caveman/skills/ultracave/SKILL.md","proxy/AGENTS.md","proxy/CLAUDE.md","shrink/AGENTS.md","shrink/CLAUDE.md","skills/cavecrew/README.md","skills/cavecrew/SKILL.md","skills/caveman-commit/README.md","skills/caveman-commit/SKILL.md","skills/caveman-compress/README.md","skills/caveman-compress/SECURITY.md","skills/caveman-compress/SKILL.md","skills/caveman-discover/SKILL.md","skills/caveman-evidence-review/SKILL.md","skills/caveman-explore/SKILL.md","skills/caveman-explore/package.json","skills/caveman-help/README.md","skills/caveman-help/SKILL.md","skills/caveman-learn/CLAUDE.md","skills/caveman-learn/README.md","skills/caveman-learn/SKILL.md","skills/caveman-learn/package.json","skills/caveman-manage/SKILL.md","skills/caveman-optimize/SKILL.md","skills/caveman-review/README.md","skills/caveman-review/SKILL.md","skills/caveman-setup/SKILL.md","skills/caveman-stats/README.md","skills/caveman-stats/SKILL.md","skills/caveman/README.md","skills/caveman/SKILL.md","skills/engine-mcp-tools.json","skills/generated/aider/pack.json","skills/generated/claude/pack.json","skills/generated/codex/pack.json","skills/generated/gemini/pack.json","skills/generated/hermes/pack.json","skills/generated/opencode/pack.json","skills/investigate-first/SKILL.md","skills/investigate-first/agents/openai.yaml","skills/lean-build/SKILL.md","skills/lean-build/agents/openai.yaml","skills/megacave/README.md","skills/megacave/SKILL.md","skills/migration/SKILL.md","skills/migration/agents/openai.yaml","skills/native/native-core.md","skills/registry.json","skills/safe-refactor/SKILL.md","skills/safe-refactor/agents/openai.yaml","skills/surgical-patch/SKILL.md","skills/surgical-patch/agents/openai.yaml","skills/ultracave/README.md","skills/ultracave/SKILL.md","skills/verify-and-stop/SKILL.md","skills/verify-and-stop/agents/openai.yaml","src/plugins/opencode/README.md"],"skills":{".claude-plugin/marketplace.json":"",".claude-plugin/plugin.json":"",".cursor-plugin/plugin.json":"","AGENTS.md":"Read `CLAUDE.md` before repository work. Binding routing: this repo owns\nskills, Engine, and MV3 extension; Agent SDK work belongs in\n`/Users/julb/Desktop/GitHub/caveman-agent-sdk`; Browse driver/MCP/benchmark/plugin\nwork belongs in `/Users/julb/Desktop/GitHub/caveman-browse`; proprietary Pebble\nproduct work belongs in `/Users/julb/Desktop/GitHub/caveman-coding-agent`.\n\nVisibility: this repo and `caveman-browse` are public now;\n`caveman-agent-sdk` is private during development with planned public release\nafter its gates; `caveman-coding-agent` and Caveman-Cloud remain private\ncommercial source.\n\n@./skills/caveman/SKILL.md\n@./skills/caveman-commit/SKILL.md\n@./skills/caveman-review/SKILL.md\n@./skills/caveman-compress/SKILL.md\n","CLAUDE.md":"# CLAUDE.md — caveman\n\n## README is a product artifact\n\nREADME = product front door. Non-technical people read it to decide if caveman worth install. Treat like UI copy.\n\n**Rules for any README change:**\n\n- Readable by non-AI-agent users. If you write \"SessionStart hook injects system context,\" invisible to most — translate it.\n- Keep Before/After examples first. That the pitch.\n- Install table always complete + accurate. One broken install command costs real user.\n- What You Get table must sync with actual code. Feature ships or removed → update table.\n- Preserve voice. Caveman speak in README on purpose. \"Brain still big.\" \"Cost go down forever.\" \"One rock. That it.\" — intentional brand. Don't normalize.\n- Benchmark numbers from real runs in `benchmarks/` and `evals/`. Never invent or round. Re-run if doubt.\n- Adding new agent to install table → add detail block in `
` section below.\n- Readability check before any README commit: would non-programmer understand + install within 60 seconds?\n\n---\n\n## Project overview\n\nCaveman makes AI coding agents respond in compressed caveman-style prose while preserving technical substance, code, commands, and exact errors. Publish no reduction or quality-equivalence percentage without a committed reviewed benchmark. Ships as Claude Code plugin, Codex plugin, Gemini CLI extension, and agent rule files for Cursor, Windsurf, Cline, Copilot, and other profiles via `npx skills`.\n\n## Repository routing\n\nThis repo is source of truth for Caveman skills, Engine, and MV3 directive\nextension. Agent SDK + initializer work belongs in\n`/Users/julb/Desktop/GitHub/caveman-agent-sdk`\n(`JuliusBrussee/agent-sdk`). Proprietary Pebble runtime, policy, sessions, TUI,\ndistribution, and conformance work belongs in\n`/Users/julb/Desktop/GitHub/caveman-coding-agent`\n(intended `JuliusBrussee/caveman-coding-agent`). Browse driver/MCP/benchmark/plugin work\nbelongs in `/Users/julb/Desktop/GitHub/caveman-browse`\n(`JuliusBrussee/caveman-browse`). The matching `browse/` directory here is a\nconsumer copy (it still builds the `caveman-browse` release binary); edit only\nfor pinned integration, migration/removal, or an explicitly requested\ncross-repo sync.\n\nVisibility is separate from ownership: this repo and `caveman-browse` are\npublic now; `caveman-agent-sdk` is private during development and planned for\npublic release after its release gates; `caveman-coding-agent` and\nCaveman-Cloud remain private commercial source.\n\n---\n\n## What lives where\n\nPost-cleanup layout. Sources of truth at the top, distribution mirrors below, build outputs in `dist/`, human docs alongside each skill.\n\n```\ncaveman/\n├── README.md # Front door (product pitch)\n├── INSTALL.md # Per-agent install commands\n├── CONTRIBUTING.md # Dev guide\n├── CLAUDE.md # This file (maintainer instructions)\n├── AGENTS.md / GEMINI.md # Autodiscovery files (must stay at root)\n│\n├── install.sh / install.ps1 # 30-line shims → installer/install.js\n│\n├── installer/ # Unified installer\n│ ├── install.js # Single source for all 30+ agents (PROVIDERS array)\n│ └── lib/settings.js # JSONC-tolerant settings.json reader/writer\n│\n├── skills/ # ALL skills, single source of truth\n│ ├── caveman/{SKILL.md, README.md}\n│ ├── caveman-commit/{SKILL.md, README.md}\n│ ├── caveman-review/{SKILL.md, README.md}\n│ ├── caveman-help/{SKILL.md, README.md}\n│ ├── caveman-stats/{SKILL.md, README.md}\n│ ├── caveman-compress/{SKILL.md, README.md, scripts/}\n│ └── cavecrew/{SKILL.md, README.md}\n│\n├── agents/ # cavecrew subagents (single source — kept at root for plugin auto-discovery)\n│ └── docs/ # profile-registry docs — NOT agents (see note below)\n├── commands/ # Codex/Gemini TOML command stubs (root for plugin auto-discovery)\n│\n├── src/ # Internal source — not auto-discovered by plugin\n│ ├── hooks/ # Claude Code hooks (installer reads here)\n│ ├── rules/ # Auto-activation rule body (single source)\n│ ├── tools/ # caveman-init.js (per-repo rule writer)\n│ └── mcp-servers/ # caveman-shrink npm-published MCP middleware\n│\n├── packages/ # Current public packages\n│ ├── cli/ # @caveman-ai/cli\n│ ├── pi-extension/ # @caveman-ai/pi — native Pi extension (bundled into the CLI, published on `pi-v*` tags)\n│ ├── sdk/ # TypeScript + Python gateway clients\n│ ├── subagent-tax/ # Local harness-prefix benchmark\n│ └── shared/ # Contracts + binary installer\n├── engine/ · proxy/ # Local compression runtime + provider proxy\n├── mcp/ · mem/ · shrink/ # Recovery tools, memory, output compression\n├── browse/ # consumer copy; source = caveman-browse\n├── extension/ # MV3 extension source\n├── shared/ # Provider catalog + platform libraries\n│\n├── .claude-plugin/ # Claude Code plugin manifest (REQUIRED at root)\n├── .cursor-plugin/plugin.json # Cursor plugin: skills/, hooks/hooks-cursor.json, agents/ (default scan)\n├── hooks/hooks-cursor.json # Cursor plugin sessionStart hook ONLY. Never add hooks/hooks.json:\n│ # Claude Code and Gemini auto-load it from the plugin/extension root\n├── plugins/caveman/ # Claude Code plugin distribution (CI-mirrored)\n│ ├── skills/ # ← from skills/\n│ └── agents/ # ← from agents/\n│\n├── dist/ # Build artifacts (gitignored)\n│ └── caveman.skill # ZIP of skills/caveman/, rebuilt by CI\n│\n├── tests/ # All tests (Node + Python)\n├── benchmarks/ # Real token measurements through Claude API\n├── evals/ # Three-arm eval harness\n├── docs/ # User-facing docs site\n└── .github/workflows/ # CI sync\n```\n\n---\n\n## File structure and what owns what\n\n### Single source of truth files — edit only these\n\n| File | What it controls |\n|------|-----------------|\n| `skills/caveman/SKILL.md` | The caveman voice: rules, auto-clarity, persistence. Sibling skills `skills/ultracave/SKILL.md` (grammar stripped) and `skills/megacave/SKILL.md` (文言文) are self-contained and each map 1:1 to a stored mode. Edit these three for behavior changes. |\n| `src/rules/caveman-activate.md` | Always-on auto-activation rule body, consumed by `src/tools/caveman-init.js` (per-repo IDE rule files) and by the opencode `AGENTS.md` block. GENERATED: `skills/compile.mjs` derives it from `skills/caveman/SKILL.md` (thesis line + rule headlines) plus the fixed tail in `skills/activation-rule.mjs`, and rewrites the `RULE_BODY` fallback in `caveman-init.js` to match. Edit the skill or the tail, rerun `node packages/cli/scripts/compile-registries.mjs`; `tests/installer/rule-copies.test.mjs` fails on drift. |\n| `src/rules/caveman-openclaw-bootstrap.md` | Marker-fenced bootstrap snippet appended to `~/.openclaw/workspace/SOUL.md` by `installer/lib/openclaw.js`. Drives always-on caveman through the OpenClaw gateway. Must include the SENTINEL `Respond terse like smart caveman` and stay well under OpenClaw's 12K-per-bootstrap-file cap. |\n| `.codex/codex-sessionstart.js` | Repo-local Codex SessionStart hook. Resolves the configured default mode through `src/hooks/caveman-config.js` and emits the active skill's ruleset whole, replacing the hardcoded `full`-level echo `.codex/hooks.json` used to carry — so `CAVEMAN_DEFAULT_MODE`, a repo-local `.caveman.json` and a user-config `defaultMode: \"off\"` all take effect on Codex. Also the user-level always-on hook (#573): `installer/install.js --only codex` copies it (shipped via `package.json` `files`) into the owned payload `$CODEX_HOME/caveman/hooks/` beside `caveman-config.js` and `package.json`, with `caveman/skills/{caveman,ultracave,megacave}/SKILL.md`, and merges one SessionStart entry into `$CODEX_HOME/hooks.json`, identified by that script path so foreign and caveman-CLI `native-hook` entries are never touched. `--no-hooks`/`--minimal` skip it; uninstall unmerges before removing the payload. Codex asks the user to trust a new hook via `/hooks`; never pre-trust it. Carries a hand-copied `FALLBACK_VALID_MODES` for when the shared resolver is absent; `tests/hooks/codex-sessionstart.test.mjs` fails if it drifts from `VALID_MODES`. |\n| `installer/lib/openclaw.js` | OpenClaw install/uninstall helper. Frontmatter merge (`version`, `always: true`), SOUL.md marker append/strip, idempotent. Shared by `installer/install.js` and `src/tools/caveman-init.js`. |\n| `skills/caveman-commit/SKILL.md` | Caveman commit message behavior. Fully independent skill. |\n| `skills/caveman-review/SKILL.md` | Caveman code review behavior. Fully independent skill. |\n| `skills/caveman-help/SKILL.md` | Quick-reference card. One-shot display, not a persistent mode. |\n| `skills/caveman-compress/SKILL.md` | Compress sub-skill behavior. |\n| `skills/cavecrew/SKILL.md` | Cavecrew decision guide — when to delegate to caveman subagents vs vanilla. Edit only here. |\n| `skills/{caveman-setup,caveman-discover,caveman-learn,caveman-manage,caveman-optimize,caveman-explore,caveman-evidence-review}/SKILL.md` | Engine/proxy driver skills. Ship with the plugin (see the auto-discovery note below). |\n| `skills/{investigate-first,lean-build,surgical-patch,safe-refactor,migration,verify-and-stop}/SKILL.md` | Token-discipline work patterns — same goal as caveman prose (fewer output tokens) applied to code volume rather than wording. Deliberately un-branded so they read as generic patterns to the model. Ship with the plugin. |\n| `agents/cavecrew-investigator.md` | Read-only locator subagent (haiku). Output contract: `path:line — symbol — note`. |\n| `agents/cavecrew-builder.md` | Surgical 1-2 file editor subagent. Refuses 3+ file scope. |\n| `agents/cavecrew-reviewer.md` | Diff/file reviewer subagent (haiku). One-line findings with severity emoji. |\n| `src/plugins/opencode/plugin.js` | opencode native plugin. ESM Bun module — `session.created` writes flag, `tui.prompt.append` parses slash/natural-language activation and appends per-prompt reinforcement. Reuses `caveman-config.js` via `createRequire`. |\n| `src/plugins/opencode/commands/*.md` | Six opencode slash-command prompt templates (`/caveman`, `/caveman-{commit,review,compress,stats,help}`). |\n\n### `skills/` is auto-discovered wholesale — every subdirectory ships\n\n`.claude-plugin/marketplace.json` sets `\"source\": \"./\"`, so the plugin root IS\nthe repo root, and Claude Code auto-discovers **every** `skills/*/SKILL.md`\nwith no `skills` key in `plugin.json` to gate it. Adding a directory under\n`skills/` therefore installs it into every plugin user's agent, where its\n`description` competes for activation on ordinary work.\n\nThere is no allowlist. Before adding a directory here, decide whether it\nshould reach end users; if not, it belongs under `packages/` or another root.\nKeep the two tables above and the README \"What you get\" table in sync with the\nactual directory listing — `ls skills/` is the source of truth.\n\n### `agents/*.md` is auto-discovered too — and `plugin.json` must NOT list them\n\nSame mechanism, sharper edge. `plugin.json` used to carry an explicit\n`\"agents\": [\"./agents/cavecrew-*.md\"]` array. On Claude Code 2.1.235 that array\nloads **zero** agents — `claude plugin details caveman` reports `Agents (0)`\nwith it and `Agents (3)` without it, so the three cavecrew subagents the\n`cavecrew` skill delegates to did not exist for any plugin user. The docs say\n`string | string[]` is valid and a directory string is rejected outright\n(`agents: Invalid input`), so the default `agents/` scan is the only path that\nworks. Do not re-add the key.\n\nConsequence: **every `.md` anywhere in `agents/` becomes a subagent**, named\nfrom its frontmatter or filename. Maintainer documentation belongs outside that\ntree; profile-registry orientation lives in\n`docs/technical/agent-profile-registry.md`. `tests/verify_repo.py` fails build\nif any markdown beyond three intended cavecrew agents appears under `agents/`.\n\n### `commands/*.md` shadows same-named skills — keep the `.md` stubs unique\n\nClaude Code loads `commands/*.md` as flat skills alongside `skills/*/SKILL.md`,\nso a stub sharing a skill's name registers that name twice. `caveman.md`,\n`caveman-commit.md`, `caveman-review.md` and `caveman-stats.md` each duplicated\na real skill — a 3-line stub competing with the full ruleset for the same slash\ncommand — and were removed. The `.toml` stubs are Codex/Gemini-only and are not\nscanned, so `commands/` keeps one `.md`: `caveman-init.md`, which has no skill\ntwin. Guarded by `tests/verify_repo.py`.\n\n### Auto-generated / auto-synced — do not edit directly\n\nWe removed the agent-specific dotdir mirrors at the repo root (`.cursor/`, `.windsurf/`, `.clinerules/`, `.github/copilot-instructions.md`, root `caveman/SKILL.md`). They were never read by the installer — only used to self-apply caveman to this repo when a maintainer opened it in Cursor/Windsurf/Cline. Devs who want caveman in their editor while editing this repo should run `npx -y github:JuliusBrussee/caveman -- --with-init` once (writes per-repo rule files from `src/rules/caveman-activate.md` via `src/tools/caveman-init.js`). For per-user installs through the upstream skills CLI, `npx -y github:JuliusBrussee/caveman -- --only ` runs `npx skills add ... -a `.\n\nA handful of dotdir leftovers (`.junie/`, `.kiro/`, `.roo/`, `.agents/`) still hold a stale `cavecrew/SKILL.md` mirror from before the cleanup. They aren't read by anything in the current install path; remove on sight, no migration needed.\n\nWhat's left is the Claude Code plugin distribution (required by the plugin loader) and the release ZIP.\n\n| File | Synced from |\n|------|-------------|\n| `plugins/caveman/skills/caveman/SKILL.md` | `skills/caveman/SKILL.md` |\n| `plugins/caveman/skills/caveman-compress/SKILL.md` (+ `scripts/`) | `skills/caveman-compress/SKILL.md` (+ `scripts/`) |\n| `plugins/caveman/skills/cavecrew/SKILL.md` | `skills/cavecrew/SKILL.md` |\n| `plugins/caveman/agents/cavecrew-*.md` | `agents/cavecrew-*.md` |\n| `dist/caveman.skill` | ZIP of `skills/caveman/` directory (gitignored; rebuilt by CI on release) |\n\nSkills not in this table (`caveman-commit`, `caveman-review`, `caveman-help`, `caveman-stats`) are not mirrored into the Claude Code plugin distribution by CI. They reach Claude Code through the standalone hook + skill install path, and reach other agents via `npx skills add`. A `plugins/caveman/skills/caveman-stats/` directory is currently checked in as a hand-committed copy; the sync workflow does not touch it, so don't rely on edits there to propagate.\n\n---\n\n## CI sync workflow\n\n`.github/workflows/sync-skill.yml` triggers on main push when `skills/**/SKILL.md` or `agents/cavecrew-*.md` changes.\n\nWhat it does:\n1. Copies `skills/caveman/SKILL.md` and `skills/cavecrew/SKILL.md` into their `plugins/caveman/skills//` mirrors so the Claude Code plugin loader sees the latest behavior.\n2. Copies `skills/caveman-compress/SKILL.md` and its `scripts/` into `plugins/caveman/skills/caveman-compress/`.\n3. Copies `agents/cavecrew-*.md` into `plugins/caveman/agents/`.\n4. Rebuilds `dist/caveman.skill` (ZIP of `skills/caveman/`) for the release artifact.\n5. Commits and pushes with `[skip ci]` to avoid loops.\n\nCI bot commits as `github-actions[bot]`. After PR merge, wait for workflow before declaring release complete.\n\nThe old steps that mirrored SKILL.md and rules into root dotdirs (`.cursor/`, `.windsurf/`, `.clinerules/`, `.github/copilot-instructions.md`) are gone — those mirrors no longer exist. The old `caveman-compress/` → `skills/compress/` rename-on-sync is also gone now that compress lives at `skills/caveman-compress/`.\n\n---\n\n## Hook system (Claude Code)\n\nFour hooks in `src/hooks/` plus a `caveman-config.js` shared module, a `caveman-parse.js` shared mode-change parser and a `package.json` CommonJS marker.\n\n**Mode state is per session.** Each session's mode lives in `$CLAUDE_CONFIG_DIR/.caveman-sessions/.mode`, keyed by the `session_id` Claude Code puts in every hook payload *and* in the statusline's stdin JSON. `$CLAUDE_CONFIG_DIR/.caveman-active` survives as a last-write-wins compat mirror (falls back to `~/.claude/`).\n\n```\nSessionStart hook ──┐ ┌── UserPromptSubmit hook\n (session_id, │ │ (session_id, prompt)\n source) ▼ ▼\n $CLAUDE_CONFIG_DIR/.caveman-sessions/.mode\n │ │\n mirrors reads\n ▼ ▼\n .caveman-active caveman-statusline.sh ◀── session JSON on stdin\n (last-write-wins, [CAVEMAN] / [ULTRACAVE] / [MEGACAVE]\n compat only)\n```\n\nTwo invariants that are load-bearing, not stylistic:\n\n- **The legacy mirror never holds the literal `off`.** Deactivation deletes it. `off` is in `VALID_MODES`, so an older `caveman-mode-tracker.js` reading `off` from that path would pass its `!INDEPENDENT_MODES.has(...)` check and inject \"CAVEMAN MODE ACTIVE (off)\", and an older `caveman-statusline.sh` would render `[CAVEMAN:OFF]`. Mixed-version installs are real: plugin hooks and standalone hooks can both be registered at once, and `statusLine` holds an absolute path baked in at install time.\n- **`recordModeChange` compares against the session's own state, never the mirror.** That's why `readSessionModeRaw` exists alongside `resolveActiveMode` — diffing against the mirror would compare one session's transition to whatever another session wrote last and spam the log with phantom entries.\n\nBoth spellings of off are READ everywhere: a missing file (old semantics) and a literal `off` (new, durable).\n\n`src/hooks/package.json` pins the directory to `{\"type\": \"commonjs\"}` so the `.js` hooks resolve as CJS even when an ancestor `package.json` (e.g. `~/.claude/package.json` from another plugin) declares `\"type\": \"module\"`. Without this, `require()` blows up with `ReferenceError: require is not defined in ES module scope`.\n\nAll hooks honor `CLAUDE_CONFIG_DIR` for non-default Claude Code config locations.\n\n### `src/hooks/caveman-config.js` — shared module\n\nExports:\n- `getDefaultMode()` — resolves default mode in order: `CAVEMAN_DEFAULT_MODE` env var → repo-local config (`/.caveman/config.json` or `/.caveman.json`, walking up to the filesystem root; the first file that names a `defaultMode` wins, so a CLI-only `.caveman/config.json` does not hide a `.caveman.json`) → user config (`$XDG_CONFIG_HOME/caveman/config.json` / `~/.config/caveman/config.json` / on Windows `%APPDATA%\\caveman\\config.json`, then `~/.config/caveman/config.json`) → `'caveman'`. Config files may carry a BOM, be UTF-16LE, or hold comments and trailing commas. The env var short-circuits before any cwd walk. Repo-local config lets a team check in a per-project default without polluting every contributor's env or user config.\n- `findRepoConfigPath(start, accept)` — walks up from `start` (default `process.cwd()`) looking for the first `.caveman/config.json` or `.caveman.json` (that `accept(path)` approves, when given). Bounded to 64 ancestors. Refuses symlinked files (symmetric with `safeWriteFlag` / `readFlag`).\n- `safeWriteFlag(flagPath, content)` — symlink-safe flag write. Refuses if flag target or its immediate parent is a symlink. Opens with `O_NOFOLLOW` where supported. Atomic temp + rename. Creates with `0600`. Protects against local attackers replacing the predictable flag path with a symlink to clobber files writable by the user. Used by both write hooks. Silent-fails on all filesystem errors.\n- `validateSessionId(id)` — returns the id or `null`. Whitelist `^[A-Za-z0-9_-]{1,128}$`. **A session id becomes part of a filesystem path, so nothing may interpolate one without passing it through here first.** The symlink hardening in `safeWriteFlag` does not cover traversal.\n- `resolveActiveMode(claudeDir, sessionId)` — what mode is in effect: session file → legacy mirror, with both a missing file and a literal `off` collapsing to `null`. The reader every hook should use.\n- `readSessionModeRaw(claudeDir, sessionId)` — literal stored value for **this** session, no legacy fallback. Two callers only: `recordModeChange` (see the invariant above) and the SessionStart continuation branch, which has to tell a stored `off` apart from \"nothing stored yet\".\n- `writeSessionMode(claudeDir, sessionId, modeOrNull)` — the single writer. Writes `off` literally to the session file, unlinks the legacy mirror. Rejects anything outside `VALID_MODES`.\n- `writeSessionPrev` / `readSessionPrev` / `clearSessionPrev` — the displaced-prose-mode memory for one-shot skills (#599), scoped per session so two windows running `/caveman-commit` don't overwrite each other's return target.\n- `gcSessionStore(claudeDir, opts)` — mtime sweep of `.caveman-sessions/`, 14-day TTL (`CAVEMAN_SESSION_TTL_MS` overrides for tests), `maxDeletes` cap, refuses symlinks. Called from SessionStart on new sessions only — never on `compact`, which is frequent and shares the 5s hook budget.\n- `recordModeChange(claudeDir, newMode, sessionId)` — third arg tags the log entry; omitted (not null) when unknown, so pre-existing readers see the old shape.\n\n**Every function above accepts a `sessionId` that may be `null` or malformed and degrades to the legacy machine-wide behavior.** That is the entire backward-compatibility story: the old code path *is* the fallback branch, which is why the existing tests — none of which send a `session_id` — pass unchanged. The three hook entrypoints resolve these helpers individually (`cfg.writeSessionMode || `) rather than adding them to their `requireSibling` shape checks: a `caveman-config.js` from before per-session state satisfies those checks, and hard-failing over the newer exports would trade \"machine-wide mode, as it always worked\" for \"no state at all\" on exactly the plugin-cache-drift scenario #848 is about.\n\n### `src/hooks/caveman-activate.js` — SessionStart hook\n\nRuns on every SessionStart — `source` is `startup`, `resume`, `clear`, `compact` or `fork`. Four things:\n1. Reads the hook payload from stdin for `session_id`, `source` and `cwd`\n2. Resolves this session's mode and persists it via `writeSessionMode`\n3. Emits caveman ruleset as hidden stdout — Claude Code injects SessionStart hook stdout as system context, invisible to user\n4. Checks `settings.json` for statusline config; if missing, appends nudge to offer setup on first interaction (one-shot, gated by `.caveman-nudge-shown`)\n\n**`source` branching.** `RESET_SOURCES` is `{startup, clear}` — only those re-derive `getDefaultMode()`. Everything else (`compact`/`resume`/`fork`, an unrecognized source, and the watchdog's `unknown`) READS the stored mode via `readSessionModeRaw`, falling back to the legacy mirror for a session that predates the store, and only then to the default. Reading the LITERAL value is the point: #691 already branched on `source`, but it read the legacy flag where off is spelled \"no file\", so a deactivated session found nothing and re-derived the default anyway — \"stop caveman\" was still undone by the next auto-compaction. A stored `off` now short-circuits to `OK` with no ruleset. It still re-emits when a mode IS active: compaction is what prunes the rules out of context, which is the whole reason this hook runs on every source. `clear` counts as a fresh start (explicit user reset — nothing else in the conversation survives it, so neither should a \"stop caveman\" from before it); this deliberately differs from #691's comment, which grouped `clear` with the continuations.\n\n**Headless sessions start under `manual` (#377).** Whenever the hook falls back to the configured default (`startMode()`), a `CLAUDE_CODE_ENTRYPOINT` starting with `sdk-` (`claude -p`, Agent SDK) turns any non-`off` default into `manual`: tool probes that parse the reply get no ruleset until an explicit `/caveman`. Interactive entrypoints (`cli`, `claude-vscode`, `claude-desktop`, …) never match; an explicit `CAVEMAN_DEFAULT_MODE` env var opts back in. Hook test helpers drop `CLAUDE_CODE_ENTRYPOINT` from the env, or a headless runner flips every SessionStart test.\n\n**The stdin contour is load-bearing.** Activation runs on the first COMPLETE JSON object, not at EOF, with a 2000ms `PAYLOAD_WATCHDOG_MS` backstop and `process.stdin.unref()` in `finish()`. `pause()` alone is not enough — it stops reading but leaves the pipe handle referenced, so a host that holds the write end open (Windows pipe close lags arbitrarily, #729/#833) burns the whole 5s budget. The watchdog must NOT assume `startup`: it reports `unknown`, which preserves the session's stored mode rather than resetting it. Several suites also invoke this hook via `subprocess.run()` with no `input=`, inheriting a stdin that never reaches EOF — `tests/test_hooks.py::test_hook_never_blocks_on_stdin_that_never_closes` guards that path.\n\nSilent-fails on all filesystem errors — never blocks session start.\n\n**`--subagent`: the SubagentStart hook (#621).** SessionStart context reaches only the parent thread, so the same script is registered for SubagentStart with `--subagent` (plugin.json, `installer/install.js`, `src/hooks/install.{sh,ps1}`). It reuses the stdin reader and watchdog, resolves THIS session's mode via `resolveActiveMode` (a session with no stored state at all — SessionStart skipped or failed, or the session predates the store — falls back to the last-write-wins legacy mirror, the same degrade the tracker's reinforcement uses, so a subagent matches its parent thread; pinned in `tests/hooks/subagent-start.test.mjs`), and prints `{\"hookSpecificOutput\":{\"hookEventName\":\"SubagentStart\",\"additionalContext\":}}`. Nothing is printed when the session stored `off` (no \"stop caveman\" leak, #672; another window's mode never overrides a stored `off`), in a one-shot mode, for `cavecrew-*` agents (they carry their own ultracave voice), or under a repo `defaultMode: \"off\"` (#634, same gate as the tracker's reinforcement). Read-only: no mode write, no mode log, no GC, no nudge, no cavecrew model overrides. Uninstall needs nothing extra — `removeCavemanHooks` walks every event and matches the `caveman-activate.js` basename.\n\n### `src/hooks/caveman-mode-tracker.js` — UserPromptSubmit hook\n\nReads JSON from stdin — `session_id` scopes every read and write. Three responsibilities:\n\n**1. Slash-command activation.** If prompt starts with `/caveman`, writes the session's mode via `writeSessionMode`:\n- `/caveman` → configured default (see `caveman-config.js`, defaults to `caveman`)\n- `/ultracave` (alias `/caveman ultra`) → `ultracave`\n- `/megacave` (alias `/caveman wenyan`, any `wenyan-*`) → `megacave`\n- `/caveman lite` or `/caveman full` (legacy aliases) → `caveman`\n- `/caveman-commit` → `commit`\n- `/caveman-review` → `review`\n- `/caveman-compress` → `compress`\n\n**2. Natural-language activation/deactivation.** Matches phrases like \"activate caveman\", \"turn on caveman mode\", \"talk like caveman\" and writes the configured default mode. Matches \"stop caveman\", \"disable caveman\", \"normal mode\", \"deactivate caveman\" etc. and stores a durable `off` for the session. README promises these triggers, the hook enforces them.\n\n**3. Per-turn reinforcement.** When the session's mode is a non-independent one (i.e. not `commit`/`review`/`compress`), emits a small `hookSpecificOutput` JSON reminder so the model keeps caveman style after other plugins inject competing instructions mid-conversation. The full ruleset still comes from SessionStart — this is just an attention anchor.\n\n### `src/hooks/caveman-statusline.sh` — Statusline badge\n\nReads the session JSON Claude Code pipes to it on stdin, extracts `session_id` (pure bash — no `jq` dependency), and reads `.caveman-sessions/.mode`; falls back to `$CLAUDE_CONFIG_DIR/.caveman-active` when there is no usable id. Outputs colored badge string for Claude Code statusline:\n- `caveman` or empty → `[CAVEMAN]` (orange)\n- `off` → nothing at all. Never `[CAVEMAN:OFF]` — that reads as a mode rather than the absence of one\n- `ultracave` → `[ULTRACAVE]`, `megacave` → `[MEGACAVE]`; one-shots → `[CAVEMAN:]` (orange). Legacy stored values render through the same map\n\nStdin is bounded the same way as the SessionStart hook: `[ ! -t 0 ]` skips an interactive terminal, and `read -r -d '' -t 1` caps the wait. The timeout is an **integer on purpose** — macOS ships bash 3.2, which rejects `-t 0.3` with `invalid timeout specification`.\n\nThe statusline reports mode only. Old `.caveman-statusline-suffix` values are ignored; fixed-ratio savings estimates were removed because no measured baseline supported them. `/caveman-stats` records actual Claude output/cache-read counts and mode attribution with savings unknown. Gemini uses native `/stats model` and `/stats session`; never read Claude transcripts as another host's usage.\n\nConfigured in `settings.json` under `statusLine.command`. PowerShell counterpart at `src/hooks/caveman-statusline.ps1` for Windows. Both scripts symlink-refuse and whitelist-validate mode flag contents — never echo arbitrary bytes.\n\n### `src/hooks/caveman-stats.js --record` — SessionEnd hook\n\nSame script as `/caveman-stats`; the `--record` flag turns it into a silent recorder. Reads the SessionEnd payload (`session_id`, `transcript_path`) and appends one snapshot of that transcript's totals to `$CLAUDE_CONFIG_DIR/.caveman-history.jsonl`, so lifetime history fills in without the user running `/caveman-stats`. Only the transcript the host names is read — never the newest file on disk. Stdin follows the activate-hook contour: first complete JSON object, 2000ms `PAYLOAD_WATCHDOG_MS` (gives up without recording), `unref()` on finish. Always exits 0 and writes nothing to stderr — a SessionEnd failure would surface as a hook error while the user quits. Every installer (plugin manifest, `installer/install.js`, `src/hooks/install.{sh,ps1}`) writes `--record` unquoted after the quoted script path; `rewriteLegacyManagedHookCommands` carries trailing `--flag` args over when it moves a bare-`node` command to the absolute node path.\n\n### `src/hooks/caveman-host-session-start.js` — Cursor / Copilot CLI sessionStart hook\n\n`node caveman-host-session-start.js `, one script for hosts other than Claude Code. Emits the resolved mode's ruleset under the host's key: `additional_context` for `cursor`, `additionalContext` for `copilot`. The mode is `getDefaultMode()` resolved from the session's workspace (`cwd`, Cursor's `workspace_roots` or `CURSOR_PROJECT_DIR`), so `defaultMode` and repo `.caveman.json` apply; `off`, `manual`, one-shot modes, an unknown host or any failure print `{}`. Writes no state. The owned install at `/caveman/hooks/` reads its pinned `/caveman/skills/` before the shared resolver, which would otherwise find the host's unpinned `npx skills` copy first. Stdin follows the activate-hook contour.\n\n### Hook installation\n\n**Plugin install** — hooks wired automatically by plugin system.\n\n**Standalone install** — `installer/install.js` (the unified Node installer) copies hook files into `$CLAUDE_CONFIG_DIR/hooks/` and merges SessionStart + SubagentStart + UserPromptSubmit + SessionEnd + statusline into `settings.json`. Uses the JSONC-tolerant helpers in `installer/lib/settings.js` so a commented `settings.json` no longer crashes the merge. Defensive `validateHookFields` runs before every write to prevent a single malformed hook from poisoning the entire file (Claude Code Zod silently discards the whole `settings.json` on schema mismatch).\n\nThe `install.sh` / `install.ps1` shims at the repo root delegate to `installer/install.js` via `node` (local clone) or `npx -y github:JuliusBrussee/caveman` (curl|bash). No legacy fallback path remains — earlier `install.sh.legacy` / `install.ps1.legacy` files were removed.\n\n**Uninstall** — `npx -y github:JuliusBrussee/caveman -- --uninstall` (or `node installer/install.js --uninstall` from a clone). Strips caveman hook entries from `settings.json` via substring marker `caveman`, deletes hook files, and removes the Claude plugin / Gemini extension. Native skill copies use `installer/lib/provider-skills.js` and ownership journals; uninstall removes unchanged owned files while preserving foreign or edited content. Use the same vendor home overrides for install and uninstall. Delegated `npx skills add` installs remain managed by the host/upstream skill manager.\n\n---\n\n## Skill system\n\nSkills = Markdown files with YAML frontmatter consumed by Claude Code's skill/plugin system and by `npx skills` for other agents.\n\nEach skill has a human-facing `README.md` alongside the LLM-facing `SKILL.md`. The README explains what the skill does for users browsing GitHub; the SKILL.md is the prompt body the agent loads. Don't merge them — different audiences, different formats.\n\n### Three skills, one mode model\n\nThree self-contained skills, each 1:1 with a stored mode id: `caveman` (default voice), `ultracave` (grammar stripped), `megacave` (文言文). The SessionStart hook injects `skills//SKILL.md` whole; there is no per-level filtering. Legacy stored values map on read: `lite` and `full` → `caveman`, `ultra` → `ultracave`, every `wenyan*` → `megacave`. Writes emit new ids only. Mode persists until changed or session ends. Plan: `docs/technical/three-skills-refactor.md`.\n\n`defaultMode: \"manual\"` is a Claude Code startup policy, not a fourth mode. It starts inactive, stores only `off`, and explicit bare-command or natural-language activation resolves to `caveman`. Keep it out of `VALID_MODES`; only configuration accepts it. OpenCode maps this policy to its existing caveman default because its installer also supplies static AGENTS.md activation. `/caveman status` is read-only and must return before one-shot restoration or any mode-state mutation.\n\n### Auto-clarity rule\n\nCaveman drops to normal prose for: security warnings, irreversible action confirmations, multi-step sequences where fragment ambiguity risks misread, user confused or repeating question, questions the agent asks the user. Resumes after. Defined in skill — preserve in any SKILL.md edit.\n\n### caveman-compress\n\nSub-skill in `skills/caveman-compress/SKILL.md`. Takes file path, compresses prose to caveman style, writes to original path, saves backup at `.original.md`. Validates headings, code blocks, URLs, file paths, commands preserved. Retries up to 2 times on failure with targeted patches only. Requires Python 3.10+.\n\nThe slash command is `/caveman-compress` everywhere — same name in plugin and standalone install. CI no longer renames the directory on sync (the old `caveman-compress/` → `skills/compress/` sed rename is gone now that the source lives at `skills/caveman-compress/`).\n\n### caveman-commit / caveman-review\n\nIndependent skills in `skills/caveman-commit/SKILL.md` and `skills/caveman-review/SKILL.md`. Both have own `description` and `name` frontmatter so they load independently. caveman-commit: Conventional Commits, ≤50 char subject. caveman-review: one-line comments in `L: . .` format.\n\n---\n\n## Agent distribution\n\nHow caveman reaches each agent type:\n\n| Agent | Mechanism | Auto-activates? |\n|-------|-----------|----------------|\n| Claude Code | Plugin (hooks + skills) or standalone hooks | Yes — SessionStart hook injects rules; SubagentStart passes the session's mode to subagents |\n| Codex | `npx skills add -a codex` plus an owned SessionStart hook in `$CODEX_HOME/hooks.json` (installer, default on); plugin in `plugins/caveman/`; repo `.codex/hooks.json` and `.codex/config.toml` for this checkout | Yes — SessionStart hook, after the user trusts it once via `/hooks` |\n| Gemini CLI | Extension with `GEMINI.md` context file | Yes — context file loads every session |\n| opencode | Native plugin (`src/plugins/opencode/`) copied into `~/.config/opencode/plugins/caveman/` + `AGENTS.md` ruleset + skills/agents/commands directories. Plugin uses `session.created` and `tui.prompt.append` lifecycle hooks. No statusline (opencode TUI exposes no plugin-writable badge). | Yes — `session.created` writes flag, `AGENTS.md` carries always-on ruleset |\n| OpenClaw | Workspace skill at `~/.openclaw/workspace/skills/caveman/SKILL.md` (frontmatter merged with `version` + `always: true`) plus a marker-fenced bootstrap block in `~/.openclaw/workspace/SOUL.md`. Both writes go through `installer/lib/openclaw.js`; workspace path is overridable via `OPENCLAW_WORKSPACE`. | Yes — SOUL.md is auto-injected each turn under \"Project Context\" (subject to OpenClaw's 12K-per-file / 60K-total bootstrap caps) |\n| Cursor | Plugin (`.cursor-plugin/plugin.json`: skills + `hooks/hooks-cursor.json` sessionStart hook) or `--only cursor`: `npx skills add ... -a cursor -g` skills, then `installer/lib/cursor-native.js` owns cavecrew agents in `~/.cursor/agents/` (Claude `model:` dropped, `readonly: true` on investigator/reviewer) and the shared hook payload in `~/.cursor/caveman/` with one sessionStart entry merged into `~/.cursor/hooks.json`. Both hooks run `src/hooks/caveman-host-session-start.js cursor`. Per-repo `.cursor/rules/caveman.mdc` via `--with-init`. Pick plugin OR `--only cursor`, not both (two hooks inject twice). | Yes — sessionStart `additional_context`, honors `defaultMode` (off/manual inject nothing) |\n| Windsurf | `npx skills add ... -a windsurf` (default via `--only windsurf`); per-repo `.windsurf/rules/caveman.md` via `--with-init` | Yes — always-on rule |\n| Cline | `npx skills add ... -a cline` (default via `--only cline`); per-repo `.clinerules/caveman.md` via `--with-init` | Yes — Cline auto-discovers `.clinerules/` |\n| Copilot | `npx skills add ... -a github-copilot` (detected via the `copilot` CLI plus its `~/.copilot` dir, since AWS Copilot CLI ships a `copilot` binary too, or the VS Code/Cursor extension); per-repo `.github/copilot-instructions.md` + `AGENTS.md` via `--with-init`. When the Copilot CLI is present (`copilot` on PATH or `$COPILOT_HOME` set — not a bare `~/.copilot`, which `npx skills add -a github-copilot` itself creates) the installer also owns `$COPILOT_HOME/caveman/` (shared hook payload) and `$COPILOT_HOME/hooks/caveman.json` (sessionStart → `caveman-host-session-start.js copilot`); `--no-hooks` skips it. No userPromptSubmitted hook: Copilot drops its output. | Copilot CLI: yes — sessionStart `additionalContext`, honors `defaultMode`. VS Code Copilot Chat: repo-wide instructions via `--with-init` |\n| Grok Build | Owned skill copies into `$GROK_HOME/skills` (default `~/.grok`) plus a marker-fenced ruleset block in `$GROK_HOME/AGENTS.md`, appended/stripped through `installer/lib/openclaw.js`'s marker helpers | Yes — Grok loads `~/.grok/AGENTS.md` as global rules (docs-backed; no live binary run) |\n| Antigravity CLI (`agy`) | `--only antigravity-cli` stages a temp plugin (`plugin.json`, the nine skills, `rules/AGENTS.md` = `src/rules/caveman-activate.md`) and runs `agy plugin install `; agy copies it to `~/.gemini/config/plugins/caveman/` and owns it. Uninstall: `agy plugin uninstall caveman` when `agy plugin list` names it. No session-start hook exists in agy (PreInvocation fires before every model call), so no `defaultMode`. | Yes — plugin `rules/AGENTS.md` merges into agy's active rule set (verified agy 1.2.17) |\n| Continue, AiderDesk, Antigravity IDE/2.0 | Owned physical copies into each vendor's supported directory, honoring configured homes; separate explicit targets for the two Antigravity products | Host skill invocation; feature settings may be required |\n| Others (Junie, Trae, Warp, Tabnine, Mistral, Qwen, Devin, Droid, ForgeCode, Bob, Crush, iFlow, OpenHands, Qoder, Rovo Dev, Replit, …) | Delegated `npx skills` personal installs; Replit uses project scope. Configured iFlow/Crush roots use owned copies | Host skill invocation; `/caveman` where supported |\n\nopencode reaches Tier 1 minus the statusline (opencode's TUI has no plugin-writable badge). Mode flag lives at `~/.config/opencode/.caveman-active` for any external tooling that wants to surface it.\n\nFor agents without hook systems, the always-on snippet lives in `INSTALL.md`'s \"Want it always on?\" section — keep current with `src/rules/caveman-activate.md`.\n\n**Adding a new agent.** Edit the `PROVIDERS` array in `installer/install.js` — single source of truth, no more bash/PS1 dual-source drift. Each entry has `id`, `label`, `mech`, `detect` (clause spec like `command:foo||dir:$HOME/x`; `&&` joins terms that must all hold), optional `profile` (vercel-labs/skills slug), optional `soft: true` (config-dir-only detection).\n\n1. The profile slug must exist in upstream [vercel-labs/skills](https://github.com/vercel-labs/skills). Verify against the README before merging — wrong slugs cause `npx skills add` to fail at runtime, not at install-script load.\n2. Run `node installer/install.js --list` to confirm the new row renders correctly.\n3. Soft probes (config-dir-only) are fine but tag them with `soft: true`. They render with `(soft)` in `--list` so users know detection is best-effort.\n\n---\n\n## Evals\n\n`evals/` has three-arm harness:\n- `__baseline__` — no system prompt\n- `__terse__` — `Answer concisely.`\n- `` — `Answer concisely.\\n\\n{SKILL.md}`\n\nHonest delta = **skill vs terse**, not skill vs baseline. Baseline comparison conflates skill with generic terseness — that cheating. Harness designed to prevent this.\n\n`llm_run.py` calls `claude -p --system-prompt-file ... --output-format json` per (prompt, arm), isolated from user settings, plugins and MCP, saves text plus Claude-reported usage (input/output/cache tokens, cost) to `evals/snapshots/results.json` (`results..json` with `CAVEMAN_EVAL_LANG`). `measure.py` reads snapshot offline with tiktoken (OpenAI BPE — approximates Claude tokenizer, ratios meaningful, absolute numbers approximate). `CAVEMAN_EVAL_SET=fidelity` runs the regex-checked cases in `evals/prompts/fidelity.json` into `snapshots/fidelity.json`; `score_fidelity.py` scores it offline.\n\nAdd skill: drop `skills//SKILL.md`. Harness auto-discovers. Add prompt: append line to `evals/prompts/en.txt`.\n\nSnapshots committed to git. CI reads without API calls. Only regenerate when SKILL.md or prompts change.\n\n---\n\n## Benchmarks\n\n`benchmarks/` runs real prompts through Claude API (not Claude Code CLI), records raw token counts. Results committed as JSON in `benchmarks/results/`. Benchmark table in README generated from results — update when regenerating.\n\nTo reproduce: `uv run python benchmarks/run.py` (needs `ANTHROPIC_API_KEY` in `.env.local`).\n\n---\n\n## Key rules for agents working here\n\n- Edit `skills//SKILL.md` for behavior changes. Never edit synced copies under `plugins/caveman/skills/`.\n- Edit `src/rules/caveman-activate.md` for auto-activation rule changes. Never edit any per-agent rule copy a user has on their machine.\n- Edit `src/rules/caveman-openclaw-bootstrap.md` for the OpenClaw SOUL.md bootstrap snippet. Keep the `` / `` markers and the `Respond terse like smart caveman` sentinel — `installer/lib/openclaw.js` keys idempotency off both. If you change the embedded fallback in `installer/lib/openclaw.js`, keep it byte-equivalent to the file.\n- Per-skill human docs live in `skills//README.md`. The LLM-facing body is in `SKILL.md`. Don't merge them — different audiences.\n- Build artifacts go in `dist/`. Never check files into `dist/` manually — CI rebuilds them on push, and `dist/` is gitignored.\n- README most important file for user-facing impact. Optimize for non-technical readers. Preserve caveman voice.\n- `INSTALL.md` is the per-agent install reference. Keep the install table in `README.md` short and link out to `INSTALL.md` for the full matrix.\n- Benchmark and eval numbers must be real. Never fabricate or estimate.\n- CI workflow commits back to main after merge. Account for when checking branch state.\n- Hook files must silent-fail on all filesystem errors. Never let hook crash block session start.\n- Any new flag file write must go through `safeWriteFlag()` in `caveman-config.js`. Direct `fs.writeFileSync` on predictable user-owned paths reopens the symlink-clobber attack surface.\n- Mode state reads/writes go through the `caveman-config.js` session helpers (`resolveActiveMode` / `writeSessionMode` / …), never by joining a path by hand. Any `session_id` that reaches a path must pass `validateSessionId()` first.\n- **Keep mode-state logic in `caveman-config.js`.** `src/plugins/opencode/plugin.js` cannot `require()` from disk (compiled Bun binary) — it reads that file and evaluates it through `new Function(...)` with a `createRequire` that resolves only node built-ins. Parsing already lives in `caveman-parse.js` (#602) and loads the same way, so a second parser copy is no longer the risk; a THIRD home for the state primitives would be, because opencode would keep its own drifting version of them.\n- The two statusline scripts have no shared runtime with the JS, so they re-implement path resolution by hand. `tests/verify_repo.py::verify_powershell_static` greps both against the `SESSIONS_DIRNAME` and `SESSION_ID_RE` constants to catch drift — there is no behavioral `.ps1` test on the POSIX runners, so that grep is the only guard on the Windows badge.\n- Editing anything in `src/hooks/` means regenerating `src/hooks/checksums.sha256` (same file set, recomputed digests) — `tests/verify_repo.py` fails the build otherwise, and `installer/install.js` verifies remote hook downloads against the manifest for the pinned ref.\n- Hooks must respect `CLAUDE_CONFIG_DIR` env var, not hardcode `~/.claude`. Same for `installer/install.js` / statusline scripts.\n- **Any entrypoint that reads a host hook payload from stdin returns on the first complete JSON object, never at EOF.** Under the Windows pipe implementation the host's close lags arbitrarily (#729/#833, #949), so a reader that waits for EOF burns the host's whole budget with its work done. The readers that follow this rule: `caveman-activate.js`, `caveman-mode-tracker.js`, `caveman-stats.js --record` and `caveman-host-session-start.js` (per-chunk parse), `packages/cli/src/native-hook-fast.ts` (`stdin()`), `readHookStdin()` in `packages/cli/src/index.ts` (shrink-hook, memory recall, native-hook), and `readNativeHookPayload` in `proxy/cmd/caveman-proxy/main.go`. A new hook callback uses one of those, not `readStdin()` or `io.ReadAll`. Each has a keep-the-writer-open regression test; add one for any new reader.\n- `installer/install.js` is the only installer source. `install.sh` / `install.ps1` at repo root are 30-line shims that delegate to it. Never re-add per-OS install logic to the shims — that's how we got the Windows quoting bug (#249).\n- Any settings.json read in installer or hooks must go through `installer/lib/settings.js` `readSettings()` so JSONC comments don't crash the merge. Any settings.json write must run through `validateHookFields()` first.\n","browse/CLAUDE.md":"# browse — `caveman-browse` browser driver\n\n> **Repository routing:** do not continue Browse product work here. Source of\n> truth is `JuliusBrussee/caveman-browse`, local checkout\n> `/Users/julb/Desktop/GitHub/caveman-browse`. This directory is a consumer\n> copy; edit only for pinned integration, migration/removal, or an explicit\n> cross-repo sync. Accessibility-compressor work stays here in\n> `engine/compressors/axtree.go` because Engine is owned by this repo.\n\nLocal, agent-facing browser interaction for the open Caveman surface. It serves\nstdio MCP tools that read a real Chrome accessibility tree, compress it with the\nengine's forced-only `a11y` compressor, act on `uid` handles, and recover the\nbyte-exact original AX payload through CCR. Every saving here is `inferred`;\nBrowse never emits `verified`.\n\n## Layout\n- `session.go` — MCP tool handlers, engine/CCR integration, UID target cache.\n- `cdp.go` — chromedp-backed Mode-A dedicated Chrome driver and bounded\n actionability recipe.\n- `cmd/caveman-browse/` — stdio MCP binary.\n\n## Gotchas\n- This package may import CDP/network/browser dependencies. `public/mcp` may not.\n- `go test ./public/browse/...` is setup-free. `make test-browse` resolves an\n installed Playwright Chromium or system Chrome and runs the `integration`\n build-tagged CDP contract across the package and direct CLI; `make\n test-browser` adds extension tests and `make test-e2e` includes both.\n- The actionability layer is intentionally bounded: same-origin dashboards and\n predictable design-system controls, not arbitrary-open-web parity.\n- Unknown handles/actions fail closed with `cave_snake_code` errors.\n- Snapshot output is compact indented text, not JSON-lines. `query` keeps at most\n 12 highest-scoring task matches plus ancestors; recovery metadata exposes only\n UIDs actually shown. Keep `tokens_after` equal to exact agent-visible result\n cost and `view_tokens` equal to serializer output cost.\n- Direct CLI Chrome is detached so separate `snapshot`/`act`/`eval` processes\n can share a target. `close` must terminate it. Fresh `CAVEMAN_HOME` must work;\n state writes stay atomic and mode `0600`.\n- CDP action acknowledgement is not application settlement. Non-wait actions\n return `settled:false` and require a focused resnapshot for proof.\n- Navigation denies `file:`, `javascript:`, and privileged Chrome schemes.\n- Benchmark contract and reproducible Playwright comparison live in\n `BENCHMARK.md`; keep token budgets executable in tests.\n- **The uid map is `browser_snapshot`'s contract, not a side effect of a\n compression ratio.** On engine pass-through (no recovery handle — a tree that\n did not get smaller, or no CCR store) `snapshotTool` fails closed with\n `cave_browser_snapshot_uncompressed` and returns the prior page's uids intact;\n it MUST NEVER dump the raw AX tree into `uids` (strictly worse than not using\n Browse) nor wipe the target cache. Regressing this reopens issue #140.\n- **An `