Record universal report formats and optional command defaults

docs/roadmap/future.md

@@ -70,7 +70,8 @@ subcommands. The roadmap records the agreed explanation modes and help behavior;
 [OD-6](promptkit-v0.19.0.md#od-6-failure-evidence-and-structured-diagnostic-delivery)
 selects optional validation details, a concise default, and available evidence
 on failure. OD-8 selects focused display, source selection, and report filters.
-Initial report formats and filter spellings are selected in the roadmap;
+Initial report content, default preferences, and filter spellings are selected
+in the roadmap; core owns universal format selection. The
 remaining layout details will be evaluated through implementation and beta use.
 It also includes focused effective display,
 source-ID selection, metadata/diagnostic filters, independent comparison
@@ -161,12 +162,14 @@ steps. No delivery date or final API is selected here.
 ### Reporting extensions
 
 The [shared core report output prerequisite](promptkit-v0.19.0.md#shared-core-report-output-prerequisite)
-is now part of the working adoption roadmap. It records the agreed command
+is now part of the working adoption roadmap. It records application-owned
-output declarations, format-independent reporting operation, and centralized
+content selection, core-owned rendering, a text fallback with optional templates,
-representation rules, initially targeting YAML. Human-oriented/native rendering
+universal format availability, and optional command defaults that otherwise
-and format availability remain open discussions there. Additional renderers such
+defer to core policy. Plain text, YAML, and JSON are the target formats;
-as JSON, XML, and Markdown remain future work; planning for them does not select
+representation, template, native-document, and delivery-staging details remain
-their mappings, command coverage, or delivery dates.
+there. XML is removed from current consideration. Markdown and other potential
+formats are not selected for this adoption; new core formats will work with
+existing commands without per-command adoption.
 
 Error-conversion helpers such as `WarnError` remain deferred pending demonstrated
 value; applications can already use `report.Warn(err.Error())`. Terminal redraw

docs/roadmap/promptkit-v0.19.0.md

@@ -33,7 +33,7 @@ The completed v0.18.0 adoption is not reopened.
 
 | Component | Current baseline | Target |
 | --- | --- | --- |
-| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | Public format-independent report output API, initially targeting YAML, as a prerequisite. Flag collections and scoped aliases still use existing core APIs. |
+| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | Public report output API with universal format selection, optional command defaults, and text/YAML/JSON targets, as a prerequisite. Flag collections and scoped aliases still use existing core APIs. |
 | `ckconfig` | ConfigKit v1.1.0; Go 1.27.0; core v0.3.0 | Adopt the new core reporting API, shared CLI inspection extensions, and an appropriate module release. |
 | `ckprompt` | PromptKit v0.18.0; ConfigKit v1.1.0; ckconfig/core v0.3.0; Go 1.27.0 | Adopt the new core reporting API, PromptKit v0.19.0, and the ckconfig version delivering the shared work. |
 | Candidate | [ckprompt v0.3.0](../../integrations/ckprompt/docs/releases/v0.3.0.md), recorded as unpublished | Update the unpublished candidate after checking its status during implementation. |
@@ -162,11 +162,12 @@ cause identity. Native errors and their categories remain upstream-owned.
 
 ### Preview and request flags
 
-Expose preview as `promptkit show prepared PROMPT_ID`, with YAML-only output
+Expose preview as `promptkit show prepared PROMPT_ID`, defaulting to YAML and
-initially, through an independently available capability alongside existing
+accepting core's universal format choices, through an independently available
-suite callbacks. The native adapter calls `Engine.Prepare` and projects its returned
+capability alongside existing suite callbacks. The native adapter calls
-snapshot; a preliminary `ValidateRequest` call is unnecessary. Use existing
+`Engine.Prepare` and projects its returned snapshot; a preliminary
-typed selection, acquisition diagnostics, and invocation reporting patterns.
+`ValidateRequest` call is unnecessary. Use existing typed selection, acquisition
+diagnostics, and invocation reporting patterns.
 Exact callback names and signatures follow the selected CLI design.
 
 Preview performs applicable resource I/O and rendering but no model call.
@@ -315,34 +316,52 @@ Centralize formatting and translation machinery to the greatest practical
 extent so commands share output conventions and avoid repeated infrastructure.
 Core remains independent of ConfigKit and PromptKit types and domain semantics.
 
-YAML is the initial structured output target. Design the public entry points
+Focus the capability on plain text, YAML, and JSON. YAML remains the first
-for additional formats, such as JSON, XML, and Markdown, without requiring
+structured encoding target; text and JSON are near-term targets, with delivery
-handlers to change their reporting call. This selects extensibility now, not
+staging to be settled during implementation planning. XML is removed from
-implementation of those additional renderers in this adoption. It supersedes
+current consideration. Markdown is not selected for this adoption. New core
-the earlier suggestion to assess only an optional YAML writer during
+formats must work with existing commands without handler refactoring or
-implementation. Keep the implementation proportionate; exact public names,
+per-command encoder registration. This supersedes both the optional YAML-helper
-signatures, and internal representation remain design work.
+proposal and earlier YAML-only report restrictions. Keep implementation
+proportionate; exact public names, signatures, and internal representation remain
+design work.
 
 ### Agreed command declarations and format selection
 
-Declare output behavior once per command, including its default format and
+Core owns the universal `--format` flag, its available options, help, input
-supported alternatives. Core uses that declaration for a standard `--format`
+validation, and renderer selection. Commands do not maintain format allowlists;
-flag, help, input validation, and renderer selection. Omission selects the
+adding a renderer and format option in core makes it available to existing
-declared default; an explicit supported value selects the requested format.
+commands automatically. An unknown format is a usage error before acquisition
-Use one format flag rather than separate `--yaml`, `--json`, or `--xml` flags.
+or other command work. Use one format flag rather than separate format flags.
-An unsupported selection is a usage error before acquisition or other command
-work. Handlers do not repeat this plumbing.
 
-This establishes the declaration and selection mechanism. How available
+Commands may optionally declare a default output format. Resolve the effective
-renderers become supported alternatives for a particular report remains a
+format in this order:
-separate open discussion below.
+
+1. The operator's explicit `--format` choice.
+2. The command's declared default, if supplied.
+3. CommandKit's centrally chosen default.
+
+An unset command default means "CommandKit chooses," not "plain text." Preserve
+that distinction in the public API rather than making the unspecified value an
+alias for text. Core can deliberately change its default in a future release;
+commands with explicit defaults retain their preference. A command default does
+not restrict operator choices or prevent automatic adoption of new formats.
+`config show` declares YAML as its default. Plain text is recommended as the
+initial core default, but that policy is not yet selected.
 
 ### Agreed format-independent reporting operation
 
-Provide one public operation through the invocation Reporter that accepts report
+The application or integration decides what content to report, including which
-data without requiring a handler to switch on the selected format or configure
+information appears normally and what is added by `--details`. Core does not
-an encoder. `invocation.Reporter().Report(report)` illustrates the intended
+select domain facts, add detail when a format changes, or infer a summary.
-shape only; it is not a selected signature or an existing API.
+Retain the agreed `--details` spelling for the standard commands.
+
+Provide one public operation through the invocation Reporter that accepts the
+selected report data and an optional plain-text template, without requiring a
+handler to switch on the selected format or configure an encoder. Core renders
+both concise and detailed report values. `invocation.Reporter().Report(report)`
+illustrates the intended operation only; it is not a selected signature or an
+existing API.
 
 Provide a corresponding writer-based API for rendering outside an invocation.
 Both entry points share the rendering implementation. Invocation reporting uses
@@ -371,34 +390,57 @@ Exact conventions, serialization-contract selection, and adapter APIs need to be
 specified during design. A large public document model or custom reflection
 framework is not selected by this decision.
 
-### Remaining core reporting discussions
+### Agreed plain-text rendering
 
-The following topics remain open and must be settled before their corresponding
+Core provides a default plain-text fallback and accepts an optional template
-API contracts are finalized:
+from the application or integration as part of the report handoff. With a
+template, core renders the chosen text arrangement; without one, it renders the
+selected report data using its standard fallback. YAML and JSON use the same
+selected content and shared representation rules, independently of the text
+template. Applications do not supply separate YAML/JSON writers.
 
-- **Human-oriented presentation (discussion point 4).** Determine how concise
+Recommend a readable hierarchical fallback with named fields, nested values,
-  text and richer formats such as Markdown relate to automatic structured
+and list items. A template can arrange the supplied content as a sentence,
-  rendering, what shared layout helpers are useful, and where custom or native
+table, or another useful presentation. Core owns template execution, shared
-  renderers fit. Generic tables, field lists, custom-renderer hooks, and a
+formatting helpers, and delivery errors. Go's `text/template` and reusable
-  native-document path are candidates, not accepted API requirements. Preserve
+templates declared once are implementation candidates; the template API,
-  the previously agreed operator reports while deciding their implementation.
+helper set, and exact fallback layout still need design.
-- **Format availability (discussion point 5).** Determine how core renderer
-  availability relates to the formats offered by each command or report,
-  including whether adding a renderer automatically enables it for suitable
-  reports or requires explicit adoption. Do not infer that every command must
-  support every format, or select mandatory per-report opt-in, from the agreed
-  declaration mechanism alone. XML mapping conventions and cross-format
-  limitations will need deliberate treatment when those formats are added.
 
-These discussions do not reopen the agreed declaration mechanism, shared
+This resolves the earlier human-oriented presentation discussion (point 4).
-reporting operation, or centralized representation rules. They also do not
+Universal core formats resolve point 5; per-command supported-format lists and
-silently expand the YAML-only reports already selected in this roadmap.
+per-format application renderers are not the selected mechanism.
+
+### Remaining core reporting decisions
+
+- **Initial defaults and staging.** Confirm the initial central default
+  (recommend text), which standard commands pin a default versus inherit core
+  policy, and whether text/YAML/JSON land together or in successive core units.
+  `config show` explicitly defaults to YAML; the existing selected text/YAML
+  presentations are starting targets, not format restrictions.
+- **Shared representation contract.** Specify field/tag and custom-marshaling
+  precedence, omission and scalar rules, supported Go report values, and how
+  unsupported values are reported. Keep adapters explicit and avoid silent
+  numeric loss. This concerns report data, not arbitrary runtime objects.
+- **Text handoff.** Settle the template API and helper functions, whether
+  templates receive the original Go value or shared representation, fallback
+  conventions, and template preparation and failure behavior. Prefer a small
+  reusable mechanism; applications select content and layout, core renders it.
+- **Native documents and multiple results.** Define how native safe YAML
+  snapshots and ordered multi-scope documents enter the shared representation,
+  and how multiple documents/results appear in JSON and text. Preserve native
+  YAML meanings and disclosure rules without silently losing data or exempting
+  commands from universal format support. Keep format translation in core and
+  domain evidence selection in the integrations.
+
+Exact public signatures, flag integration/collision handling, and replacement
+of existing format plumbing are implementation design tasks. The decisions
+above do not reopen content selection, universal formats, or default precedence.
 
 ## Initial report implementation approach
 
 Use the accepted OD-4 through OD-6 flags and formats as a practical starting
 point. Keep added code, report types, and translations proportionate. Beta
-feedback on actual reports should guide changes. Resolve the core discussions
+feedback on actual reports should guide changes. Resolve the core design details
 above, then implement the agreed extension points without delaying delivery
 for exhaustive layout design or speculative additional renderers.
 
@@ -421,10 +463,10 @@ Exceptions serve concrete report semantics: preserving absent/null/false/zero
 and empty collections, expressing paths and durations readably, projecting safe
 snapshot values, and retaining native redaction. Encode report/inspection values,
 not engines, mutable runtime configuration, or request credential storage.
-Preserve existing native-document semantics and concise diff and validation
+Preserve native-document semantics and the concise diff and validation content
-presentations. Their connection to the shared API is part of the open
+selections. Integrations prepare those values and any text templates; core owns
-human-oriented/native-rendering discussion, not a decision to rewrite them as
+rendering. Native-document adaptation is part of the shared representation
-generic structured dumps.
+design, not an integration-owned alternative formatting pipeline.
 
 Separate content projection from format rendering and from invocation delivery.
 Use the existing Reporter and outcome lifecycle for delivery and failures.
@@ -436,15 +478,17 @@ incidental formatting detail in tests.
 ## Work sequence
 
 1. **Confirm remaining implementation choices.** Use the accepted flags and
-   report formats as the MVP target. Resolve the two remaining core reporting
+   report content and default preferences as the MVP target. Resolve the
-   discussions and specify the public API and shared representation conventions.
+   remaining core representation, text-template, native-document, and initial
+   default/staging decisions; specify the public API.
    Resolve outstanding acquisition/binding grammar and flag collisions; use
    concrete examples to review report details during implementation rather than
    reopening accepted scope.
 2. **Implement shared core report output.** Deliver the agreed command output
-   declarations, `--format` selection, format-independent Reporter operation,
+   defaults, universal `--format` selection, format-independent Reporter
-   writer-based API, and shared representation/encoding machinery, with YAML as
+   operation, writer-based API, and shared representation/encoding machinery.
-   the initial structured target. Exercise the public API with core reporting
+   Deliver YAML encoding, text fallback/templates, and JSON encoding according
+   to the selected staging. Exercise the public API with core reporting
    and an application-owned command example, and consolidate suitable existing
    integration reports onto it. Cover the selected contracts and update their
    canonical documentation with the implementation. Complete this prerequisite
@@ -493,12 +537,19 @@ CommandKit to retest PromptKit rendering, schema, namespace, or ConfigKit
 resolution algorithms.
 Default tests remain offline and independent of real credentials.
 
-- [ ] Human-oriented/native rendering and format-availability decisions are
+- [ ] Remaining representation, text-template, native-document, and initial
-  recorded before finalizing their core API contracts. Exact public signatures
+  default/staging decisions are recorded. Public signatures and shared
-  and shared representation conventions are documented with implementation.
+  representation conventions are documented with implementation.
-- [ ] Command output declarations drive defaults, `--format`, help, validation,
+- [ ] Core owns universal `--format` options, help, validation, and selection.
-  and renderer selection. Unsupported selections produce usage failures before
+  Added core formats work with existing commands without refactoring or local
-  acquisition, and selected formats do not leak between invocations.
+  allowlists. Unknown selections fail before acquisition, and selected formats
+  do not leak between invocations.
+- [ ] Explicit operator selection overrides a declared command default, which
+  overrides core policy. An unspecified default remains distinct from text.
+  `config show` defaults to YAML without restricting other format choices.
+- [ ] Plain text uses the supplied template or core's fallback. Core owns
+  rendering and errors in both cases. The integration chooses concise/detailed
+  content; changing format does not implicitly change the selected detail level.
 - [ ] The invocation and writer-based public APIs share rendering behavior;
   handlers submit report data without their own format switches or encoder
   setup. Existing quiet-mode, presentation-failure, and domain-outcome behavior
@@ -519,7 +570,8 @@ Default tests remain offline and independent of real credentials.
   operational outcomes, including the no-report case; no model dispatch is
   introduced by CommandKit to handle them.
 - [ ] `promptkit show prepared PROMPT_ID` forwards the intended request and
-  faithfully reports native fields in YAML, the only initial output format.
+  faithfully reports native fields, defaulting to YAML and accepting universal
+  format choices.
   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.
@@ -557,9 +609,10 @@ Default tests remain offline and independent of real credentials.
 - [ ] Bare `config explain` displays help successfully, presenting `--list` and
   `--path` as the two alternatives. Selecting both modes is a usage error;
   explicitly supplied `--path ""` selects root explanation rather than help.
-- [ ] Discovery uses text by default with YAML available, compact path/presence/
+- [ ] Discovery retains its initial text default preference, with universal
-  explicitness fields, and the selected `--historical`, `--under`, and
+  format choices, compact path/presence/explicitness fields, and the selected
-  `--explicit` behavior. Historical-only paths and unavailable discovery are not
+  `--historical`, `--under`, and `--explicit` behavior. Historical-only paths and
+  unavailable discovery are not
   misreported as current implicit values or an empty configuration.
 - [ ] Metadata discovery through `config explain` distinguishes effective and
   historical paths, retains available history on absent lookup, and projects
@@ -573,9 +626,10 @@ Default tests remain offline and independent of real credentials.
   when there are no differences.
 - [ ] Focused display preserves native snapshot content and distinguishes
   missing/historical-only paths from explicit null. Whole-document display
-  retains its current contract. Focused display uses one scope and native YAML
+  retains native YAML semantics when that format is selected. Focused display
-  without a snapshot wrapper; absent effective paths and unknown source IDs
+  uses one scope and defaults to the native YAML value without a snapshot
-  produce clear operational failures.
+  wrapper; other formats use the shared representation. Absent effective paths
+  and unknown source IDs produce clear operational failures.
 - [ ] Source-ID selection works on successful and failed acquisitions. Path,
   explicitness, severity, and code filters preserve the selected evidence and
   source references without masking the acquisition outcome.
@@ -591,10 +645,10 @@ Default tests remain offline and independent of real credentials.
   selected comparison-side behavior, native errors, and returned provenance
   preserved. No tests independently re-establish ConfigKit override semantics.
 - [ ] Default validation remains concise; `--details` selects the additional
-  diagnostic report, with text by default and optional YAML. Selecting YAML
+  diagnostic report, with an initial text default preference and universal
-  alone does not enable detailed mode. Severity/code filters, evidence
+  format choices. Changing format alone does not enable detailed mode.
-  availability, no-match presentation, and known duplicate-warning handling
+  Severity/code filters, evidence availability, no-match presentation, and
-  preserve the underlying validation outcome.
+  known duplicate-warning handling preserve the underlying validation outcome.
 - [ ] `config sources` and `config validate --details` report
   available evidence with an acquisition error;
   the original failure, unavailable-versus-empty evidence, cancellation, and
@@ -640,10 +694,11 @@ from configuration to deliver it in this roadmap. General execution, prepared
 handle lifecycle, sessions, and observer convenience APIs remain application
 responsibilities. Persistent configuration editing, new live probes, dynamic
 completion, and unrelated deferred proposals are not added by this roadmap.
-JSON, XML, and Markdown renderers remain future additions; the
+The [shared core API](#shared-core-report-output-prerequisite) targets text,
-[shared core API](#shared-core-report-output-prerequisite) now explicitly plans
+YAML, and JSON, with automatic availability of newly added core formats.
-for format extensibility. Renderer availability policy remains open, and this
+XML is removed from current consideration; Markdown is not selected for this
-roadmap does not promise those formats for every report.
+adoption. Exact delivery staging for the three target formats remains to be
+settled, rather than retaining JSON as an unrelated deferred proposal.
 Transient acquisition overrides are included under OD-11.
 Output-contract override and appended-message flags are deferred under OD-2
 and retained in
@@ -658,10 +713,19 @@ These decisions concern significant choices within the proposed scope. Resolved
 items retain their numbers and record the agreed decision. OD numbers are local
 to this roadmap, not the retired adoption documents.
 
+The core ownership, text fallback/template, universal-format, and default
+precedence decisions are now agreed above. Their remaining design details are
+listed under [remaining core reporting decisions](#remaining-core-reporting-decisions).
+Outstanding integration choices are provider JSON decoding in OD-2, namespace
+applicability in OD-3, empty comparison collections and binding design in OD-9,
+and override grammar/acquisition details in OD-11. Exact helper names and report
+layouts otherwise remain ordinary implementation choices, not unresolved scope.
+
 ### OD-1: Preview command and report presentation
 
-**Agreed:** use `promptkit show prepared PROMPT_ID`, with YAML-only output
+**Agreed:** use `promptkit show prepared PROMPT_ID`, with YAML as its default
-initially and the complete relevant `PreparedRun` projection. The argument names
+and the complete relevant `PreparedRun` projection. Universal core format
+selection supersedes the earlier YAML-only restriction. The argument names
 the prompt to prepare, not a saved prepared object. A single native preparation
 supplies both validation and preview evidence.
 
@@ -672,8 +736,9 @@ 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
+a guarantee that later execution uses the same snapshot or succeeds. Core's
-text presentation may be considered later; it is outside the initial scope.
+text fallback supplies text output without requiring a dedicated preview
+template; a specialized template is not required for initial delivery.
 
 ### OD-2: Request controls and provider-parameter grammar
 
@@ -847,8 +912,8 @@ missing-path usage error; automatic discovery on a bare invocation is not
 selected.
 
 **Agreed initial presentation:** use a compact text discovery report by default,
-with YAML available through `--format yaml`, and one scope at a time. List
+with alternatives through core's universal `--format`, and one scope at a time.
-current effective paths by default; `--historical` adds historical-only paths
+List current effective paths by default; `--historical` adds historical-only paths
 rather than selecting only removed paths. Show path, current/historical-only
 presence, and available explicitness. Do not equate non-explicit values with
 application defaults or historical-only metadata with explicitness false.
@@ -888,7 +953,9 @@ presence so missing and null remain distinct. Show redaction and concealed-chang
 annotations where relevant; omission of an optional annotation has a defined
 meaning and never relies on recognizing a marker-looking string. Prefer ordinary
 Go fields and serialization tags to custom omission logic. An empty comparison
-has an explicit empty difference list. YAML is the only initial detailed format.
+has an explicit empty difference list. Retain YAML as the default preference;
+universal core formats supersede the earlier YAML-only detailed restriction.
+The same selected comparison evidence is handed to core in every format.
 
 Keep the projection close to native report values, using the
 [shared reporting approach](#initial-report-implementation-approach) rather than
@@ -915,8 +982,8 @@ mode on `config diff`. Retain concise validation by default, including its
 ordinary warning and error reporting. Detailed mode reports available native
 diagnostic records and source references alongside the validation result. The
 purpose is to help a human operator locate and investigate configuration
-problems; it does not introduce new validation rules. Selecting YAML alone does
+problems; it does not introduce new validation rules. Changing the output format
-not implicitly enable the additional detail.
+does not implicitly enable the additional detail.
 
 Preserve available evidence when loading fails: `config validate --details`
 reports diagnostic findings and relevant source references, and `config sources`
@@ -931,9 +998,10 @@ structured evidence through to reporting. Use current core reporting and outcome
 handling; no generic cross-family diagnostics framework is required.
 
 **Agreed initial presentation:** detailed validation uses text by default, with
-YAML available through `--format yaml`. Begin text output with scope and outcome,
+alternatives through core's universal `--format`. Supply a text template that
-then show readable findings with their available messages, severities, codes,
+begins with scope and outcome, then shows readable findings with their available
-configuration paths, and source locations. Place useful locations near messages;
+messages, severities, codes, configuration paths, and source locations. Place
+useful locations near messages;
 YAML may use a source legend shared by multiple findings.
 
 Use repeatable `--severity` and `--code` filters in detailed mode. Multiple values
@@ -984,10 +1052,12 @@ does not authorize publication.
 Keep reports unfiltered by default. The purpose is to reduce noise for a human
 operator investigating a known part of the configuration.
 
-Focused show emits the selected native effective YAML directly, without a
+`config show` explicitly defaults to YAML. In that format, focused show emits
-snapshot wrapper containing presence/redaction/YAML fields. Use the existing
+the selected native effective YAML directly, without a snapshot wrapper
-explanation capability to obtain the native snapshot. An absent effective path
+containing presence/redaction/YAML fields. Other core formats render the selected
-or unknown source ID produces a clear operational failure. Explicitly present
+value through the shared representation; YAML is a default, not a restriction.
+Use the existing explanation capability to obtain the native snapshot. An absent
+effective path or unknown source ID produces a clear operational failure. Explicitly present
 null remains a valid value; historical-only paths are not effective values.
 Path-selected display initially uses one scope, while whole-document
 `--scope all` remains available.