brigade-cli 0.11.0__tar.gz → 0.13.0__tar.gz

{brigade_cli-0.11.0 → brigade_cli-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brigade-cli
-Version: 0.11.0
+Version: 0.13.0
 Summary: AI agent memory, handoffs, and local guardrails for Codex, Claude Code, OpenCode, Hermes, and OpenClaw.
 Author-email: Solomon Neas <me@solomonneas.dev>
 License: MIT
@@ -35,7 +35,7 @@ Dynamic: license-file
 <h1 align="center">Brigade CLI</h1>
 
 <p align="center">
-  <strong>AI agent memory, handoffs, and local guardrails for Codex, Claude Code, OpenCode, and over a dozen other harnesses.</strong>
+  <strong>One canonical source for the MCP servers, tools, and memory your AI coding agents share, merged into each tool's native config with a review gate and a receipt for every change. Local files, no daemon, no lock-in.</strong>
 </p>
 
 <p align="center">
@@ -47,46 +47,72 @@ Dynamic: license-file
 
 Your agents run loops. Brigade keeps the receipts.
 
+## What it does
+
+You run more than one agent CLI. Each one keeps its MCP servers in its own config file, its memory in its own silo, and writes to both without review. Brigade is the local layer that fixes that. You keep one canonical source for your MCP servers, your tool and skill catalog, and your memory, and Brigade merges each into the tools you actually use: MCP servers into each tool's native config, tools and skills projected into each harness, and one shared memory owned in one place. A review gate sits in front of anything that gets written, and every consequential change lands a receipt you can grep, diff, and roll back. No daemon, no hosted service, no vendor lock-in: it writes plain files in your repo when you run a command, and that is all it does.
+
 ## Try it in 60 seconds
 
 ```bash
 pipx install brigade-cli
+pipx ensurepath          # then open a new shell so `brigade` is on PATH
 brigade operator quickstart --target ./my-repo --harnesses codex      # wire one repo
 brigade operator doctor --target ./my-repo --profile local-operator   # verify
 ```
 
 That installs the CLI, wires memory, handoffs, and local guardrails into one repo for a single harness, and prints a readiness check. Nothing leaves your machine and no daemon is started. Add `--dry-run` to preview the file-by-file plan before anything is written. More harnesses, workspace setups, and the homegrown-adoption path are under [Install](#install).
 
-## Why I built this
+## One MCP catalog, synced into every tool
+
+Every agent tool reads its MCP servers from a different file in a different shape. The same servers wired across Claude Code, Cursor, Codex, VS Code, OpenCode, and Antigravity means hand-editing six configs and keeping them in sync forever. Brigade keeps one canonical catalog and merges it into each tool's native config for you.
+
+```bash
+brigade mcp init                  # scaffold .brigade/mcp.json
+brigade mcp add --name github --command npx \
+  --args "-y @modelcontextprotocol/server-github" \
+  --env GITHUB_TOKEN=ref:GITHUB_TOKEN
+brigade mcp sync                  # dry-run: show the diff for every tool
+brigade mcp sync --write          # merge into each tool's config
+```
 
-I run an always-on OpenClaw agent next to daily Codex and Claude Code sessions, and I have since January. Every one of those tools wakes up empty. Whatever a session learned about my machine, my rules, or yesterday's dead ends scattered across tool-specific folders and died there.
+One catalog (`.brigade/mcp.json`), six native targets:
 
-So I hand-rolled the fixes, one incident at a time: a slim `MEMORY.md` index pointing at small memory cards instead of one giant file, a handoff note format every harness could write, an ingest cron that filed the good notes into durable memory every 30 minutes, staleness checks so old cards stopped being trusted forever.
+| Tool | File it writes |
+|---|---|
+| Claude Code | `.mcp.json` |
+| Cursor | `.cursor/mcp.json` |
+| Codex CLI | `.codex/config.toml` (merged surgically, other tables preserved) |
+| VS Code | `.vscode/mcp.json` (secrets become `inputs[]`) |
+| OpenCode | `opencode.json` |
+| Antigravity | `~/.gemini/config/mcp_config.json` (user-scoped, `--user-scope`) |
 
-Two incidents shaped the design more than anything I planned. First, a nightly "dreaming" job that auto-promoted session fragments bloated `MEMORY.md` to 41KB, way past the 12KB bootstrap budget, so every session started with truncated memory and nobody noticed for weeks. Auto-promotion died that day. Everything goes through review now. Second, I found 195 handoff notes sitting unread across 35 repos because the ingester had a hardcoded three-repo allowlist and nothing warned about the coverage gap. Silence is the failure mode. Every part of Brigade that lints, warns, or writes a receipt exists because something once failed in silence.
+It is dry-run by default and never runs from `doctor` or `brief`. It merges by server key, so servers you added by hand are never touched, and ones you edited are left alone unless you pass `--force`. Secrets are written as `${VAR}` references (or VS Code `${input:VAR}`), never inlined. Ownership is tracked in a gitignored sidecar, so re-syncing on a fresh clone does not spuriously conflict. Full behavior in [docs/mcp-sync.md](docs/mcp-sync.md).
 
-That system now runs 482 memory cards and survives daily multi-agent work. But explaining it to anyone meant: clone six repos, write these crons, keep your index slim, watch for staleness, and whatever you do, turn auto-promotion off. Brigade is that setup packaged as one installable CLI. The full production stack is documented in the [solos-cookbook](https://github.com/escoffier-labs/solos-cookbook) if you want to see where it came from.
+Tools and skills get the same treatment: `brigade tools sync` projects one reviewed catalog into each harness's native format.
 
-## The loop
+> `brigade mcp` requires brigade 0.13.0 or newer (`pipx upgrade brigade-cli`).
 
-Writer harnesses leave handoff notes as they work. A memory owner (OpenClaw, Hermes, or just you) ingests the ones worth keeping. Brigade lints, guards, and routes everything in between, and every consequential action lands a receipt in a plain file you can grep, diff, and prune.
+## Shared memory, with a guard in front
+
+Writer harnesses leave handoff notes as they work. Brigade lints, guards, and classifies each one, then files the safe, targeted notes into durable memory on its own. A memory owner (OpenClaw, Hermes, or just you) only steps in for the ambiguous few. Every consequential action lands a receipt in a plain file you can grep, diff, and prune.
 
 1. agents write handoff notes into their own local inboxes
-2. Brigade lints and scans them before they can become memory
-3. safe targeted notes get filed into durable memory by the owner
-4. ambiguous or risky notes wait for your review
+2. Brigade lints and classifies each one before it can become memory
+3. safe, targeted notes file themselves into durable memory automatically
+4. only the ambiguous or risky few wait for your review
 5. future sessions start with better context, and receipts show what happened
 
 ```mermaid
 flowchart LR
     WRITERS["writer harnesses<br/>Codex · Claude Code · OpenCode · ..."]
-    BRIGADE["Brigade<br/>lint · guard · route · receipts"]
-    REVIEW["operator review<br/>safe · ambiguous · risky"]
+    BRIGADE["Brigade<br/>lint · guard · classify · receipts"]
     OWNER["memory owner<br/>OpenClaw / Hermes / you"]
     MEM["durable memory<br/>MEMORY.md index · memory cards"]
+    REVIEW["review inbox<br/>ambiguous · risky"]
 
-    WRITERS -- handoff notes --> BRIGADE --> REVIEW
-    REVIEW -- safe targeted notes --> OWNER --> MEM
+    WRITERS -- handoff notes --> BRIGADE --> OWNER
+    OWNER -- safe targeted, auto-filed --> MEM
+    OWNER -. ambiguous or risky .-> REVIEW
     MEM -. context .-> WRITERS
 
     classDef brigade fill:#2563eb,stroke:#1d4ed8,color:#fff;
@@ -97,38 +123,31 @@ flowchart LR
     class REVIEW gate;
 ```
 
-Memory has two layers: knowledge cards under `memory/cards/` hold the detail, and `MEMORY.md` stays a slim one-line-per-card index that loads every session. `brigade memory care scan` flags stale, contradictory, or undersourced cards for review instead of letting them rot. Brigade never edits canonical memory itself; the owner does the writing.
-
-It all runs on the machine you control: laptop, workstation, or VPS. Local by default, loud about the exceptions.
-
-## Install
+Memory has two layers: knowledge cards under `memory/cards/` hold the detail, and `MEMORY.md` stays a slim one-line-per-card index that loads every session. `brigade memory care scan` flags stale, contradictory, or undersourced cards for review instead of letting them rot. Brigade never edits canonical memory itself; the owner does the writing. It all runs on the machine you control: laptop, workstation, or VPS.
 
-```bash
-pipx install brigade-cli
-brigade operator quickstart --target ./my-repo --harnesses codex
-brigade operator doctor --target ./my-repo --profile local-operator
-```
+## Verified learning
 
-For an OpenClaw or Hermes workspace instead of a code repo:
+Filing notes is the first loop. The second loop earns trust. Brigade can promote a learned skill on its own, but only when a real signal proves it helped, and it rolls one back the moment a signal says it broke. The model never grades its own work.
 
-```bash
-brigade operator quickstart --target ~/agent-workspace --depth workspace --harnesses openclaw,hermes --owner openclaw
-```
+- `brigade outcome capture` records the result of a verify run (a real exit code, not an opinion) against the skill that produced it.
+- `brigade outcome score` ranks each skill by a Wilson lower bound, so something that passed twice never outranks something vetted across twenty runs.
+- `brigade outcome reconcile` is the gate. Dry-run by default; with `--apply` it installs a skill that earned it across your harnesses, or rolls a regressed one back to its last good version.
+- `brigade outcome explain` prints the full signal trail behind any decision: which run produced each result, the threshold it crossed, and the reversible action taken.
 
-Use `--dry-run` first to preview the planned steps without writing anything; `brigade init --target ./my-repo --harnesses codex --dry-run` shows the full file-by-file list. Pass more harnesses as a comma-separated list. Quickstart only wires the harnesses you select and leaves the rest alone.
+The whole ledger is plain JSON and markdown under `memory/outcome/`, tracked in git and readable without Brigade. Schedule `brigade outcome reconcile` in your own cron to run it hands-off; Brigade still installs no daemon.
 
-Write a handoff and check the wiring:
+## Sidecars
 
-```bash
-brigade handoff draft --target ./my-repo --inbox codex \
-  --title "What changed" \
-  --summary "Short note future agents should know." \
-  --content "The durable note itself goes here."
-brigade handoff lint --target ./my-repo
-brigade handoff doctor --target ./my-repo
-```
+Brigade is the hub. Each station wires an optional standalone tool, installed with `brigade add <station>` and health-checked by `brigade status` and `brigade doctor`. Every tool is its own repo, independently installable, with no library coupling back into Brigade.
 
-New here? Start with [QUICKSTART.md](QUICKSTART.md) for the five-minute install, then [docs/first-10-minutes.md](docs/first-10-minutes.md) for the guided first session. Already have a homegrown setup with scripts, crons, and handoff folders? Brigade has an adoption path that inventories what you have before changing anything: start with `brigade operator adopt plan` and see the [technical guide](docs/technical-guide.md). Want an agent to set this up for you? Point it at this repo; [AGENTS.md](AGENTS.md) tells it exactly what to do and where to stop.
+| `brigade add` | Tool | What it does |
+|---|---|---|
+| `guard` | content-guard | scans handoffs and content for secrets and PII before anything leaves the machine |
+| `tokens` | tokenjuice | tracks token spend across your harnesses and compacts noisy output |
+| `memory` | memory-doctor, bootstrap-doctor | validates memory cards and bootstrap files for staleness and contradictions |
+| `pantry` | agentpantry | syncs browser sessions and auth across an agent's machine |
+| `search` | code-search | local semantic code search over your repos |
+| `evidence` | miseledger | a local-first evidence ledger with receipts and source exporters |
 
 ## Harness support
 
@@ -156,18 +175,17 @@ Each writer gets its own local inbox; one canonical owner ingests. Brigade keeps
 | Hermes | `hermes` | `.hermes/memory-handoffs/` |
 | OpenClaw | `openclaw` | usually the memory owner, not a writer |
 
-All of them get handoff templates, ingest source coverage, and projected tools/skills. Per-harness details are in the [technical guide](docs/technical-guide.md).
+All of them get handoff templates and ingest source coverage. Most also get projected tools and skills in their native format; the per-harness matrix is in the [technical guide](docs/technical-guide.md). Hermes is validated against a real install: handoffs land in `.hermes/memory-handoffs/`, and reviewed skills install into your Hermes store (`~/.hermes/skills`).
 
-## Beyond memory
+## More
 
-The memory loop is the core. Around it, the same review-and-receipt pattern covers the rest of an operator's day, and you can ignore all of it until you need it:
+The same review-and-receipt pattern covers the rest of an operator's day, and you can ignore all of it until you need it.
 
+- **Cross-model runs**: `brigade run "<task>"` plans, dispatches, and synthesizes one bounded task across the agent CLIs in your roster, so an expensive model can think while cheaper ones do the grunt work. `--worktree` runs everything in a detached git checkout that comes back as a reviewable `changes.patch`.
 - **Daily loop**: `brigade work brief` shows pending work, imports, and warnings; `brigade daily status` keeps it bounded and cheap.
-- **Friction logs**: `brigade friction scan --days 30 --import-candidates` mines recent notes, handoffs, session artifacts, and optional local agent logs for reviewable workflow friction.
-- **Security**: `brigade security scan` is a local read-only scanner for agent workspaces (secrets, risky hooks, MCP configs, prompt-injection patterns); `brigade scrub` gates content before it leaves the machine.
-- **Tools and skills**: one reviewed catalog projected into every harness's native format, with approval gates for anything that executes.
+- **Friction logs**: `brigade friction scan` mines recent notes, handoffs, and session artifacts for reviewable workflow friction.
+- **Security and scrub**: `brigade security scan` is a local read-only scanner for agent workspaces; `brigade scrub` gates content before it leaves the machine.
 - **Research**: `brigade research run` turns a question into a cited local report and a reviewable memory handoff.
-- **Cross-model runs**: `brigade run "<task>"` plans, dispatches, and synthesizes one bounded task across the agent CLIs in your roster, so an expensive model can think while cheaper ones do the grunt work. Rosters pin a model per agent, plans can stage dependent workers, and `--worktree` runs everything in a detached git checkout that comes back as a reviewable `changes.patch`. A dirty-tree guard and a run lock keep agents away from your work in progress.
 - **Fleet and release**: health evidence across your local repos and release-readiness receipts, with no publish step.
 
 The full tour of every station lives in [docs/overview.md](docs/overview.md).
@@ -176,7 +194,8 @@ The full tour of every station lives in [docs/overview.md](docs/overview.md).
 
 - **mem0, Letta, and friends** are memory layers for apps you are building, usually behind an API or a server. Brigade is for the agent CLIs you already run, and it is file-first: your memory is markdown in your repo, reviewable in git, readable without Brigade.
 - **Native harness memory** (each tool's own auto-memory) is a per-tool silo. It does not cross harnesses, and it writes without review. Brigade gives every tool one shared format and one canonical owner, with a review gate in between.
-- **A plain CLAUDE.md / AGENTS.md** works great until it bloats past the context budget and goes stale. Brigade exists because mine hit 41KB. It keeps bootstrap files slim, moves detail into indexed cards, and flags staleness instead of trusting last month's facts forever.
+- **Already running Hermes, or any self-improving agent?** Keep it. Brigade is not a replacement, it is the verification layer on top. A built-in learning loop grades its own work and keeps what it learns inside one tool. Brigade promotes a skill only when a real signal confirms it, keeps every learned skill as portable markdown in your git, and runs one loop across your whole fleet.
+- **A plain CLAUDE.md / AGENTS.md** works great until it bloats past the context budget and goes stale. Brigade keeps bootstrap files slim, moves detail into indexed cards, and flags staleness instead of trusting last month's facts forever.
 - **A daemon or hosted service** would be simpler to demo and worse to trust. Brigade writes local files when you run a command, and that is all it does.
 
 ## What Brigade is not
@@ -194,11 +213,39 @@ It does not:
 
 That pause is the point. Agent memory should be useful, not noisy.
 
+## Install
+
+`brigade operator quickstart` (in [Try it in 60 seconds](#try-it-in-60-seconds)) wires one code repo for one harness. For an OpenClaw or Hermes workspace instead:
+
+```bash
+brigade operator quickstart --target ~/agent-workspace --depth workspace --harnesses openclaw,hermes --owner openclaw
+```
+
+Use `--dry-run` first to preview the planned steps without writing anything. Pass more harnesses as a comma-separated list; quickstart only wires the harnesses you select and leaves the rest alone.
+
+Write a handoff and check the wiring:
+
+```bash
+brigade handoff draft --target ./my-repo --inbox codex \
+  --title "What changed" \
+  --summary "Short note future agents should know." \
+  --content "The durable note itself goes here."
+brigade handoff lint --target ./my-repo
+brigade handoff doctor --target ./my-repo
+```
+
+New here? Start with [QUICKSTART.md](QUICKSTART.md) for the five-minute install, then [docs/first-10-minutes.md](docs/first-10-minutes.md) for the guided first session. Already have a homegrown setup with scripts, crons, and handoff folders? Brigade has an adoption path that inventories what you have before changing anything: start with `brigade operator adopt plan` and see the [technical guide](docs/technical-guide.md). Want an agent to set this up for you? Point it at this repo; [AGENTS.md](AGENTS.md) tells it exactly what to do and where to stop.
+
+## Why I built this
+
+I run an always-on OpenClaw agent next to daily Codex and Claude Code sessions. Every one of those tools wakes up empty, and whatever a session learned scattered across tool-specific folders and died there. Two incidents shaped the design: a "dreaming" job that promoted raw session fragments straight into memory bloated `MEMORY.md` past the bootstrap budget, so every session started truncated and nobody noticed for weeks; and 195 handoff notes that sat unread across 35 repos because an ingester had a hardcoded allowlist and nothing warned about the gap. Silence is the failure mode. Every part of Brigade that lints, warns, or writes a receipt exists because something once failed in silence. The full production stack, now 482 cards across daily multi-agent work, is documented in the [solos-cookbook](https://github.com/escoffier-labs/solos-cookbook).
+
 ## Docs
 
 - [First 10 minutes](docs/first-10-minutes.md): shortest path from install to healthy setup.
 - [Overview](docs/overview.md): the full tour of every station and diagram.
 - [Technical guide](docs/technical-guide.md): the detailed command walkthrough.
+- [MCP sync](docs/mcp-sync.md): the canonical catalog, supported tools, and merge rules.
 - [Security and Content Guard](docs/security.md): scanner policies, handoff guards, import flow.
 - [Handoff promotion](docs/handoff-promotion.md): how notes move toward memory.
 - [Repo fleet](docs/repo-fleet.md) and [Tool catalog](docs/tool-catalog.md).

{brigade_cli-0.11.0 → brigade_cli-0.13.0}/QUICKSTART.md

@@ -59,7 +59,7 @@ Which harnesses do you use? (type numbers separated by space/comma to toggle, en
   [ ] 16. Amp
   [ ] 17. Crush
   [ ] 18. OpenClaw
-  [ ] 19. Hermes (experimental)
+  [ ] 19. Hermes
 
 Depth? (type a number, enter for default)
   * 1. repo       (handoff flow + publish guard)
@@ -108,7 +108,7 @@ brigade doctor: target /home/you/agent-kitchen
   ...
 ```
 
-A `[fail]` line means the install is incomplete; `[warn]` is informational; `[todo]` means the check needs your attention (e.g. Hermes is experimental).
+A `[fail]` line means the install is incomplete; `[warn]` is informational; `[todo]` means the check needs your attention.
 
 ## Reconfiguring
 

brigade_cli-0.13.0/README.md

@@ -0,0 +1,228 @@
+<p align="center">
+  <img src="docs/assets/brigade-social-preview.jpg" alt="Brigade" width="900">
+</p>
+
+<h1 align="center">Brigade CLI</h1>
+
+<p align="center">
+  <strong>One canonical source for the MCP servers, tools, and memory your AI coding agents share, merged into each tool's native config with a review gate and a receipt for every change. Local files, no daemon, no lock-in.</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/github/actions/workflow/status/escoffier-labs/brigade/ci.yml?branch=main&style=for-the-badge&label=ci" alt="CI status">
+  <img src="https://img.shields.io/pypi/v/brigade-cli?style=for-the-badge&label=pypi" alt="PyPI version">
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT license">
+</p>
+
+Your agents run loops. Brigade keeps the receipts.
+
+## What it does
+
+You run more than one agent CLI. Each one keeps its MCP servers in its own config file, its memory in its own silo, and writes to both without review. Brigade is the local layer that fixes that. You keep one canonical source for your MCP servers, your tool and skill catalog, and your memory, and Brigade merges each into the tools you actually use: MCP servers into each tool's native config, tools and skills projected into each harness, and one shared memory owned in one place. A review gate sits in front of anything that gets written, and every consequential change lands a receipt you can grep, diff, and roll back. No daemon, no hosted service, no vendor lock-in: it writes plain files in your repo when you run a command, and that is all it does.
+
+## Try it in 60 seconds
+
+```bash
+pipx install brigade-cli
+pipx ensurepath          # then open a new shell so `brigade` is on PATH
+brigade operator quickstart --target ./my-repo --harnesses codex      # wire one repo
+brigade operator doctor --target ./my-repo --profile local-operator   # verify
+```
+
+That installs the CLI, wires memory, handoffs, and local guardrails into one repo for a single harness, and prints a readiness check. Nothing leaves your machine and no daemon is started. Add `--dry-run` to preview the file-by-file plan before anything is written. More harnesses, workspace setups, and the homegrown-adoption path are under [Install](#install).
+
+## One MCP catalog, synced into every tool
+
+Every agent tool reads its MCP servers from a different file in a different shape. The same servers wired across Claude Code, Cursor, Codex, VS Code, OpenCode, and Antigravity means hand-editing six configs and keeping them in sync forever. Brigade keeps one canonical catalog and merges it into each tool's native config for you.
+
+```bash
+brigade mcp init                  # scaffold .brigade/mcp.json
+brigade mcp add --name github --command npx \
+  --args "-y @modelcontextprotocol/server-github" \
+  --env GITHUB_TOKEN=ref:GITHUB_TOKEN
+brigade mcp sync                  # dry-run: show the diff for every tool
+brigade mcp sync --write          # merge into each tool's config
+```
+
+One catalog (`.brigade/mcp.json`), six native targets:
+
+| Tool | File it writes |
+|---|---|
+| Claude Code | `.mcp.json` |
+| Cursor | `.cursor/mcp.json` |
+| Codex CLI | `.codex/config.toml` (merged surgically, other tables preserved) |
+| VS Code | `.vscode/mcp.json` (secrets become `inputs[]`) |
+| OpenCode | `opencode.json` |
+| Antigravity | `~/.gemini/config/mcp_config.json` (user-scoped, `--user-scope`) |
+
+It is dry-run by default and never runs from `doctor` or `brief`. It merges by server key, so servers you added by hand are never touched, and ones you edited are left alone unless you pass `--force`. Secrets are written as `${VAR}` references (or VS Code `${input:VAR}`), never inlined. Ownership is tracked in a gitignored sidecar, so re-syncing on a fresh clone does not spuriously conflict. Full behavior in [docs/mcp-sync.md](docs/mcp-sync.md).
+
+Tools and skills get the same treatment: `brigade tools sync` projects one reviewed catalog into each harness's native format.
+
+> `brigade mcp` requires brigade 0.13.0 or newer (`pipx upgrade brigade-cli`).
+
+## Shared memory, with a guard in front
+
+Writer harnesses leave handoff notes as they work. Brigade lints, guards, and classifies each one, then files the safe, targeted notes into durable memory on its own. A memory owner (OpenClaw, Hermes, or just you) only steps in for the ambiguous few. Every consequential action lands a receipt in a plain file you can grep, diff, and prune.
+
+1. agents write handoff notes into their own local inboxes
+2. Brigade lints and classifies each one before it can become memory
+3. safe, targeted notes file themselves into durable memory automatically
+4. only the ambiguous or risky few wait for your review
+5. future sessions start with better context, and receipts show what happened
+
+```mermaid
+flowchart LR
+    WRITERS["writer harnesses<br/>Codex · Claude Code · OpenCode · ..."]
+    BRIGADE["Brigade<br/>lint · guard · classify · receipts"]
+    OWNER["memory owner<br/>OpenClaw / Hermes / you"]
+    MEM["durable memory<br/>MEMORY.md index · memory cards"]
+    REVIEW["review inbox<br/>ambiguous · risky"]
+
+    WRITERS -- handoff notes --> BRIGADE --> OWNER
+    OWNER -- safe targeted, auto-filed --> MEM
+    OWNER -. ambiguous or risky .-> REVIEW
+    MEM -. context .-> WRITERS
+
+    classDef brigade fill:#2563eb,stroke:#1d4ed8,color:#fff;
+    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
+    classDef gate fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
+    class BRIGADE brigade;
+    class OWNER,MEM memory;
+    class REVIEW gate;
+```
+
+Memory has two layers: knowledge cards under `memory/cards/` hold the detail, and `MEMORY.md` stays a slim one-line-per-card index that loads every session. `brigade memory care scan` flags stale, contradictory, or undersourced cards for review instead of letting them rot. Brigade never edits canonical memory itself; the owner does the writing. It all runs on the machine you control: laptop, workstation, or VPS.
+
+## Verified learning
+
+Filing notes is the first loop. The second loop earns trust. Brigade can promote a learned skill on its own, but only when a real signal proves it helped, and it rolls one back the moment a signal says it broke. The model never grades its own work.
+
+- `brigade outcome capture` records the result of a verify run (a real exit code, not an opinion) against the skill that produced it.
+- `brigade outcome score` ranks each skill by a Wilson lower bound, so something that passed twice never outranks something vetted across twenty runs.
+- `brigade outcome reconcile` is the gate. Dry-run by default; with `--apply` it installs a skill that earned it across your harnesses, or rolls a regressed one back to its last good version.
+- `brigade outcome explain` prints the full signal trail behind any decision: which run produced each result, the threshold it crossed, and the reversible action taken.
+
+The whole ledger is plain JSON and markdown under `memory/outcome/`, tracked in git and readable without Brigade. Schedule `brigade outcome reconcile` in your own cron to run it hands-off; Brigade still installs no daemon.
+
+## Sidecars
+
+Brigade is the hub. Each station wires an optional standalone tool, installed with `brigade add <station>` and health-checked by `brigade status` and `brigade doctor`. Every tool is its own repo, independently installable, with no library coupling back into Brigade.
+
+| `brigade add` | Tool | What it does |
+|---|---|---|
+| `guard` | content-guard | scans handoffs and content for secrets and PII before anything leaves the machine |
+| `tokens` | tokenjuice | tracks token spend across your harnesses and compacts noisy output |
+| `memory` | memory-doctor, bootstrap-doctor | validates memory cards and bootstrap files for staleness and contradictions |
+| `pantry` | agentpantry | syncs browser sessions and auth across an agent's machine |
+| `search` | code-search | local semantic code search over your repos |
+| `evidence` | miseledger | a local-first evidence ledger with receipts and source exporters |
+
+## Harness support
+
+Each writer gets its own local inbox; one canonical owner ingests. Brigade keeps the note format consistent so different tools can contribute without inventing their own styles.
+
+| Writer | Harness id | Inbox |
+|---|---|---|
+| Codex CLI | `codex` | `.codex/memory-handoffs/` |
+| Claude Code | `claude` | `.claude/memory-handoffs/` |
+| OpenCode | `opencode` | `.opencode/memory-handoffs/` |
+| Antigravity | `antigravity` | `.antigravity/memory-handoffs/` |
+| Pi | `pi` | `.pi/memory-handoffs/` |
+| Cursor | `cursor` | `.cursor/memory-handoffs/` |
+| Aider | `aider` | `.aider/memory-handoffs/` |
+| Goose | `goose` | `.goose/memory-handoffs/` |
+| Continue | `continue` | `.continue/memory-handoffs/` |
+| GitHub Copilot CLI | `copilot` | `.copilot/memory-handoffs/` |
+| Qwen Code | `qwen` | `.qwen/memory-handoffs/` |
+| Kimi Code | `kimi` | `.kimi/memory-handoffs/` |
+| AdaL | `adal` | `.adal/memory-handoffs/` |
+| OpenHands | `openhands` | `.openhands/memory-handoffs/` |
+| Grok CLI | `grok` | `.grok/memory-handoffs/` |
+| Amp | `amp` | `.amp/memory-handoffs/` |
+| Crush | `crush` | `.crush/memory-handoffs/` |
+| Hermes | `hermes` | `.hermes/memory-handoffs/` |
+| OpenClaw | `openclaw` | usually the memory owner, not a writer |
+
+All of them get handoff templates and ingest source coverage. Most also get projected tools and skills in their native format; the per-harness matrix is in the [technical guide](docs/technical-guide.md). Hermes is validated against a real install: handoffs land in `.hermes/memory-handoffs/`, and reviewed skills install into your Hermes store (`~/.hermes/skills`).
+
+## More
+
+The same review-and-receipt pattern covers the rest of an operator's day, and you can ignore all of it until you need it.
+
+- **Cross-model runs**: `brigade run "<task>"` plans, dispatches, and synthesizes one bounded task across the agent CLIs in your roster, so an expensive model can think while cheaper ones do the grunt work. `--worktree` runs everything in a detached git checkout that comes back as a reviewable `changes.patch`.
+- **Daily loop**: `brigade work brief` shows pending work, imports, and warnings; `brigade daily status` keeps it bounded and cheap.
+- **Friction logs**: `brigade friction scan` mines recent notes, handoffs, and session artifacts for reviewable workflow friction.
+- **Security and scrub**: `brigade security scan` is a local read-only scanner for agent workspaces; `brigade scrub` gates content before it leaves the machine.
+- **Research**: `brigade research run` turns a question into a cited local report and a reviewable memory handoff.
+- **Fleet and release**: health evidence across your local repos and release-readiness receipts, with no publish step.
+
+The full tour of every station lives in [docs/overview.md](docs/overview.md).
+
+## Why not something else?
+
+- **mem0, Letta, and friends** are memory layers for apps you are building, usually behind an API or a server. Brigade is for the agent CLIs you already run, and it is file-first: your memory is markdown in your repo, reviewable in git, readable without Brigade.
+- **Native harness memory** (each tool's own auto-memory) is a per-tool silo. It does not cross harnesses, and it writes without review. Brigade gives every tool one shared format and one canonical owner, with a review gate in between.
+- **Already running Hermes, or any self-improving agent?** Keep it. Brigade is not a replacement, it is the verification layer on top. A built-in learning loop grades its own work and keeps what it learns inside one tool. Brigade promotes a skill only when a real signal confirms it, keeps every learned skill as portable markdown in your git, and runs one loop across your whole fleet.
+- **A plain CLAUDE.md / AGENTS.md** works great until it bloats past the context budget and goes stale. Brigade keeps bootstrap files slim, moves detail into indexed cards, and flags staleness instead of trusting last month's facts forever.
+- **A daemon or hosted service** would be simpler to demo and worse to trust. Brigade writes local files when you run a command, and that is all it does.
+
+## What Brigade is not
+
+Brigade is not a hosted memory service, a daemon, or an automatic release bot.
+
+It does not:
+
+- run in the background or install schedulers
+- push to GitHub or publish packages
+- send notifications by default
+- save every note automatically
+- turn memory ingest into a silent background process
+- skip review for ambiguous, risky, or failed notes
+
+That pause is the point. Agent memory should be useful, not noisy.
+
+## Install
+
+`brigade operator quickstart` (in [Try it in 60 seconds](#try-it-in-60-seconds)) wires one code repo for one harness. For an OpenClaw or Hermes workspace instead:
+
+```bash
+brigade operator quickstart --target ~/agent-workspace --depth workspace --harnesses openclaw,hermes --owner openclaw
+```
+
+Use `--dry-run` first to preview the planned steps without writing anything. Pass more harnesses as a comma-separated list; quickstart only wires the harnesses you select and leaves the rest alone.
+
+Write a handoff and check the wiring:
+
+```bash
+brigade handoff draft --target ./my-repo --inbox codex \
+  --title "What changed" \
+  --summary "Short note future agents should know." \
+  --content "The durable note itself goes here."
+brigade handoff lint --target ./my-repo
+brigade handoff doctor --target ./my-repo
+```
+
+New here? Start with [QUICKSTART.md](QUICKSTART.md) for the five-minute install, then [docs/first-10-minutes.md](docs/first-10-minutes.md) for the guided first session. Already have a homegrown setup with scripts, crons, and handoff folders? Brigade has an adoption path that inventories what you have before changing anything: start with `brigade operator adopt plan` and see the [technical guide](docs/technical-guide.md). Want an agent to set this up for you? Point it at this repo; [AGENTS.md](AGENTS.md) tells it exactly what to do and where to stop.
+
+## Why I built this
+
+I run an always-on OpenClaw agent next to daily Codex and Claude Code sessions. Every one of those tools wakes up empty, and whatever a session learned scattered across tool-specific folders and died there. Two incidents shaped the design: a "dreaming" job that promoted raw session fragments straight into memory bloated `MEMORY.md` past the bootstrap budget, so every session started truncated and nobody noticed for weeks; and 195 handoff notes that sat unread across 35 repos because an ingester had a hardcoded allowlist and nothing warned about the gap. Silence is the failure mode. Every part of Brigade that lints, warns, or writes a receipt exists because something once failed in silence. The full production stack, now 482 cards across daily multi-agent work, is documented in the [solos-cookbook](https://github.com/escoffier-labs/solos-cookbook).
+
+## Docs
+
+- [First 10 minutes](docs/first-10-minutes.md): shortest path from install to healthy setup.
+- [Overview](docs/overview.md): the full tour of every station and diagram.
+- [Technical guide](docs/technical-guide.md): the detailed command walkthrough.
+- [MCP sync](docs/mcp-sync.md): the canonical catalog, supported tools, and merge rules.
+- [Security and Content Guard](docs/security.md): scanner policies, handoff guards, import flow.
+- [Handoff promotion](docs/handoff-promotion.md): how notes move toward memory.
+- [Repo fleet](docs/repo-fleet.md) and [Tool catalog](docs/tool-catalog.md).
+- [Command inventory](docs/command-inventory.md): every public CLI command.
+- [Maintainers](MAINTAINERS.md), [Governance](GOVERNANCE.md), [Security](SECURITY.md), and [Contributing](CONTRIBUTING.md).
+- [Roadmap](ROADMAP.md) and [roadmap archive](docs/roadmap-archive.md).
+
+Project identity: GitHub [`escoffier-labs/brigade`](https://github.com/escoffier-labs/brigade), website [brigade.tools](https://brigade.tools), PyPI [`brigade-cli`](https://pypi.org/project/brigade-cli/), command `brigade`. The name comes from the kitchen: a *brigade de cuisine* runs the line, and *mise en place* means the station is prepped before service. Set up the rules, memory, tools, and receipts before the session gets expensive.
+
+It is early-stage and moving fast. If you hit a broken workflow, a confusing command, or a setup issue, [open an issue](https://github.com/escoffier-labs/brigade/issues) and I will get it fixed.

{brigade_cli-0.11.0 → brigade_cli-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "brigade-cli"
-version = "0.11.0"
+version = "0.13.0"
 description = "AI agent memory, handoffs, and local guardrails for Codex, Claude Code, OpenCode, Hermes, and OpenClaw."
 readme = "README.md"
 requires-python = ">=3.10"

{brigade_cli-0.11.0 → brigade_cli-0.13.0}/src/brigade/__init__.py

@@ -1,3 +1,3 @@
 """Brigade: local operator-system CLI for agent workspaces."""
 
-__version__ = "0.11.0"
+__version__ = "0.13.0"

{brigade_cli-0.11.0 → brigade_cli-0.13.0}/src/brigade/agents.py

@@ -133,6 +133,40 @@ _ADAPTERS: dict[str, Callable[[str, bool, str | None], List[str]]] = {
 }
 
 
+# How strongly each adapter enforces a read-only run:
+#   hard - a native sandbox or tool allowlist the model cannot escape
+#   soft - read-only is only a prompt instruction the model may ignore
+#   none - read_only is not applied to this CLI at all
+# Brigade is "loud about exceptions", so `brigade run --read-only` warns when an
+# assigned harness is soft or none rather than implying a guarantee it cannot make.
+READ_ONLY_ENFORCEMENT: dict[str, str] = {
+    "codex": "hard",
+    "antigravity": "hard",
+    "pi": "hard",
+    "cursor": "hard",
+    "aider": "hard",
+    "continue": "hard",
+    "qwen": "hard",
+    "kimi": "hard",
+    "goose": "soft",
+    "copilot": "soft",
+    "adal": "soft",
+    "openhands": "soft",
+    "grok": "soft",
+    "amp": "soft",
+    "crush": "soft",
+    "claude": "none",
+    "opencode": "none",
+}
+
+
+def read_only_enforcement(cli_ref: str) -> str:
+    """Return how strongly cli_ref enforces read-only: 'hard', 'soft', or 'none'."""
+    if cli_ref.startswith(_OLLAMA_PREFIX):
+        return "none"
+    return READ_ONLY_ENFORCEMENT.get(cli_ref, "none")
+
+
 @dataclass(frozen=True)
 class AgentResult:
     text: str

{brigade_cli-0.11.0 → brigade_cli-0.13.0}/src/brigade/cli/__init__.py

@@ -47,6 +47,7 @@ from . import (
     context as _context_group,
     projects as _projects_group,
     learn as _learn_group,
+    outcome as _outcome_group,
     research as _research_group,
     center as _center_group,
     run as _run_group,
@@ -55,11 +56,13 @@ from . import (
     scrub as _scrub_group,
     security as _security_group,
     tools as _tools_group,
+    mcp as _mcp_group,
     handoff_template as _handoff_template_group,
     ingest as _ingest_group,
     openclaw_fragments as _openclaw_fragments_group,
     hermes_fragments as _hermes_fragments_group,
     reconfigure as _reconfigure_group,
+    completions as _completions_group,
 )
 
 
@@ -101,6 +104,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _context_group.register(sub)
     _projects_group.register(sub)
     _learn_group.register(sub)
+    _outcome_group.register(sub)
     _research_group.register(sub)
     _center_group.register(sub)
     _run_group.register(sub)
@@ -110,11 +114,13 @@ def _build_parser() -> argparse.ArgumentParser:
     _scrub_group.register(sub)
     _security_group.register(sub)
     _tools_group.register(sub)
+    _mcp_group.register(sub)
     _handoff_template_group.register(sub)
     _ingest_group.register(sub)
     _openclaw_fragments_group.register(sub)
     _hermes_fragments_group.register(sub)
     _reconfigure_group.register(sub)
+    _completions_group.register(sub)
 
     parser.epilog = _grouped_epilog(sub)
     return parser

{brigade_cli-0.11.0 → brigade_cli-0.13.0}/src/brigade/cli/_common.py

@@ -14,12 +14,15 @@ import argparse
 COMMAND_GROUPS: list[tuple[str, list[str]]] = [
     ("Core memory loop", ["init", "handoff", "handoff-template", "ingest", "memory", "doctor", "status"]),
     ("Daily operator loop", ["operator", "daily", "work", "friction", "center", "runbook", "budgets", "notifications"]),
-    ("Stations and tools", ["add", "skills", "tools", "pantry", "roster", "run", "runs", "dogfood"]),
+    ("Stations and tools", ["add", "skills", "tools", "mcp", "pantry", "roster", "run", "runs", "dogfood"]),
     (
         "Review, security, and research",
-        ["security", "scrub", "untrusted", "research", "learn", "chat", "context", "projects"],
+        ["security", "scrub", "untrusted", "research", "learn", "outcome", "chat", "context", "projects"],
+    ),
+    (
+        "Wiring and advanced",
+        ["release", "roadmap", "repos", "reconfigure", "completions", "openclaw-fragments", "hermes-fragments"],
     ),
-    ("Wiring and advanced", ["release", "roadmap", "repos", "reconfigure", "openclaw-fragments", "hermes-fragments"]),
 ]
 
 _START_HERE = """Brigade: run your agent brigade. Operator-system CLI for agent workspaces.