brainclaw 1.8.0 → 1.9.0

package/docs/integrations/cline.md

@@ -1,6 +1,6 @@
 # Cline Integration
 
-brainclaw integrates with Cline through MCP tools, instruction rules, and lifecycle hooks. Cline is a Tier A agent — full MCP access, hooks, auto-approve support, skills, and CLI spawn capability for parallel lanes.
+brainclaw integrates with Cline through MCP tools, instruction rules, auto-approval, and CLI spawn capability for parallel lanes. Cline does not currently expose a Brainclaw-managed lifecycle hook surface.
 
 ## Auto-setup
 
@@ -51,9 +51,9 @@ Cline supports per-server `alwaysAllow` for auto-approving specific tools:
 - `.clinerules/live.md` — optional local live companion with current plans, claims, traps, candidates, and handoffs. Write it with `brainclaw export --format cline --write --include-live`; it remains gitignored.
 - Static content stays behavioural and lightweight. By default, live state flows through MCP; the live companion is an optional parity/backstop file.
 
-## SKILL.md discovery
-
-Cline auto-discovers skills from `.clinerules/`, `.claude/skills/`, and `.agents/skills/`. brainclaw writes a single `.agents/skills/brainclaw/SKILL.md` that Cline picks up automatically.
+## SKILL.md discovery
+
+Cline may discover skills from agent-specific directories depending on the installed extension/version. Brainclaw's current Cline writer configures MCP and `.clinerules/brainclaw.md`; it does not write a Cline-specific SKILL.md.
 
 ## Headless invocation
 
@@ -69,11 +69,11 @@ The `-y` flag (YOLO mode) disables interactive approval prompts so the spawned w
 
 | Field | Value |
 |-------|-------|
-| Tier | A |
-| MCP | yes |
-| Hooks | yes |
-| Auto-approve | yes (`alwaysAllow` per server, `-y` per session) |
-| Skills | yes |
+| Tier | A |
+| MCP | yes |
+| Hooks | no |
+| Auto-approve | yes (`alwaysAllow` per server, `-y` per session) |
+| Skills | no Brainclaw-specific writer |
 | CLI spawnable | yes |
 | Max concurrent tasks | 3 |
 | Workflow model | interactive |
@@ -82,7 +82,6 @@ The `-y` flag (YOLO mode) disables interactive approval prompts so the spawned w
 
 ## Caveats
 
-- **Hook support varies by platform**: Cline hooks are reliable on macOS/Linux but the Windows path is less exercised. brainclaw generates hooks that gracefully degrade when the runtime doesn't honour them — the templateTier stays A regardless.
-- **Cline / Roo / Kilocode family**: Cline shares its config-pattern lineage with Roo Code and Kilocode. The directory names differ (`.clinerules/` vs `.roo/rules/` vs `.kilo/rules/`) but the auto-discovery model is the same.
+- **Cline / Roo / Kilocode family**: Cline shares its config-pattern lineage with Roo Code and Kilocode. The directory names differ (`.clinerules/` vs `.roo/rules/` vs `.kilo/rules/`) but the auto-discovery model is the same.
 - **Project-scoped MCP**: unlike machine-scoped agents (Cursor, Windsurf), Cline's MCP config lives in the repo. Each repo gets its own brainclaw registration.
 - **Long prompts**: inline arg supports up to 8000 chars before falling back to inbox-structured delivery. Briefs longer than that should arrive via inbox.

package/docs/integrations/codex.md

@@ -1,6 +1,6 @@
 # Codex Integration
 
-brainclaw integrates with OpenAI's Codex CLI through MCP tools and shared instruction files. Codex is a Tier A agent — full MCP access, lifecycle hooks, skills support, and headless CLI spawn capability.
+brainclaw integrates with OpenAI's Codex CLI through MCP tools and shared instruction files. Codex has MCP access, universal skills support, and headless CLI spawn capability, but no native lifecycle hook surface.
 
 ## Auto-setup
 
@@ -61,7 +61,7 @@ Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started
 |-------|-------|
 | Tier | A |
 | MCP | yes |
-| Hooks | yes |
+| Hooks | no |
 | Auto-approve | manual (per-tool approval) |
 | Skills | yes |
 | CLI spawnable | yes |

package/docs/integrations/continue.md

