brigade-cli 0.8.2__tar.gz → 0.9.0__tar.gz

brigade_cli-0.9.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: brigade-cli
+Version: 0.9.0
+Summary: AI agent memory, handoffs, and local guardrails for Codex, Claude Code, OpenCode, Hermes, and OpenClaw.
+Author-email: Solomon Neas <srneas@gmail.com>
+License: MIT
+Project-URL: Homepage, https://brigade.tools
+Project-URL: Repository, https://github.com/escoffier-labs/brigade
+Project-URL: Cookbook, https://github.com/solomonneas/solos-cookbook
+Project-URL: OpenClaw, https://github.com/solomonneas/openclaw
+Project-URL: ContentGuard, https://github.com/solomonneas/content-guard
+Project-URL: AgentPantry, https://github.com/escoffier-labs/agentpantry
+Project-URL: Issues, https://github.com/escoffier-labs/brigade/issues
+Keywords: agents,ai-agents,agent-memory,agent-handoffs,ai-memory,openclaw,claude-code,codex,opencode,memory,bootstrap,brigade,brigade-cli,operator,local-first,guardrails,agents-md
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: research
+Requires-Dist: playwright>=1.40; extra == "research"
+Dynamic: license-file
+
+<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>AI agent memory, handoffs, and local guardrails for Codex, Claude Code, OpenCode, and a dozen other harnesses.</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.
+
+## Why I built this
+
+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.
+
+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.
+
+Two incidents shaped the design more than anything I planned. First, a nightly "dreaming" job that auto-promoted session fragments quietly 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 quietly.
+
+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/solomonneas/solos-cookbook) if you want to see where it came from.
+
+## The loop
+
+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.
+
+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
+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"]
+    OWNER["memory owner<br/>OpenClaw / Hermes / you"]
+    MEM["durable memory<br/>MEMORY.md index · memory cards"]
+
+    WRITERS -- handoff notes --> BRIGADE --> REVIEW
+    REVIEW -- safe targeted notes --> OWNER --> MEM
+    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. Local by default, loud about the exceptions.
+
+## Install
+
+```bash
+pipx install brigade-cli
+brigade operator quickstart --target ./my-repo --harnesses codex
+brigade operator doctor --target ./my-repo --profile local-operator
+```
+
+For an OpenClaw or Hermes workspace instead of a code repo:
+
+```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; `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.
+
+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 [docs/first-10-minutes.md](docs/first-10-minutes.md). 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.
+
+## 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/` |
+| 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).
+
+## Beyond memory
+
+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:
+
+- **Daily loop**: `brigade work brief` shows pending work, imports, and warnings; `brigade daily status` keeps it bounded and cheap.
+- **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.
+- **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.
+- **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.
+- **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.
+
+## 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.
+- [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.
+- [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.9.0/README.md

@@ -0,0 +1,165 @@
+<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>AI agent memory, handoffs, and local guardrails for Codex, Claude Code, OpenCode, and a dozen other harnesses.</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.
+
+## Why I built this
+
+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.
+
+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.
+
+Two incidents shaped the design more than anything I planned. First, a nightly "dreaming" job that auto-promoted session fragments quietly 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 quietly.
+
+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/solomonneas/solos-cookbook) if you want to see where it came from.
+
+## The loop
+
+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.
+
+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
+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"]
+    OWNER["memory owner<br/>OpenClaw / Hermes / you"]
+    MEM["durable memory<br/>MEMORY.md index · memory cards"]
+
+    WRITERS -- handoff notes --> BRIGADE --> REVIEW
+    REVIEW -- safe targeted notes --> OWNER --> MEM
+    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. Local by default, loud about the exceptions.
+
+## Install
+
+```bash
+pipx install brigade-cli
+brigade operator quickstart --target ./my-repo --harnesses codex
+brigade operator doctor --target ./my-repo --profile local-operator
+```
+
+For an OpenClaw or Hermes workspace instead of a code repo:
+
+```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; `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.
+
+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 [docs/first-10-minutes.md](docs/first-10-minutes.md). 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.
+
+## 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/` |
+| 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).
+
+## Beyond memory
+
+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:
+
+- **Daily loop**: `brigade work brief` shows pending work, imports, and warnings; `brigade daily status` keeps it bounded and cheap.
+- **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.
+- **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.
+- **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.
+- **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.
+
+## 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.
+- [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.
+- [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.8.2 → brigade_cli-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "brigade-cli"
-version = "0.8.2"
+version = "0.9.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.8.2 → brigade_cli-0.9.0}/src/brigade/__init__.py

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

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/cli.py

@@ -11,12 +11,62 @@ from .work_cmd import TASK_PRIORITIES, TASK_TYPES
 from .prompt import prompt_for_selection  # imported here so tests can monkeypatch cli.prompt_for_selection
 
 
+# Top-level help groups. Every sub.add_parser command must appear in exactly
+# one group; tests/test_cli_help.py enforces full coverage.
+COMMAND_GROUPS: list[tuple[str, list[str]]] = [
+    ("Core memory loop",
+     ["init", "handoff", "handoff-template", "ingest", "memory", "doctor", "status"]),
+    ("Daily operator loop",
+     ["operator", "daily", "work", "center", "runbook", "budgets", "notifications"]),
+    ("Stations and tools",
+     ["add", "skills", "tools", "pantry", "roster", "run", "runs", "dogfood"]),
+    ("Review, security, and research",
+     ["security", "scrub", "untrusted", "research", "learn", "chat", "context", "projects"]),
+    ("Wiring and advanced",
+     ["release", "roadmap", "repos", "reconfigure", "openclaw-fragments", "hermes-fragments"]),
+]
+
+_START_HERE = """Brigade: run your agent brigade. Operator-system CLI for agent workspaces.
+
+Start here:
+  brigade operator quickstart --target <repo> --harnesses codex   set up a repo or workspace
+  brigade operator doctor --target <repo>                         check the wiring
+  brigade handoff draft --target <repo> ...                       record a durable note
+  brigade ingest --target <workspace>                             route handoffs into memory"""
+
+
+class _TopLevelHelpFormatter(argparse.RawDescriptionHelpFormatter):
+    """Suppress argparse's flat subcommand dump on the top-level parser.
+
+    The grouped epilog lists every command instead. Subparsers do not inherit
+    this formatter, so `brigade <command> --help` keeps the normal listing.
+    """
+
+    def _iter_indented_subactions(self, action):
+        if isinstance(action, argparse._SubParsersAction):
+            return iter(())
+        return super()._iter_indented_subactions(action)
+
+
+def _grouped_epilog(sub: argparse._SubParsersAction) -> str:
+    helps = {action.dest: (action.help or "") for action in sub._choices_actions}
+    lines = ["commands:"]
+    for title, names in COMMAND_GROUPS:
+        lines.append("")
+        lines.append(f"{title}:")
+        lines.extend(f"  {name:<22}{helps.get(name, '')}" for name in names)
+    lines.append("")
+    lines.append("Run 'brigade <command> --help' for details on any command.")
+    return "\n".join(lines)
+
+
 def _build_parser() -> argparse.ArgumentParser:
     from . import learn_cmd, projects_cmd, release_cmd, repos_cmd
 
     parser = argparse.ArgumentParser(
         prog="brigade",
-        description="Brigade: run your agent brigade. Operator-system CLI for agent workspaces.",
+        description=_START_HERE,
+        formatter_class=_TopLevelHelpFormatter,
     )
     parser.add_argument(
         "--version", action="version", version=f"brigade {__version__}"
@@ -1046,8 +1096,8 @@ def _build_parser() -> argparse.ArgumentParser:
     p_handoff_draft.add_argument("--action", choices=["create-card", "update-card", "no-card"], default="no-card", help="Recommended memory action.")
     p_handoff_draft.add_argument("--target-card", default=None, help="Target card filename for card handoffs.")
     p_handoff_draft.add_argument("--target-document", default=".learnings/LEARNINGS.md", help="Target document for no-card handoffs.")
-    p_handoff_draft.add_argument("--content", default=None, help="Suggested card or document content.")
-    p_handoff_draft.add_argument("--content-file", type=Path, default=None, help="Read suggested content from a file.")
+    p_handoff_draft.add_argument("--content", default=None, help="Suggested card or document content. One of --content/--content-file is required.")
+    p_handoff_draft.add_argument("--content-file", type=Path, default=None, help="Read suggested content from a file. One of --content/--content-file is required.")
     p_handoff_draft.add_argument("--id", dest="draft_id", default=None, help="Stable id slug to use in the filename.")
     p_handoff_draft.add_argument("--force", action="store_true", help="Overwrite an existing generated draft path.")
     p_handoff_draft.add_argument("--guard", action="store_true", help="Scan the generated draft with content-guard before returning success.")
@@ -2817,6 +2867,7 @@ def _build_parser() -> argparse.ArgumentParser:
     p_recon.add_argument("--prune", action="store_true",
                          help="Remove files for harnesses no longer selected.")
 
+    parser.epilog = _grouped_epilog(sub)
     return parser
 
 

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/handoff_cmd.py

@@ -1437,6 +1437,8 @@ def draft(
             print(f"content_guard_detail: {guard_result.get('detail')}")
     for error in lint_result.errors:
         print(f"error: {error}")
+    if not lint_result.valid:
+        print(f"note: invalid draft kept at {path}; repair or delete it, then rerun `brigade handoff lint`.")
     return 0 if payload["valid"] else 1
 
 

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/install.py

@@ -247,7 +247,11 @@ def install_selection(
         for d in dirs:
             print(f"  dir   {target / d}")
         for entry in files:
-            print(f"  file  {target / entry['dst']}")
+            dst = target / entry["dst"]
+            if dst.exists():
+                print(f"  file  {dst} (exists; refused without --force)")
+            else:
+                print(f"  file  {dst}")
         return 0
 
     target.mkdir(parents=True, exist_ok=True)

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/operator_cmd.py

@@ -2787,7 +2787,8 @@ def quickstart(
         dry_run=dry_run,
         allow_home=False,
     )
-    steps.append({"id": "brigade-init", "status": "ok" if install_rc == 0 else "error", "return_code": install_rc, "output": install_output})
+    install_status = "planned" if dry_run and install_rc == 0 else "ok" if install_rc == 0 else "error"
+    steps.append({"id": "brigade-init", "status": install_status, "return_code": install_rc, "output": install_output})
     if install_rc != 0:
         payload = {
             "target": str(target),

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/templates/hermes/memory-handoff.harness.json

@@ -5,7 +5,7 @@
     "Describes the handoff inbox + routing targets that Hermes should treat",
     "as the canonical memory contract."
   ],
-  "_brigade_version": "0.8.2",
+  "_brigade_version": "0.9.0",
   "_brigade_status": "experimental",
   "memory_handoff": {
     "inbox_dir": ".hermes/memory-handoffs",

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/templates/hermes/model-lanes.harness.json

@@ -5,7 +5,7 @@
     "Suggested model lane names. Same shape as the OpenClaw alias map so",
     "knowledge cards and runbooks can talk about lanes without naming providers."
   ],
-  "_brigade_version": "0.8.2",
+  "_brigade_version": "0.9.0",
   "_brigade_status": "experimental",
   "model_lanes": {
     "main": "<provider/main-model-id>",

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/templates/hermes/workspace.harness.json

@@ -8,7 +8,7 @@
     "",
     "Replace <hermes-config-path> with your Hermes config location."
   ],
-  "_brigade_version": "0.8.2",
+  "_brigade_version": "0.9.0",
   "_brigade_status": "experimental",
   "workspace": {
     "root": "<workspace-root>",

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/templates/memory/chat-memory-sweep.example.json

@@ -1,5 +1,5 @@
 {
-  "_brigade_version": "0.8.2",
+  "_brigade_version": "0.9.0",
   "_description": "Example output contract for a nightly chat/session memory sweep. Keep raw chat transcripts in crawler archives; this file contains summaries and local source locators only.",
   "generated_at": "2026-05-26T22:09:00-04:00",
   "window": {

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/templates/memory/memory-care.example.json

@@ -1,5 +1,5 @@
 {
-  "_brigade_version": "0.8.2",
+  "_brigade_version": "0.9.0",
   "_description": "Example config for a local memory-care scanner. Brigade does not run this scanner for you; it validates the output with `brigade doctor`.",
   "cards_glob": "memory/cards/*.md",
   "decay_dir": "memory/cards/decay",

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/templates/policies/personal.json

@@ -4,7 +4,7 @@
     "It blocks secrets and attribution trailers, while warning on personal or infrastructure-like context.",
     "Use via: brigade handoff lint --content-guard --guard-policy personal"
   ],
-  "_brigade_version": "0.8.2",
+  "_brigade_version": "0.9.0",
   "categories": {
     "secret": "block",
     "private-network": "warn",

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/templates/policies/public-content.json

@@ -4,7 +4,7 @@
     "social drafts, and docs that will be published, not just pushed.",
     "Use via: brigade scrub --policy public-content"
   ],
-  "_brigade_version": "0.8.2",
+  "_brigade_version": "0.9.0",
   "categories": {
     "secret": "block",
     "private-network": "block",

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/templates/policies/public-repo.json

@@ -4,7 +4,7 @@
     "Used by brigade pre-push hook and `brigade scrub`.",
     "Override by pointing CONTENT_GUARD_POLICY at your own copy of this file."
   ],
-  "_brigade_version": "0.8.2",
+  "_brigade_version": "0.9.0",
   "categories": {
     "secret": "block",
     "private-network": "block",

{brigade_cli-0.8.2 → brigade_cli-0.9.0}/src/brigade/tools_cmd.py

@@ -4094,7 +4094,7 @@ def init(*, target: Path, force: bool = False, update_gitignore: bool = True) ->
     print(f"tools: {len(DEFAULT_TOOLS)}")
     print(f"sources: {sum(1 for item in source_results if item['action'] == 'create')}")
     if update_gitignore:
-        result = apply_gitignore(target, Selection("repo", ["codex"], "codex"))
+        result = apply_gitignore(target, _gitignore_selection(target))
         print(f"gitignore: {result}")
     else:
         print("gitignore: skipped")
@@ -4143,6 +4143,21 @@ def _projection_scope(target: Path) -> set[str] | None:
     return scope
 
 
+def _gitignore_selection(target: Path) -> Selection:
+    """Use the workspace's configured selection for gitignore rewrites.
+
+    Re-applying the managed gitignore block with a narrower selection than the
+    install drops inbox entries for the other selected harnesses.
+    """
+    try:
+        config = load_brigade_config(target)
+    except Exception:
+        config = None
+    if config is not None and config.selection.harnesses:
+        return config.selection
+    return Selection("repo", ["codex"], "codex")
+
+
 def _scoped_default_tool(tool: dict[str, Any], scope: set[str] | None) -> dict[str, Any]:
     entry = dict(tool)
     if scope is None:
@@ -4222,7 +4237,7 @@ def defaults(*, target: Path, dry_run: bool = False, force: bool = False, update
     source_results = _ensure_default_tool_sources(target, dry_run=dry_run or bool(conflicts))
     gitignore_result = "skipped"
     if update_gitignore and not dry_run and not conflicts:
-        gitignore_result = apply_gitignore(target, Selection("repo", ["codex"], "codex"))
+        gitignore_result = apply_gitignore(target, _gitignore_selection(target))
     payload = {
         "target": str(target),
         "config_path": str(path),
@@ -5548,7 +5563,7 @@ def pack_import(*, target: Path, pack: Path, force: bool = False, json_output: b
         imported.append({"tool_id": tool_id, "source_path": entry.get("source_path")})
     config_path(target).parent.mkdir(parents=True, exist_ok=True)
     config_path(target).write_text(_format_tool_entries(list(merged_by_id.values())))
-    result = apply_gitignore(target, Selection("repo", ["codex"], "codex"))
+    result = apply_gitignore(target, _gitignore_selection(target))
     payload = {
         "target": str(target),
         "pack": str(pack),