CLAUDE.md@crates/orbit-cli git:20261013.7f94c07A

Immutable. This exact content never changes and is served at /api/v1/blob/b549e78dfde90257.

# orbit-cli

Clap entry point. Subcommand files hold only `Args`/`Subcommand` definitions, one `impl Execute` calling the owning domain crate, and output projection. Registry lookups, file I/O, audit decisions, and state mutation belong in the domain crate.

- **Directory ⟺ one command.** Command subdirectories under `command/` map to `orbit <name>`; keep them independent of `--help` sections. Shared command infrastructure may use its own concern module, such as `operation/`. Single `.rs` is fine for any command that fits in one file.
- In a command directory: `command.rs` holds the `XxxCommand` struct, `XxxSubcommand` enum, and their `Execute` impls; each subcommand body is its own `<subcommand>.rs`; shared helpers go in `support.rs`; `mod.rs` is declarations and re-exports only — no clap derives.
- `--help` grouping comes from a hand-rolled `help_template` in `command/mod.rs`. Adding a top-level command: add the `Commands` variant in template order, add the row to the template section, and add exactly one exhaustive arm in `command/operation/registry.rs` (dispatch, runtime need, audit metadata, error policy together — no default arm, no duplicate policy matches elsewhere).
- Registry-derived commands (`friction` only, so far): `command/operation/args.rs` builds the tree from `orbit-common`'s operation registry and implements the clap traits for every noun, `registry_operation` derives the registry arm, and the noun's file keeps only its exhaustive `prepare`/`render` tables. Adding a verb is a registry entry, a Core handler arm and the arms the compiler then asks for — no flags, help text or input mapping are written under `command/`.
- A registry-derived verb executes through `runtime.run_tool`, never a direct core call, including CLI-only verbs (`mcp_scope: None`). Don't restate in `command/` anything the spec declares — flag spellings, help, input projection, field presence rules.
- Migrating another noun is planned work ([design §9](../../docs/design/operations-as-data/2_design.md#9-migration-plan)), not a side effect of an unrelated task. Follow the [cookbook](../../docs/design/operations-as-data/references/cookbook.md): freeze `--help` and, for a CLI that calls core directly today, a behaviour baseline (Step 0) before any code. If the noun needs a parameter kind the kernel lacks (enum, default, switch, nested subcommand), extend the kernel first rather than hand-wiring around it. Don't half-migrate a command.