Document Promptkit report generation

docs/internal/cli.md

@@ -1,74 +1,23 @@
 # CLI Internals
 
-`internal/cli` turns process arguments into application requests and translates
-application results into terminal output. The user-facing command, flag, and
-output contract belongs in the [CLI reference](../cli.md).
+`internal/cli` parses terminal arguments, loads configuration, constructs app
+requests, and translates app results to bounded JSON summaries. The user
+contract belongs in the [CLI reference](../cli.md).
 
-## Responsibilities
+For each `generate` or `run` action, `Runner` constructs one project-owned
+Promptkit executor after configuration loads. It passes the executor and any
+`--llm-debug-dir` request into the app. `run` accepts the debug flag as well
+as `generate`; the app, not the CLI, secures and initializes the debug root.
 
-`Runner.Run` dispatches the top-level action or inspection request. For actions,
-the package parses command-specific and common flags, loads configuration with
-CLI overrides, obtains the current time, and constructs either an
-`app.GenerateRequest` or an `app.BatchRequest`. It delegates generation and
-batch execution to `internal/app`.
+Summaries include identity, status, safe artifact paths, and notification
+provenance. They intentionally exclude module values, YAML package bodies, raw
+generated text, rendered prompts, schemas, endpoints, credentials, and full
+Distributor payloads. A failed action with a partial result still emits its
+safe summary before its error is returned.
 
-`Runner` also owns a project-owned prompt-executor factory seam. Its production
-factory maps `promptkit` configuration to the Promptkit adapter, while tests can
-inject a factory without importing dependency types. Each `generate` request
-constructs one executor after configuration loads and passes it to the app.
+CLI code owns no report policy, weather collection, persistence, provider
+execution, or notification policy. Focused checks:
 
-All four `generate` commands also accept `--llm-debug-dir PATH`. The CLI passes
-only this explicit request to the app; the app initializes the secure debug
-root before prompt inspection. `run` commands do not accept the flag.
-
-For inspection, it loads configuration, builds the appropriate app inspection
-request, and writes the returned value. Inspection is read-only; the inspected
-artifact types and user invocation remain owned by the [CLI reference](../cli.md)
-and [operations guide](../operations.md).
-
-## Result Translation
-
-Action results become CLI-safe JSON summaries in `result.go`. Generate summaries
-carry report identity, status, relevant artifact paths, and notification
-summary data. Batch summaries carry aggregate counts, per-report outcomes, and
-the optional batch notification result. The translation deliberately excludes
-full module snapshots, prompt packages, raw generated text, Scriptorium output,
-complete Distributor payloads, and prompt-debug content.
-
-When an action returns both a result and an error, the CLI writes the failed
-summary before returning that error. Parse, configuration-load, and other
-failures that produce no application result return without a summary.
-
-`writeActionResult` writes action status information to stderr first, then JSON
-to stdout. Batch execution supplies the status writer; single-report generation
-does not emit routine stderr output. Quiet action requests suppress both normal
-streams but still return errors. Inspection writes its JSON value to stdout and
-does not accept quiet mode because stdout is the inspection result.
-
-## Boundaries
-
-The package owns argument parsing, request adaptation, help text, and terminal
-presentation. It does not implement report selection, collection, state
-persistence, external transport, subprocess execution, or notification policy.
-Those concerns remain in [application orchestration](app-orchestration.md) and
-their focused owners.
-
-## Failure Behavior
-
-- Invalid command names, flags, dates, and configuration fail before an app
-  request is executed.
-- Application errors retain their application context; output helpers do not
-  hide or replace them.
-- JSON-encoding errors are returned directly.
-- A failed batch summary causes the CLI to return an aggregate batch error even
-  when the detailed batch call has already returned its result.
-
-## Tests And Invariants
-
-Focused tests are in `internal/cli/root_test.go`, `internal/cli/output_test.go`,
-and `internal/cli/result_test.go`.
-
-- CLI summaries are stable, bounded views of app results.
-- Routine batch status lines precede the batch JSON summary.
-- A quiet action produces no successful or failure summary output.
-- Inspection never invokes action-output helpers.
+```sh
+go test ./internal/cli
+```