# Runtime Command Discovery

Treat the installed BMCLI binary as the command schema. Bundled reference text
explains concepts and workflows but does not override runtime help.

## Resolve syntax before execution

1. Run `bmcli version --format=json` and preserve version, build number, and Git
   commit in generated evidence.
2. Run `bmcli help --format=json` to discover current categories and actions.
3. Before a nontrivial operation, run `bmcli help <category> <action>
   --format=json`. Read required options, defaults, units, constraints, notes,
   and examples from that response.
4. If help does not list an operation or option, do not invent it. State the
   capability gap and choose a supported lower-level operation when safe.
5. Use the full reference only to understand semantics: locate
   `share/bmcli/doc/bmcli_reference.md` relative to the installation when needed.

Do not expect MCP, a GUI automation layer, or undocumented BMAPI calls. BMCLI is
the AI-facing interface.

## Automation contract

- Use `--format=json` for one bounded result and `--format=jsonl` for streams.
- Check the process exit code before interpreting stdout. Public success is 0;
  public failure is 1.
- Parse stdout as data. Preserve stderr separately for warnings and notes.
- Give the parent process a timeout longer than BMCLI's own `--timeout` or
  `--duration`, including startup and cleanup margin.
- Preserve raw JSON/JSONL, exact argv, timestamps, BMCLI version, and channel in
  test evidence.
- Pass subprocess arguments as an argv array. Do not concatenate untrusted file
  paths, DBC values, or specification text into a shell command.

Use a direct command for bounded inspection, shell for simple fixed sequences,
and Python `subprocess` for matrices, retries, structured parsing, assertions,
reports, and long-running maintenance. For persistent activity, query daemon,
TX-task, route, logging, replay, and gateway help and explicitly own their
lifecycle. `gateway` is for an upper computer that already uses remote BMAPI;
it is not BMCLI daemon IPC, an HTTP API, or a generic untrusted-network tunnel.

Use stable `SN/port` channel names in generated artifacts. A numeric enumeration
index is temporary process-local evidence, not a durable hardware identity.
Use `channel enumerate --format=json` capability bits to distinguish CAN and LIN
ports on a mixed-function analyzer. Do not infer bus type from the model name.
The canonical raw interface is still `message`: query its send/receive help to
discover bus-specific options. For LIN master/slave work, also query `channel
open` and `txtask add`; a slave response is a header-triggered task, not a
periodic CAN-style task.
