Record agreed prepared request preview command

docs/roadmap/promptkit-v0.19.0.md

@@ -2,7 +2,7 @@
 
 Status: proposed roadmap for review. Scope is agreed in principle; implementation
 has not started. Command spellings, report designs, and API changes below are
-recommendations until the open decisions are resolved.
+recommendations except where explicitly recorded as agreed below.
 
 ## Purpose and ownership
 
@@ -89,12 +89,12 @@ The original adoption tasks remain included:
    propagation at CommandKit's boundary.
 4. Validate the final independent modules and aligned workspace.
 
-Add the following operator capabilities. Syntax is illustrative and subject to
+Add the following operator capabilities. Syntax is illustrative unless selected
-the decisions at the end of this document.
+in the decisions at the end of this document.
 
 | Operator task | Proposed CLI | Owning module and report |
 | --- | --- | --- |
-| Inspect what a concrete prompt request prepares | `promptkit show request ID --profile … --input … --var …` | `ckprompt`: selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. |
+| Inspect what a concrete prompt request prepares | `promptkit show prepared PROMPT_ID --profile … --input … --var …` | `ckprompt`: YAML report of selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. |
 | Reproduce target/provider settings without editing configuration | Applicable existing smoke override flags on validation and preview; `--extra-params JSON` on these and smoke operations | `ckprompt`: native request forwarding; preview and smoke reports show returned effective settings. |
 | Resolve unqualified resource selections in chosen namespaces | Independent prompt/profile/backend namespace flags | `ckprompt`: delegate to native namespace views, retaining the distinction from catalog filters. |
 | Find configuration paths and inspect their explicitness | `config explain --list --scope promptkit`, with historical selection; metadata alongside path explanation | `ckconfig`, wired through `ckprompt.ConfigScope`: observed paths, effective presence, explicitness/null/origin evidence, and available history. |
@@ -148,8 +148,9 @@ cause identity. Native errors and their categories remain upstream-owned.
 
 ### Preview and request flags
 
-Add an independently available preview capability alongside existing suite
+Expose preview as `promptkit show prepared PROMPT_ID`, with YAML-only output
-callbacks. The native adapter calls `Engine.Prepare` and projects its returned
+initially, through an independently available capability alongside existing
+suite callbacks. The native adapter calls `Engine.Prepare` and projects its returned
 snapshot; a preliminary `ValidateRequest` call is unnecessary. Use existing
 typed selection, acquisition diagnostics, and invocation reporting patterns.
 Exact callback names and signatures follow the selected CLI design.
@@ -335,9 +336,11 @@ Default tests remain offline and independent of real credentials.
   native unknown facts. Smoke preparation errors retain supported causes and
   operational outcomes, including the no-report case; no model dispatch is
   introduced by CommandKit to handle them.
-- [ ] Preview forwards the intended request and faithfully reports native
+- [ ] `promptkit show prepared PROMPT_ID` forwards the intended request and
-  fields. Its CLI path makes no model call and does not create/execute retained
+  faithfully reports native fields in YAML, the only initial output format.
-  prepared handles.
+  Help identifies the argument as a prompt ID and explains resource I/O and
+  rendered content disclosure. Its CLI path makes no model call and does not
+  create/execute retained prepared handles.
 - [ ] New flags preserve selected omission/empty/zero semantics, parse malformed
   inputs through the existing usage path, and do not leak state between runs.
   Numeric decoding of provider JSON matches the selected strategy in OD-2.
@@ -420,21 +423,26 @@ performs application startup effects.
 
 ## Open Decisions
 
-These decisions concern significant choices within the proposed scope. OD
+These decisions concern significant choices within the proposed scope. Resolved
-numbers are local to this roadmap, not the retired adoption documents.
+items retain their numbers and record the agreed decision. OD numbers are local
+to this roadmap, not the retired adoption documents.
 
 ### OD-1: Preview command and report presentation
 
-**Recommendation:** use `promptkit show request ID`, with YAML as the initial
+**Agreed:** use `promptkit show prepared PROMPT_ID`, with YAML-only output
-report format and the complete relevant `PreparedRun` projection. It sits beside
+initially and the complete relevant `PreparedRun` projection. The argument names
-definition inspection while clearly requiring concrete inputs. A single native
+the prompt to prepare, not a saved prepared object. A single native preparation
-preparation supplies both validation and preview evidence. Document rendered
+supplies both validation and preview evidence.
-content disclosure directly in help and CLI guidance.
 
-**Alternative:** `promptkit prepare ID`, with text and YAML reports. This names
+The command sits beside definition inspection and emphasizes that the report
-the native action and makes interactive inspection easier, but can suggest an
+contains resolved settings and rendered content. Use help wording such as:
-executable prepared handle and adds a second rendering contract. Both forms can
+"Prepare a prompt request and show the resulting messages and settings without
-stay entirely within CLI ownership; select vocabulary and formats before coding.
+calling the model."
+
+Document resource I/O and rendered content disclosure directly in help and CLI
+guidance. The report is an inspection snapshot, not a saved execution handle or
+a guarantee that later execution uses the same snapshot or succeeds. A separate
+text presentation may be considered later; it is outside the initial scope.
 
 ### OD-2: Request controls and provider-parameter grammar