# components

Use this to see which components BrigadeStack can wire into a workspace, or to check a component's contract before you install it.

`brigadestack components list|discover|verify` is the catalog command. `brigadestack stations` still works as a hidden alias with identical arguments and exit codes, no warning, and no removal date. Root help lists only `components`.

A component is a bundle of sidecar tools BrigadeStack knows how to wire, and a profile decides which components are selected or optional. `brigadestack components` lists the built-in component catalog, discovers external `station.json` catalogs on disk, and verifies a component contract before you install it. All three subcommands are read-only: they report and never install a sidecar or edit config.

The contract file keeps its name. A component repo still publishes `station.json` with the schema `brigade.station.v1`, the verify report keeps the schema `brigade.stations.verify.v1`, and the JSON keys `station`, `stations`, `selected_stations`, `optional_stations`, and `missing_stations` are unchanged. Scripts and manifests written for earlier releases keep working.

## Commands

`brigadestack components list` lists every component in the catalog, its selection under a profile, the tools it wires, and a one-line summary. It defaults to the `repo` profile. Pass `--profile <name>` to compare against another built-in profile by name or alias. Add `--json` for machine-readable output.

```bash
brigadestack components list
brigadestack components list --profile repo
brigadestack components list --profile workspace
brigadestack components list --json
```

`brigadestack components discover` scans local roots for external `station.json` catalogs (schema `brigade.station.v1`) so you can see what a third-party component declares before wiring it. It defaults to the current directory plus `~/repos`, `~/src`, and `~/code` when they exist. Pass `--root <dir>` (repeatable) to override, and `--max-depth` to control how deep it looks (default `2`: each root, its children and their children).

```bash
brigadestack components discover
brigadestack components discover --root ~/work --root ~/oss
brigadestack components discover --max-depth 3 --json
```

`brigadestack components verify <path>` checks one explicitly selected `station.json` contract without installing it. Pass the directory that contains `station.json` or the file itself. It exits non-zero when the contract is missing or malformed. Add `--check-managed` to also fail when a matching active executable contract has drifted from BrigadeStack's managed catalog.

```bash
brigadestack components verify ./some-tool
brigadestack components verify ./some-tool/station.json --json
brigadestack components verify ./some-tool --check-managed
```

## Reading the catalog

Each row shows the component name, its selection for the chosen profile (`selected`, `optional`, or `not selected`), the tools that component wires, and the summary. `built-in` rows ship inside `brigade-cli`. A row can be followed by indented `surfaces:` lines that name the machine-readable surfaces each tool exposes, such as `doctor-json`, `summary-json`, `brief-markdown`, and `verify-exit`.

This is an excerpt of the real output. The full catalog has more rows.

```text receipt="brigadestack components list · exit 0"
brigade components: profile=repo
  core           [selected]  built-in  - workspace bootstrap and harness adapters
  skills         [selected]  brigade-work, ultra-work-scout  - portable agent skills, Scout workflows, and runbooks
  memory         [selected]  bootstrap-doctor  - handoff inbox, ingest, memory-care, and embedded memory maintenance
                   surfaces: bootstrap-doctor: summary-json, doctor-json, verify-exit
  tokens         [selected]  token-glace, usage-tracker  - Token Glace output compaction and optional usage export
                   surfaces: token-glace: doctor-json, summary-json, verify-exit
                   surfaces: usage-tracker: summary-json
  security       [selected]  built-in  - agent workspace security scanning
  pantry         [optional]  agentpantry  - agent session auth sync
                   surfaces: agentpantry: doctor-json, summary-json, verify-exit
  notifications  [optional]  agent-notify  - operator notification wiring
                   surfaces: agent-notify: doctor-json, verify-exit
  mcp            [optional]  built-in  - canonical MCP server config sync
```

The `guard`, `search`, and `evidence` rows, which this excerpt leaves out, are backed by the embedded guard and the engines `brigadestack setup` installs. The code intelligence and evidence engines are managed binaries (`brigade-code-graph`, `brigade-evidence`) that `brigadestack setup` installs beside the `brigade-cli` package.

The same catalog is listed for every profile. Only the selection column changes with `--profile`. An unknown profile name exits non-zero and prints `unknown profile: <name>`.

Component listing is inspection only. Use `brigadestack profiles show` to see a profile's selected and optional components. Use `brigadestack guard` or `brigadestack scrub` for the embedded guard, and `brigadestack add` for components that still need external tools.