# init, doctor, status

Use this to set up a repo or workspace, and to check afterward that your agent tools are wired correctly.

## init

Run `brigadestack init --target <dir>` for the interactive picker:

```bash
brigadestack init --target ~/agent-workspace
```

A non-interactive shell needs the flags instead: bare `brigadestack init` exits 2 with `error: brigade init needs a TTY for the interactive prompt. Pass --depth and --harnesses for scripting.` The CLI names itself `brigade` in its messages under either command name.

For CI or scripts, pass flags directly:

```bash
brigadestack init --target ~/agent-workspace --depth workspace --harnesses claude,codex,openclaw
brigadestack init --target ./repo --depth repo --harnesses codex
brigadestack init --target ./repo --harnesses none           # generic install
```

Add `--dry-run` to preview the full file-by-file list without writing anything. Files that already exist are listed with `(exists; kept)`, so nothing is implied to be overwritten.

The workspace config directory is `.brigade`.

`brigade --help` opens with a short start-here block and lists commands in five groups: the core memory loop, the daily operator loop, components and tools, review/security/research, and wiring and advanced. Every command stays listed. The grouping just replaces the flat dump.

## doctor

`brigadestack doctor` verifies the wiring. It checks installed bootstrap files against hard byte budgets so overgrown files fail before agents load truncated context. It folds installed managed tools into its report and surfaces each tool's own health. A missing optional tool is not a failure. Missing optional managed tools collapse into one non-failing summary line telling you to run `brigadestack add <component>`, instead of a per-tool wall.

```bash
brigadestack doctor
```

Add `--json` to emit the machine-readable report instead of text, `--target/-t <dir>` to point at another install, and `--harness {generic,openclaw,hermes}` to run a specific harness's checks.

This abbreviated output was captured with v0.31.0 in an isolated generic fixture after removing `AGENTS.md`. Counts vary by installation.

```text receipt="brigadestack doctor · exit 1"
brigade doctor: target <fixture>
  harnesses: (none) (owner=this-repo, depth=workspace)
  scope: target workspace only (pass --operator for host-global checks)
triage: 49 checks, 38 ok, 7 warn, 1 failed, 0 manual, 3 info

failures:
  [fail] bootstrap: AGENTS.md  target=<fixture>: missing at <fixture>/AGENTS.md
warnings:
  [warn] bootstrap: CLAUDE.md  target=<fixture>: not present at <fixture>/CLAUDE.md
  [warn] outcome loop: dormant  target=<fixture>: wired but no verify run ever captured; run `brigade work verify run --target . --command "<test>" --capture <skill-or-card-id>`
  [warn] security: config  target=<fixture>: missing at <fixture>/.brigade/security.toml; run `brigade security init --target .`

showing 8 actionable checks; run `brigade doctor --full` to show all checks

summary: 49 checks, 1 failed, 0 manual
```

Review every `[warn]` to decide whether it needs action. `[fail]` means the install is incomplete. The `openclaw` and `hermes` agent tools add their own checks on top.

## status

Once installed, `brigadestack status` reports over the component registry as a per-component table.

```bash
brigadestack status
```

Add `--json` to emit the machine-readable report instead of text, and `--target/-t <dir>` to point at another install.

The component rows below come from a v0.31.0 capture. The `work mode: strict` line uses the 0.32.0 beta mode name. 0.31.0 prints `engineer` for the same mode.

```text receipt="brigadestack status · exit 0"
brigade status: /home/you/agent-workspace
work mode: strict; safety rails: on
  core           [ok]  16 ok, 1 warn, 0 fail  - workspace bootstrap and harness adapters
  memory         [ok]  15 ok, 2 warn, 0 fail  - handoff inbox, ingest, and memory-care
  guard          [ok]  2 ok, 0 warn, 0 fail  - publish safety and content scrub
  tokens         [empty]  0 ok, 0 warn, 0 fail  - output compaction
  search         [empty]  0 ok, 0 warn, 0 fail  - local semantic code search
  security       [ok]  2 ok, 3 warn, 0 fail  - agent workspace security scanning
  pantry         [empty]  0 ok, 0 warn, 0 fail  - agent session auth sync
  notifications  [empty]  0 ok, 0 warn, 0 fail  - operator notification wiring
  evidence       [empty]  0 ok, 0 warn, 0 fail  - local-first evidence ledger and source exporters
  mcp            [empty]  0 ok, 0 warn, 0 fail  - canonical MCP server config sync
```

## When setup misbehaves: bug diagnose and bug report

Two commands help when a wiring problem is not obvious from `doctor`.

`brigadestack bug diagnose` compares a selected project's configuration against one agent tool without running it. `--harness` and `--summary` are required. `--component mcp` compares the project's MCP catalog with that agent tool's configuration. `--component instructions` diagnoses project-only Codex instruction loading, such as which `AGENTS.md` files Codex would select, and models the selection without reading file bodies. Add `--json` for machine-readable output. `--save-finding <new-path>` exports the finding locally, and `--prepare-report` prepares a local report for `bug report`.

```bash
brigadestack bug diagnose --harness codex --summary "MCP server missing in Codex"
brigadestack bug diagnose --component instructions --harness codex --summary "AGENTS.md not picked up" --assume-codex-defaults
```

`brigadestack bug report` collects a redacted diagnostics bundle and previews it before anything is shared. `--dry-run` saves and previews locally with no network calls. Submitting needs `--report-id <id>` from a saved preview plus `--yes` once you have approved the complete preview. `--kind` is `bug`, `feedback`, or `security`, and `--via` picks `auto`, `gh`, `url`, `email`, or `file`. `--summary` or `--summary-file` describes what happened and what you expected, and `--include-output <file>` adds a redacted 200-line tail of a file you choose.

```bash
brigadestack bug report --title "Doctor fails after init" --summary "Expected a clean doctor." --dry-run
```

## Running without the backend

A local install with no backend routes handoffs into a single workspace on that machine, and `init` picks that workspace automatically. To choose a different one, pass `--owner` to `brigadestack init`, `brigadestack operator quickstart` or `brigadestack reconfigure`. On `init` the value must be `this-repo` or one of the names you gave to `--harnesses`. The receipt commands `brigadestack handoff receipt plan` and `brigadestack handoff receipt record` also take `--owner`, as a label for the workspace the receipt belongs to. The output of `init` and `quickstart` names the chosen workspace on a line that starts `brigade: memory owner ->`.

```bash
brigadestack init --target ./repo --depth repo --harnesses claude,codex --owner claude
```