Document CLI output contract

docs/internal/cli.md

@@ -0,0 +1,67 @@
+# CLI Internals
+
+This document describes command output ownership in `internal/cli`.
+
+## Purpose
+
+`internal/cli` owns command parsing, app request construction, help text, and
+presentation of command results. It converts app-layer results into stable CLI
+summaries and writes stdout/stderr through shared output helpers.
+
+## Command Categories
+
+- Action commands: `generate` and `run`. These perform work, write artifacts,
+  and return compact summaries.
+- Inspection commands: `inspect reports`, `inspect metadata`, `inspect
+  modules`, `inspect data-package`, `inspect prior`, and `inspect sources`.
+  These read existing artifacts and return requested data.
+
+Future commands must declare which category they belong to before adding output
+behavior.
+
+## Stdout And Stderr
+
+Action commands write JSON summaries to stdout by default. `run` also writes
+compact status lines to stderr through `writeBatchStatus`. `generate` does not
+write routine stderr today. Pre-run errors return without partial JSON.
+
+Inspection commands write requested JSON data to stdout with `writeJSON`. They
+do not use action output helpers and do not support quiet mode.
+
+Returned errors are not hidden by output helpers. The caller remains
+responsible for displaying command errors.
+
+## Quiet Mode
+
+`--quiet` is supported only by action commands. It suppresses successful stdout
+and routine stderr by passing `outputOptions{Quiet: true}` to
+`writeActionResult`. It does not suppress returned errors.
+
+Quiet mode is intentionally not accepted by inspection commands because
+inspection stdout is the command result.
+
+## Summary Ownership
+
+CLI-safe summary structs live in `internal/cli/result.go`.
+
+- `newGenerateSummary` converts `*app.ReportResult` plus an optional error into
+  the generate JSON contract.
+- `newBatchSummary` converts `*app.BatchResult` into the run JSON contract and
+  derives the top-level run status.
+
+Summary types must not expose full app internals, module contents, data package
+contents, raw generated text, Scriptorium result bodies, or full distributor
+payloads.
+
+## Helper Path
+
+New action commands should:
+
+1. parse command-specific flags into CLI option structs;
+2. call the app-layer use case;
+3. convert app results into a CLI summary type;
+4. write through `writeActionResult`;
+5. use a status writer only for routine stderr status lines.
+
+New inspection commands should call the app inspection use case and write the
+returned data through `writeJSON`.