@@ -6,9 +6,9 @@ brainclaw integrates with Continue through MCP tools and project-scoped rules, g
 
 `brainclaw init` detects Continue and writes `.continue/rules/brainclaw.md` automatically. Or manually:
 
-```bash
-brainclaw export --format continue-rules --write
-```
+```bash
+brainclaw export --format continue --write
+```
 
 ## MCP configuration
 
@@ -32,7 +32,7 @@ Per-server YAML configs are also supported in `.continue/mcpServers/*.yaml`.
 
 Continue uses a separate permissions file at `~/.continue/permissions.yaml`. Tool-level control uses `--allow`, `--ask`, and `--exclude` flags on the CLI.
 
-brainclaw does not yet emit `permissions.yaml` automatically — configure manually if running headless.
+`brainclaw setup-machine` writes `~/.continue/permissions.yaml` when Continue is selected. Configure it manually only if you need stricter local policy than Brainclaw's generated defaults.
 
 ## SKILL.md discovery
 
@@ -55,6 +55,6 @@ cn /path/to/project
 ## Caveats
 
 - **No hooks**: Continue delegates hook-like behavior to VS Code extensions. No native pre-prompt injection.
-- **No auto-approve writer**: brainclaw does not emit `permissions.yaml` yet — tool approval must be configured manually.
+- **Permissions are machine-local**: Brainclaw can write `~/.continue/permissions.yaml`, but it is not committed with the project.
 - **No native subagents**: Continue does not expose subagent orchestration.
 - **Windows**: Works via VS Code extension; CLI (`cn`) requires Node.js on PATH.

package/docs/integrations/copilot.md

@@ -4,10 +4,12 @@ brainclaw integrates with GitHub Copilot through MCP tools, instruction files, a
 
 ## Auto-setup
 
-`brainclaw init` detects Copilot (`gh copilot` or `copilot` CLI installed) and writes:
-
-- `.github/copilot-instructions.md` — instruction file Copilot reads automatically on each prompt
-- MCP registration at `~/.copilot/mcp-config.json` (machine-level fallback) and/or project-level `.github/copilot/mcp-config.json`
+`brainclaw init` detects Copilot (`gh copilot` or `copilot` CLI installed) and writes:
+
+- `.github/copilot-instructions.md` — instruction file Copilot reads automatically on each prompt
+- `.vscode/settings.json` and `.vscode/mcp.json` — project-level MCP registration used by VS Code/Copilot surfaces
+- `.github/copilot/hooks.json` — session lifecycle hooks where supported
+- `.github/skills/brainclaw-context/SKILL.md` and `.agents/skills/brainclaw/SKILL.md` — Copilot and cross-agent skill discovery
 
 Manual regeneration:
 
@@ -18,14 +20,14 @@ brainclaw export --format copilot-instructions --write --include-live
 
 ## MCP configuration
 
-Copilot reads MCP servers from `~/.copilot/mcp-config.json`:
-
-```json
-{
-  "mcpServers": {
-    "brainclaw": {
-      "command": "npx",
-      "args": ["-y", "brainclaw@latest", "mcp"]
+VS Code/Copilot reads project MCP configuration from `.vscode/settings.json` and `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"]
     }
   }
 }

package/docs/integrations/openclaw.md

@@ -38,12 +38,13 @@ brainclaw enable-agent openclaw
 
 This copies the brainclaw skill to `~/.openclaw/workspace/skills/brainclaw/`.
 
-Or manually:
-
-```bash
-mkdir -p ~/.openclaw/workspace/skills/brainclaw
-cp "$(npm root -g)/brainclaw/skills/openclaw/SKILL.md" ~/.openclaw/workspace/skills/brainclaw/
-```
+Or manually:
+
+```bash
+brainclaw export --format openclaw --output /tmp/brainclaw-openclaw-skill.md
+mkdir -p ~/.openclaw/workspace/skills/brainclaw
+cp /tmp/brainclaw-openclaw-skill.md ~/.openclaw/workspace/skills/brainclaw/SKILL.md
+```
 
 ### Initialize a project
 

package/docs/integrations/overview.md

@@ -71,16 +71,16 @@ The agent cannot call brainclaw tools at all. The instruction file or SKILL.md b
 | Agent | MCP | Instruction file | Hooks | Auto-approve | Skills |
 |---|---|---|---|---|---|
 | **Claude Code** | ✔ project + global | CLAUDE.md | ✔ pre-prompt + stop | ✔ permissions | ✔ /brainclaw |
