# 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`, `auto-task`, and every `task` verb with a tool: `add`, `update`, `show`, `list`, `eligible`, `lint`, `artifact`, `locks`, `review-reset`, `reconcile-review` and `requeue`): `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 or directory keeps only its exhaustive `prepare`/`render` tables. A part-migrated noun (`task`) flattens an `Operation(Invocation<V>)` variant into its hand-wired subcommand enum, with a `//` comment, since clap renders `///` there as help. 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, extend the kernel first rather than hand-wiring around it. Don't half-migrate a command.