Document profile comparison workflow

docs/internal/app-orchestration.md

@@ -1,6 +1,9 @@
 # Application Orchestration Internals
 
-`internal/app` owns stateless report generation, batch execution, atomic output publication, and notification coordination after `internal/cli` has parsed arguments and loaded configuration. The user contract is owned by the [CLI reference](../cli.md) and [operations guide](../operations.md).
+`internal/app` owns stateless report generation, batch execution, comparison
+orchestration, atomic output publication, and notification coordination after
+`internal/cli` has parsed arguments and loaded configuration. The user contract
+is owned by the [CLI reference](../cli.md) and [operations guide](../operations.md).
 
 ## Single-Report Flow
 
@@ -16,6 +19,23 @@ Failures return an active partial result with safe identity, profile, warning, v
 
 Each item has an independent result. A failed item does not stop later items; successful items retain their published output paths. Per-report notification is suppressed during a batch. Batch notification runs only after every planned report has published successfully. It is skipped when any item failed. Batch result counters count report items only; a batch notification failure is represented by the top-level notification result and still produces a failed batch outcome.
 
+## Comparisons
+
+`CompareDetailed` validates ordered explicit profile IDs, resolves the report,
+and preflights the exact bundle destination before initializing optional prompt
+debugging, prompt inspection, or collection. It then inspects the one prompt
+and every selected profile, collects once, and delegates shared report
+construction to the prepared-report flow. It does not accept a notifier.
+
+The comparison execution core starts each inspected profile independently,
+keeps results in selection order, and waits for all started work. Independent
+profile failures are recorded and do not stop peers. Context cancellation marks
+unfinished work and prevents publication. Details of prepared values, execution
+and debugging, and publication are documented in [prepared report
+internals](prepared-report.md), [comparison execution
+internals](comparison-execution.md), and [comparison publication
+internals](comparison-publication.md).
+
 ## Boundaries And Verification
 
 The package does not parse flags, load YAML, implement transport, construct provider SDKs, or define report-period policy. Prompt, profile, weather, and Distributor implementations remain behind project-owned contracts.

docs/internal/comparison-execution.md

@@ -0,0 +1,25 @@
+# Comparison Execution Internals
+
+The comparison execution core receives an already prepared report and an
+already inspected, ordered profile list. It initializes an outcome for every
+selected profile, launches each started profile in its own goroutine, and
+waits for every started goroutine before returning. Results retain the supplied
+selection order even though execution completes in an arbitrary order.
+
+Every profile uses the exact inspected prompt identity and a private copy of
+the same prepared data package. Provider, generated-text validation, rendering,
+or debug-write failure becomes that profile's safe failed outcome and does not
+cancel its peers. The application deliberately imposes no additional semaphore:
+Promptkit owns backend capacity. Cancellation or a deadline marks unfinished
+outcomes as skipped or failed, joins work, and prevents bundle publication.
+
+When debugging is enabled, each execution receives a deterministic reference
+derived from the comparison identity, ordered profile position, and safe
+profile slug. This keeps concurrent captures separate. The debug writer itself
+owns secure-root validation and file permissions; operational retention and
+sensitivity are documented in the [operations guide](../operations.md).
+
+The output result and its safe errors are converted into the durable contract
+only by comparison publication. See [comparison publication
+internals](comparison-publication.md) and the external [comparison bundle
+contract](../integrations/comparison-bundle.md).

docs/internal/comparison-publication.md

@@ -0,0 +1,22 @@
+# Comparison Publication Internals
+
+`internal/comparison` separates the logical bundle from filesystem mechanics.
+The application builds a validated manifest, exact shared data-package bytes,
+and only the Markdown files for successful profiles. The durable layout,
+schema, and compatibility rules are owned by the [comparison bundle
+contract](../integrations/comparison-bundle.md).
+
+Destination planning is read-only. It requires an exact absolute target that
+is neither the filesystem root nor the working directory, rejects unsafe
+symlinks and non-directories, accepts a missing or empty directory, and permits
+replacement only for a recognized current bundle. Publication rechecks that
+plan, writes a private sibling staging directory, and installs it atomically.
+Replacement temporarily moves the recognized prior bundle aside and restores it
+if installation fails.
+
+The application preflights before prompt inspection and collection, then
+preflights again before publication. A cancellation or any failure before the
+commit leaves the prior destination untouched. Completed bundles include
+partial profile results; comparison publication never coordinates Distributor
+notification. Operator-facing lifecycle and cleanup are in the
+[operations guide](../operations.md).

docs/internal/prepared-report.md

@@ -0,0 +1,20 @@
+# Prepared Report Internals
+
+`internal/app` builds a `preparedReport` after collection and before profile
+execution. This is the immutable boundary shared by ordinary report generation
+and profile comparison; it is not a durable artifact.
+
+Preparation builds report facts, the configured module snapshot, briefing
+metadata, the curated prompt-input package, serialized YAML, and the
+generated-text definition. It deep-copies mutable facts, snapshots, metadata,
+and data-package bytes before returning them. Consumers receive independent
+copies so one execution cannot change another's input or rendering context.
+
+Single-report generation executes one prepared profile and publishes its
+Markdown. Comparison prepares once, gives every selected profile the same YAML
+bytes, and only then assembles the resulting logical bundle. The prompt-input
+shape is owned by [prompt-input internals](prompt-input.md); profile execution
+semantics are owned by [Promptkit integration](../integrations/promptkit.md).
+
+Preparation failure has no publication side effects. Tests for this boundary
+cover mutation isolation, byte equality, and reuse by both execution paths.