-| **Cursor** | ✔ global | .cursor/rules/ + MDC | ◐ alwaysApply MDC | — | — |
-| **Windsurf** | ✔ global | .windsurfrules | ◐ session trigger | — | — |
+| **Cursor** | ✔ global | .cursor/rules/ + MDC | ✔ workspace hooks | — | ✔ universal skills |
+| **Windsurf** | ✔ global | .windsurfrules + .windsurf/rules/ | — | ✔ alwaysAllow | — |
 | **Cline** | ✔ project | .clinerules/ | — | ✔ autoApprove | — |
 | **Roo** | ✔ project | .roo/rules/ | — | ✔ alwaysAllow | — |
-| **Continue** | ✔ both | .continue/rules/ | — | — | — |
-| **Kilocode** | ✔ both | .kilo/rules/ + AGENTS.md | — | ✔ alwaysAllow | — |
-| **OpenCode** | ✔ project | AGENTS.md | — | — | — |
-| **Codex** | ✔ global | AGENTS.md | — | — | — |
+| **Continue** | ✔ both | .continue/rules/ | — | ✔ permissions.yaml | — |
+| **Kilocode** | ✔ both | .kilo/rules/ + AGENTS.md | — | ✔ alwaysAllow | ✔ universal skills |
+| **OpenCode** | ✔ project | AGENTS.md | — | — | ✔ universal skills |
+| **Codex** | ✔ global | AGENTS.md | — | — | ✔ universal skills |
 | **Gemini CLI** | ✔ global | GEMINI.md | — | — | — |
-| **GitHub Copilot** | ✔ global + project | .github/copilot-instructions.md | — | manual (per-call) | ✔ brainclaw-context |
+| **GitHub Copilot** | ✔ project | .github/copilot-instructions.md | ✔ workspace hooks | manual (per-call) | ✔ brainclaw-context + universal skills |
 | **Mistral Vibe** | ✔ project + user (TOML) | AGENTS.md | — | `--auto-approve` flag | ✔ universal skill |
 | **Hermes** | ✔ global (YAML) | AGENTS.md | — | — | ✔ universal skill |
 | **OpenClaw** | — | — | — | — | ✔ brainclaw skill |

package/docs/integrations/roo.md

@@ -6,9 +6,9 @@ brainclaw integrates with Roo through MCP tools and project-scoped rules, provid
 
 `brainclaw init` detects Roo and writes `.roo/rules/brainclaw.md` automatically. Or manually:
 
-```bash
-brainclaw export --format roo-rules --write
-```
+```bash
+brainclaw export --format roo --write
+```
 
 ## MCP configuration
 

package/docs/integrations/windsurf.md

@@ -6,9 +6,9 @@ brainclaw integrates with Windsurf through MCP tools and instruction rules, prov
 
 `brainclaw init` detects Windsurf and writes `.windsurfrules` automatically. Or manually:
 
-```bash
-brainclaw export --format windsurfrules --write
-```
+```bash
+brainclaw export --format windsurf --write
+```
 
 ## MCP configuration
 
@@ -49,14 +49,14 @@ Windsurf supports `alwaysAllow` as an array on each MCP server entry:
 }
 ```
 
-brainclaw does not yet emit `alwaysAllow` for Windsurf automatically.
+`brainclaw setup-machine` emits the Windsurf MCP config with `alwaysAllow` for the Brainclaw tool surface.
 
 ## Instruction files
 
 - `.windsurf/rules/*.md` — modern format (recommended), multiple rule files
 - `.windsurfrules` — legacy single-file format (still supported)
 
-brainclaw currently emits the legacy format. Modern `.windsurf/rules/` support is planned.
+`brainclaw export --format windsurf --write` writes the legacy `.windsurfrules` instruction file. Project setup also writes `.windsurf/rules/brainclaw.md` when Windsurf is selected, so modern rule discovery is covered.
 
 ## SKILL.md discovery
 
@@ -77,7 +77,7 @@ Windsurf does not offer a headless CLI. It runs as a Docker-based environment
 
 - **Machine-scoped MCP**: The config at `~/.codeium/windsurf/mcp_config.json` is global, not per-project. All projects share the same server list.
 - **No hooks**: Cascade Hooks exist but are limited to logging — no pre-prompt injection.
-- **Legacy format**: brainclaw currently writes `.windsurfrules` (single file). Modern `.windsurf/rules/` multi-file support is planned (P5).
+- **Two rule paths**: `.windsurfrules` remains the portable export target; `.windsurf/rules/brainclaw.md` is written during project setup for modern Windsurf rule discovery.
 - **No headless**: Cannot be used as a brainclaw dispatch target.
 - **Plan Mode**: Windsurf's "megaplan" mode is separate from brainclaw plans — they don't conflict but don't interoperate.
 - **Windows/Linux**: Works on all platforms via the Windsurf IDE.

package/docs/mcp-schema-changelog.md

@@ -10,6 +10,17 @@ guarantees this changelog follows.
 
 ## Unreleased
 
+**Changed — agent-UX read-path surface (pln#542)**
+- `bclaw_work`, `bclaw_context`, `bclaw_find`, `bclaw_get`, `bclaw_search`
+  gain an optional `budget_tokens` argument (relevance-ranked fill).
+- `bclaw_work` compact payload now includes a trimmed `context_diff`
+  (event-cursor sourced, all intents) and facade responses carry
+  `next_actions` affordances.
+- `bclaw_quick_capture` gains an optional caller-asserted `type` argument;
+  contradiction detection is advisory metadata (no longer blocks promotion).
+- No tool was removed or renamed; no required argument changed.
+- MCP public surface fingerprint: `sha256:eaa8865070b10401`
+
 **Changed — JSON Schema generation shift (pln#486, zod 4 migration)**
 - Migration from zod 3.24 → 4.3.6 changes the introspection output that
   feeds `tools/list`. Schemas are semantically equivalent but the emitted
@@ -93,8 +104,24 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:333be7c3cda7e166`
-  (updated 2026-06-09: added the `preflight` boolean to the bclaw_coordinate
+- MCP public surface fingerprint: `sha256:b1d3c6a00a224509`
+  (updated 2026-06-14: journal ON by default + `migrate --enable-journal`,
+  registry post-image families + verify gate, and capped auto-handoff diff
+  preview on `bclaw_get`; pln#567/#568/#569.
+  Previous: `sha256:21fa9544977a3754`,
+  updated 2026-06-11b: observability surfaces — composite
+  `attention_required` in board_summary, observer-mode read flags,
+  `bootstrap_verdict` in FacadeResponse; pln#557/#558/#559.
+  Previous: `sha256:8f86d3998f8a24e3`,
+  updated 2026-06-11: uninitialized setup mode — the server now boots with
+  a minimal catalog on a missing project store instead of exit(1), and the
+  empty-memory decision rule is surfaced in setup/work hints; pln#556.
+  Previous: `sha256:eaa8865070b10401`,
+  updated 2026-06-10: agent-UX read-path surface — `budget_tokens` on the
+  read tools, `context_diff`/`next_actions` in facade payloads,
+  caller-asserted `type` on quick_capture; see the Unreleased entry, pln#542.
+  Previous: `sha256:333be7c3cda7e166`,
+  updated 2026-06-09: added the `preflight` boolean to the bclaw_coordinate
   inputSchema — pln#533, the pre-flight spawn validation for open_loop reviews
   (run one trivial validation spawn per reviewer before opening the loop so an
   environment death surfaces with a clear reason instead of a generic timeout).

package/docs/quickstart.md

@@ -6,46 +6,46 @@ Get brainclaw running in your project in under 5 minutes.
 
 If you're about to cut a release that changes the CLI, MCP, or context surface, run the checklist in [release-maintenance.md](release-maintenance.md) before publishing a local pack or npm build.
 
-## Step 1: Install
-
-```bash
-npm install -g brainclaw
-```
-
-Requires Node.js 20+. Verify with `brainclaw --version`.
-
-## Step 2: Bootstrap this machine
-
-```bash
-brainclaw setup-machine --yes
-```
-
-This configures the agents Brainclaw can see on the current machine and writes the machine-level MCP/user files it manages. It does **not** initialize the current repository yet.
-
-## Step 3: Initialize or refresh your project
-
-```bash
-cd your-project
-brainclaw init
-```
-
-**What happens:**
-- Creates `.brainclaw/` when the project is new, or refreshes it safely when it already exists
-- Detects your coding agent (Claude Code, Codex, Cursor, Copilot, Cline, Mistral Vibe, etc.)
-- Refreshes the detected agent's project and machine integration files when applicable
-- Writes instruction files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/brainclaw.md`, etc.)
-- Installs session hooks (if supported by your agent)
-- Adds `.brainclaw/` to `.gitignore`
-
-If you want the explicit path for a second or late-arriving agent on an already initialized project, use:
-
-```bash
-brainclaw enable-agent <agent-name>
-```
-
-If you have multiple repos, use `brainclaw setup --yes` instead — it bootstraps the machine, scans your project directories, and initializes everything at once.
-
-## Step 4: Restart your agent
+## Step 1: Install
+
+```bash
+npm install -g brainclaw
+```
+
+Requires Node.js 20+ (`engines.node = ">=20.0.0"`). CI exercises Node 22 (Active LTS) and Node 24 (current LTS) — Node 22 or 24 is the recommended runtime; Node 20 still installs but is no longer CI-verified since its April 2026 EOL. Verify with `brainclaw --version`.
+
+## Step 2: Bootstrap this machine
+
+```bash
+brainclaw setup-machine --yes
+```
+
+This configures the agents Brainclaw can see on the current machine and writes the machine-level MCP/user files it manages. It does **not** initialize the current repository yet.
+
+## Step 3: Initialize or refresh your project
+
+```bash
+cd your-project
+brainclaw init
+```
+
+**What happens:**
+- Creates `.brainclaw/` when the project is new, or refreshes it safely when it already exists
+- Detects your coding agent (Claude Code, Codex, Cursor, Copilot, Cline, Mistral Vibe, etc.)
+- Refreshes the detected agent's project and machine integration files when applicable
+- Writes instruction files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/brainclaw.md`, etc.)
+- Installs session hooks (if supported by your agent)
+- Adds `.brainclaw/` to `.gitignore`
+
+If you want the explicit path for a second or late-arriving agent on an already initialized project, use:
+
+```bash
+brainclaw enable-agent <agent-name>
+```
+
+If you have multiple repos, use `brainclaw setup --yes` instead — it bootstraps the machine, scans your project directories, and initializes everything at once.
+
+## Step 4: Restart your agent
 
 Your coding agent needs to reload to pick up the new MCP configuration.
 
@@ -58,7 +58,7 @@ Your coding agent needs to reload to pick up the new MCP configuration.
 | **Windsurf** | Reload the editor |
 | **Copilot** | Reload VS Code window (uses instruction file, not MCP) |
 
-## Step 5: Verify it works
+## Step 5: Verify it works
 
 After reloading, tell your agent:
 
@@ -76,7 +76,7 @@ brainclaw agent-board     # what each agent sees
 brainclaw context         # current project memory
 ```
 
-## Step 6: Start using brainclaw
+## Step 6: Start using brainclaw
 
 ### For agents with MCP (most agents)
 
@@ -109,11 +109,12 @@ The CLI is for inspection, scripting, and fallback:
 
 ```bash
 brainclaw plan create "Implement auth module" --priority high
-brainclaw plan list
-brainclaw claim list
-brainclaw context --for src/auth/routes.ts
-brainclaw export --detect --write    # regenerate all instruction files
-```
+brainclaw plan list
+brainclaw claim list
+brainclaw context --for src/auth/routes.ts
+brainclaw export --detect --write    # regenerate the detected agent instruction file
+brainclaw export --all               # regenerate all known instruction files
+```
 
 ## Onboarding an existing project
 

package/docs/security.md

@@ -4,8 +4,10 @@ brainclaw is designed to be safe by default.
 
 ## Security model
 
-### No network access
-The CLI does not need to call external services to function.
+### No network access by default
+The CLI does not need to call external services to function. The optional
+supply-chain gate (see below) is the one feature that talks to a remote
+service, and it is off until explicitly enabled.
 
 ### No telemetry
 brainclaw does not collect or send usage data.
@@ -19,35 +21,192 @@ That makes review easier, but it also means users must be careful about what the
 
 ## Built-in safety behaviors
 
-brainclaw warns when content appears sensitive, for example when text includes patterns such as:
+### Content scanning (scanText)
 
-- `api_key`
-- `secret`
-- `token`
-- `password`
+Whenever content is added to `.brainclaw/` brainclaw scans the text in three
+layers:
 
-It can also warn about sensitive paths such as:
+1. **User-configured regex patterns** from `redaction.patterns`. The
+   defaults catch words like `api_key`, `secret`, `token`, `password`.
+2. **Structural detectors** for well-known token shapes — GitHub PATs
+   (`ghp_`, `gho_`, `github_pat_…`), AWS access keys (`AKIA…`/`ASIA…`),
+   Google API keys (`AIza…`), Slack tokens and webhooks, Stripe
+   `sk_live_/sk_test_` keys, JWTs, PEM-encoded private keys, and URLs
+   with embedded `user:password@host` credentials.
+3. **Entropy detector** that flags high-Shannon-entropy substrings near
+   a secret keyword (api_key/token/secret/password/auth/...). This
+   catches custom-shaped keys the structural list does not enumerate.
 
-- `.env`
-- `secrets/`
+In `security.mode: warn` matches surface as warnings; in
+`security.strict_redaction: true` (or `security.mode: strict`) the same
+matches block the write.
 
-Redaction behavior is configurable in `config.yaml`:
+### Sensitive paths
+
+When `security.block_sensitive_paths: true` (default), content that
+references paths like `.env`, `secrets/`, `.git/`, or `node_modules/`
+emits a warning.
+
+### Configuration
 
 ```yaml
 security:
-  mode: warn               # 'warn' or 'strict'
+  mode: warn               # 'warn' or 'strict' — affects redaction scanning
   strict_redaction: false  # if true, blocks entries with sensitive content
   block_sensitive_paths: true
+  token_detection:
+    enabled: true          # turn off all structural + entropy detection
+    entropy:
+      enabled: true
+      min_length: 32       # minimum substring length to consider
+      min_entropy: 4.0     # minimum Shannon entropy (bits/char)
+    detectors:             # per-detector override map; explicit false disables a detector
+      aws_access_key: true
+      jwt: true
+
+redaction:
+  enabled: true
+  patterns:
+    - '(?i)api[_-]?key'
+    - '(?i)secret'
+    - '(?i)token'
+    - '(?i)password'
+```
+
+## Supply-chain pre-install gate
+
+`brainclaw setup-security` enables a preinstall gate that intercepts
+`npm`/`pnpm`/`yarn`/`pip`/`pip3` install commands and asks Socket.dev's
+scoring service whether the requested packages are risky.
+
+```
+brainclaw setup-security --mode advisory    # default — warn-only
+brainclaw setup-security --mode enforced    # block risky installs
 ```
 
+### Advisory vs enforced
+
+The mode determines what happens when the gate decides a package is
+risky:
+
+- **advisory** — verdicts are surfaced (printed warning, security trap
+  created) but the install is *not* aborted.
+- **enforced** — a `block` verdict aborts the install with a non-zero
+  exit code.
+
+The mode is read from `security.preinstall.mode` and can be overridden
+per call with `brainclaw check-security --mode <advisory|enforced>`.
+
+### Exit codes
+
+`brainclaw check-security` emits exit codes that already encode the mode
+decision, so wrapper scripts are mode-agnostic:
+
+| Exit | Meaning                                                    |
+|------|------------------------------------------------------------|
+| 0    | pass — no risky packages                                   |
+| 1    | warn — advisory-mode block, or warn-threshold verdict      |
+| 2    | block — enforced-mode block; the wrapper aborts the install|
+
+The wrapper scripts (`<.brainclaw/security/bin>/npm`, `pnpm`, `yarn`,
+`pip`, `pip3` and their `.ps1` counterparts) call the CLI and react
+purely to the exit code, so flipping advisory↔enforced is a config
+change — no regeneration required.
+
+### Composite scoring
+
+Each package gets five sub-scores from Socket (supply-chain,
+vulnerability, quality, maintenance, license) on a 0–100 scale. The
+gate combines them into a single composite using configurable weights:
+
+```yaml
+security:
+  preinstall:
+    weights:
+      supply_chain: 0.35
+      vulnerability: 0.30
+      quality: 0.15
+      maintenance: 0.15
+      license: 0.05
+    thresholds:
+      composite_pass: 70        # composite >= 70 → pass
+      composite_warn: 50        # composite >= 50 but < 70 → warn; below → block
+      supply_chain_block: 30    # hard block when supply_chain < 30
+      vulnerability_block: 20   # hard block when vulnerability < 20
+```
+
+Weights are normalized to sum to 1.0 automatically — a config like
+`{ supply_chain: 1, vulnerability: 1 }` is rescaled rather than
+producing composites above 100. Thresholds are clamped to `[0,100]`
+and `composite_warn` is capped at `composite_pass` so the verdict
+function stays monotonic.
+
+### Allowlist / denylist
+
+```yaml
+security:
+  preinstall:
+    allowlist:
+      - npm:internal-pkg            # ecosystem-scoped
+      - npm:axios@1.14.0            # exact version pin
+      - lodash                       # bare name — any ecosystem, any version
+    denylist:
+      - npm:axios@1.14.1            # known-compromised version
+      - pypi:bad-pkg
+```
+
+Matching is exact on each component. Bare names match by package name
+only; an `ecosystem:` prefix scopes the match to that ecosystem;
+appending `@version` (or `==version` for pip-style) requires an exact
+version. The wildcard `@*` matches any version (useful for explicit
+"any version" entries).
+
+This is a hard tightening from the MVP: previously `denylist: ['lodash']`
+matched any package whose purl contained the substring `lodash`, so
+`react-lodash` was silently blocked. The new matcher requires exact
+package-name equality.
+
+### Package extraction sources
+
+`check-security` can pull the list of packages from three places, which
+may be combined:
+
+- `--packages axios,express@1.2.3` — comma-separated specs
+- `--requirements requirements.txt` — pip-style requirements file;
+  recursive `-r` includes, env markers, and extras are handled
+- `--lockfile package-lock.json` — npm package-lock (v1, v2, v3);
+  scans top-level direct deps and devDeps
+
+The wrappers auto-translate `npm install -r foo.txt` → `--requirements`,
+skip filesystem paths and URL specs that aren't registry packages
+(`./local-pkg`, `git+https://…`, `*.tgz`, `*.whl`), and handle the
+common npm/pip flag conventions.
+
+### Offline / fetch-error fallback
+
+When the Socket call fails (network down, service unreachable), the
+gate uses `security.preinstall.fallback_on_error`:
+
+- `block` — fail closed regardless of mode
+- `warn` — surface a warning, continue with whatever cached scores
+  exist; if no cache exists the gate exits with code 1
+- `pass`  — silent fall-through (the install proceeds)
+
+Cached scores have a TTL of `cache_ttl_hours` (default 24) and live
+in `.brainclaw/security/cache.json`.
+
 ## Recommended stance
 
-- do not store secrets
+- do not store secrets — even with detection, the safer move is to never
+  write them
 - review what gets committed
 - keep machine-local observations machine-local when appropriate
 - use stricter redaction settings in sensitive environments
+- run `setup-security --mode advisory` first; flip to `enforced` once
+  the team has gotten used to the verdicts
 
 ## Important nuance
 
-brainclaw reduces hidden behavior, but it does not remove the need for operational discipline.
-It warns; the team still decides what belongs in shared memory.
+brainclaw reduces hidden behavior, but it does not remove the need for
+operational discipline. It warns; the team still decides what belongs
+in shared memory.

package/docs/storage.md

@@ -7,7 +7,7 @@ brainclaw is local-first and workspace-centric.
 ```text
 .brainclaw/
   config.yaml                    ← Project configuration
-  project.md                     ← Derived readable view (best-effort, regenerable)
+  project.md                     ← Legacy derived readable view (best-effort, regenerable)
   events.jsonl                   ← Append-only event log (agent notifications)
   audit.log                      ← Append-only audit trail (before/after snapshots)
   memory/
@@ -42,7 +42,9 @@ Benefits:
 - isolated corruption (one bad file does not affect others)
 
 ### Derived views are best-effort
-`project.md` is a **derived view** regenerated from canonical state via `rebuildProjectMd()`. It is not a write target — it can always be rebuilt from the JSON files using `brainclaw rebuild`.
+`.brainclaw/project.md` is a **legacy derived view** regenerated from canonical state via `rebuildProjectMd()`. It is not a write target and no longer carries live claims, plans, handoffs, or runtime state — use `brainclaw agent-board`, `brainclaw context`, or MCP board/context tools for that operational data.
+
+Root `PROJECT.md` is different: it is the durable project vision and should contain stable product, architecture, and contribution guidance that does not expire every session.
 
 Failures to regenerate `project.md` are logged but never block mutations. If it gets stale, `brainclaw doctor` detects the drift.