commandkit/docs/roadmap/promptkit-v0.20.0.md

# Shared report output, PromptKit v0.20.0 adoption, and ConfigKit operator CLI

Status: agreed feature roadmap; implementation is in progress. The numbered
decisions and final review clarifications are settled. The
[implementation plan](implementation.md) owns staged execution and concrete API
and transition choices; native resource report fields follow upstream. Practical
beta feedback will guide presentation refinements.

Reading guide: the core prerequisite sections own shared mechanics; resource
inspection and OD-1 through OD-11 own integration behavior. The overview links
to those decisions, and the completion checklist identifies verification
boundaries without redefining policy.

## Ownership principles

The [architecture ownership table](../policy/architecture.md#ownership-boundaries)
and [Go types and facilities policy](../policy/architecture.md#go-types-and-facilities)
now own the agreed principles. Core supplies CLI mechanics and output formatting;
applications and integrations choose report content, and upstream libraries own
domain semantics. This roadmap owns the desired target and its specific input,
serialization, and presentation contracts. The
[implementation plan](implementation.md) owns the steps from the current
baseline to that target.

## Purpose and ownership

Adopt released PromptKit v0.20.0 and expose useful operator tasks through
standard CommandKit commands, flags, and reports. This roadmap covers CLI
exposure, including ConfigKit v1.1.0 operator features in `ckconfig`, with shared
core reporting and CLI input capabilities as prerequisites to the downstream work.
Core standardizes report format selection, representation, rendering, and
delivery for core commands, integrations, and application-owned commands.
Applications and integrations continue to choose report content. This does not
turn `ckprompt` into a convenience library for application-internal PromptKit
operations. Applications continue to own engine construction, domain inputs,
credentials, execution, and their executable lifecycle.

`ckprompt` neutrally exposes the released upstream capabilities and their returned
evidence. CommandKit is in alpha with no consumers: implement a clean adoption
of v0.20.0, with no backward-compatibility adapters, legacy report shapes, or
consumer migration guidance. Update the final API, CLI documentation, examples,
and candidate notes to describe the selected behavior directly.

The [architecture policy](../policy/architecture.md),
[optional-module decision](../adr/0004-optional-integration-modules.md), and
[reporting decision](../adr/0006-invocation-reporting.md) govern implementation.
The [CLI reference](../cli.md) and public GoDoc remain the owners of implemented
contracts. This roadmap records planned work, not new guarantees about upstream
behavior or permanent limits on future features.

## Baseline and released evidence

Planning baseline: `e90821331874c926eb5f95216dc2bb4bcbf4a115`. The table
below distinguishes the implemented dependencies from the selected target.

| Component | Current baseline | Target |
| --- | --- | --- |
| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | Shared report output, public CLI JSON parsing, and ordered typed input composition. Text/YAML/JSON land together. Collections and aliases retain existing declaration 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.20.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. |
| Local workspace | Core and both integrations, Go 1.27.0 | Validate local composition and independent modules separately. |

Use PromptKit tag `v0.20.0`, commit
`8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf`. Its Go minimum remains
1.27.0 and its ConfigKit dependency remains v1.1.0. Reviewed sources are the
[release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/releases/v0.20.0.md),
[request and report types](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/types.go),
[resource inspection reports](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/resource_inspection.go),
[configuration and execution semantics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/formats.md),
[engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.go),
[namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/namespaces.go),
[configuration inspection API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/configuration_inspection.go),
and [smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/smoke_diagnostics.go).
Work against released versions only; do not inspect or monitor unreleased
upstream work in anticipation of another adoption.

ConfigKit v1.1.0 is already adopted at released commit
`191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9`. Its
[inspection API](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/inspection.go),
[metadata API](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/metadata.go),
and [configuration reference](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md)
support the additional CLI work below without an upstream dependency upgrade.
Its matched history for registered records moving within lists flows through
native inspection; it does not introduce identity-based CLI paths or
element-level effective diffs.

Current `ckprompt` supplies prompt/profile inspection, requirements discovery,
concrete request validation, prompt/profile/backend/namespace/collection
catalogs, and four smoke operations plus `test all`. Smoke commands already
expose most execution overrides and detailed native evidence. Validation has
profile, session, variable, and file-input flags but lacks that override surface.
There is no concrete request preview or dedicated backend detail command.

Current `ckconfig` supplies validation, native effective YAML, source inventory,
path explanation with history, and reduced semantic comparison. Its `View`
contains effective, sources, and explanation facets. Native metadata is not
exposed as a capability. `config sources` returns on acquisition failure before
rendering evidence; loaders convert native diagnostics into presentation
messages but do not expose a structured diagnostics report. Relevant boundaries
are [ckconfig contracts](../../integrations/ckconfig/contracts.go),
[ConfigKit adapters](../../integrations/ckconfig/configkit_adapter.go), and
[PromptKit adapters](../../integrations/ckprompt/adapters.go).

Effective display currently writes the whole configuration. Sources are reported
as a complete inventory. Comparison accepts independent config/overlay choices,
but applies the same application selectors to both typed inputs and succeeds
when a comparison reports differences. The new tasks extend those boundaries;
they do not replace already-delivered explanation or smoke functionality.

## Targeted end state

First establish the [shared core report output capability](#shared-core-report-output-prerequisite).
The integration work below uses that public API instead of adding independent
format-selection and encoding machinery in each module. The
[core input prerequisites](#shared-core-cli-input-prerequisites) provide shared
CLI JSON parsing and the required cross-flag input ordering.

The adoption includes:

1. Update the dependency, checksums, attribution, and unpublished candidate note
   to the released v0.20.0 target.
2. Use the released resource inspection types and document the operator-facing
   distinctions among resources, configuration evidence, and prepared requests.
3. Cover native resource reports/errors, authentication response-limit evidence,
   and smoke preparation-error propagation at CommandKit's boundary.
4. Validate the final independent modules and aligned workspace.

Deliver the following operator capabilities. The resource inspection section
and numbered decisions own syntax and behavior; these examples summarize tasks.

| Operator task | CLI examples | Owning module and report |
| --- | --- | --- |
| Inspect a captured prompt definition | `promptkit show prompt PROMPT_ID` | `ckprompt`: native `PromptInspection`, including unrendered messages and presence-aware metadata. |
| Inspect a resolved profile resource | `promptkit show profile PROFILE_ID` | `ckprompt`: native `ProfileInspection`, before backend completion and request overrides. |
| Inspect backend settings without running a probe | `promptkit show backend BACKEND_ID` | `ckprompt`: native `BackendInspection`, including configured smoke diagnostics. |
| Inspect what a concrete prompt request prepares | `promptkit show prepared PROMPT_ID --profile … --input-file … --var …` | `ckprompt`: YAML report of selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. |
| Supply a short sample to one prompt without creating a file | `promptkit show prepared PROMPT_ID --input NAME=TEXT`; also request validation | `ckprompt`: native inline input for single-prompt preparation; file input remains available through `--input-file NAME=PATH`. |
| Reproduce target/provider settings without editing configuration | Applicable existing smoke override flags on validation and preview; `--llm-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. |
| Understand both sides of configuration changes | `config diff --scope promptkit --details` | `ckconfig`: native paths, left/right snapshots, presence/redaction, and hidden-change evidence. |
| Investigate a failed configuration load | `config sources --scope promptkit` on failure; `config validate --details --scope promptkit` | `ckconfig`, with both native adapters: acquired source inventory and native codes, severities, paths, and locations while retaining the load failure. |
| Inspect one effective value or subtree | `config show --scope app --path /server` | `ckconfig`: the selected native effective snapshot, retaining redaction and absence/null distinctions. |
| Follow a source reference | `config sources --source-id ID` | `ckconfig`: the matching acquired source record, including evidence available after failure. |
| Compare different application selections | For example, `config diff --campaign spring --against-campaign autumn` | `ckconfig`: independently prepared typed inputs passed to the existing native comparison provider. |
| Detect configuration differences in scripts | `config diff --check` | `ckconfig`: a deliberate difference outcome based on native records, alongside the selected comparison report. |
| Narrow an inspection to relevant evidence | Subtree/explicitness filters on explanation discovery; severity/code filters on validation diagnostics | `ckconfig`: filtered native evidence with source references retained. |

The configuration suite retains six subcommands: `scopes`, `validate`, `show`,
`sources`, `explain`, and `diff`. Path discovery belongs within `config explain`;
structured diagnostics belong within `config validate`. This command placement
is agreed. OD-4 selects `--list` and `--path` as the explanation modes, with
help on a bare invocation. OD-6 selects `config validate --details` for detailed
diagnostics while retaining concise validation by default. Initial report
presentation and filter spellings are selected under OD-4, OD-6, and OD-8; exact
Go projections can be refined during implementation. No separate path inventory
or diagnostics subcommand is planned.

Transient configuration overrides are included under OD-11 as an opt-in loader
capability. `config validate --set /workers=0` and
`config show --set /server/port=8080` apply temporary overrides during acquisition
without editing source files. OD-11 selects simple assignment syntax and normal
load-time forwarding; paths containing `=` are unsupported by these flags. Comparison
overrides follow OD-9's independent-side model: `--set` affects only the left
side and `--against-set` only the right.

### Resource inspection

Expose `promptkit show prompt PROMPT_ID`, `promptkit show profile PROFILE_ID`,
and `promptkit show backend BACKEND_ID` as peer resource commands. Each selects
one resource through its corresponding released `Engine.Inspect*` API and hands
the returned `PromptInspection`, `ProfileInspection`, or `BackendInspection`
directly to core. Use the full native report, without a separate summary/details
mode or a dedicated text template. The structured mapping automatically selects
YAML; explicit JSON or text uses the same core rendering rules and content.
Remove the duplicated prompt/profile report structs and per-field formatters.

The upstream report types own the fields and their meanings:

- Prompt inspection includes captured, unrendered inline or imported messages,
  cache metadata, declared inputs, description/session/default-profile metadata,
  output settings, and the opaque prompt hash. Referenced profiles and schemas
  are not resolved by this inspection.
- Profile inspection exposes the resolved profile after composition and sibling
  inheritance, before backend completion, execution defaults, or request
  overrides. An omitted endpoint is not evidence that the completed request
  lacks one. Use `show prepared` to see completed request settings; do not
  reconstruct an effective target inside the profile command.
- Backend inspection includes its endpoint, credential environment reference,
  concurrency/queue configuration, provider parameters, and configured smoke
  diagnostics. These are configured settings, not live capacity occupancy,
  derived probe destinations, or probe results. Actual smoke operations remain
  under `promptkit test`.

Preserve native omission and presence, including explicit empty strings, zero,
false, and empty collections. Do not fill absent resource fields with execution
defaults or infer provenance from nil pointers. Configuration inspection through
`config show` and `config explain` remains the source of effective configuration,
explicit null, and provenance evidence; resource reports do not replace it.

Add an independently optional backend-inspection callback to `Suite`, following
the prompt/profile acquisition pattern, and wire it through `FromEngine`. A nil
callback omits only that command. Use the standard configuration/application
selectors and input/state/diagnostic lifecycle. Backend selection is a positional
ID; install only its applicable namespace control under OD-3, without request
execution overrides, profile selection, or a redundant backend flag. Help and
completion reflect capability availability without acquiring an engine.

Preserve acquisition failures, cancellation, and supported native error identity,
including `ErrBackendNotFound`; do not relabel an absent backend as
`ErrInvalidRequest` or fabricate an empty successful report. Use the existing
operational-outcome and presentation-failure paths.

Help distinguishes captured resource content from rendered request content.
Application acquisition can load sources and capture message files; the resource
inspection call itself does not prepare requests, read schemas or request inputs,
resolve credentials, or contact providers. Inspection success is not a readiness
check. Credential environment references are names, not resolved secrets, but
arbitrary prompt and provider content is not guaranteed safe for public disclosure.

### Released upstream semantics

Adopt PromptKit v0.20.0 semantics directly. Keep operator help focused on the
selected operation and link to upstream contracts for domain rules:

- After configuration composition and inheritance, profile null endpoint,
  credential source, and whole provider map permit backend defaults. Empty
  strings explicitly clear the endpoint or credential source; an empty provider
  map does not suppress backend entries. Profile-level whole-map suppression
  is not an upstream operation. Nested provider nulls remain literal data.
  ConfigKit's inspection still records explicit nulls and their provenance.
- `api_key_required`, when present and true, requires a usable direct or
  environment credential and can coexist with an explicit profile `api_key_env`.
  A required key with an absent/null profile source suppresses the backend
  credential source. Inspection does not establish credential availability.
- Request provider overrides retain their native whole-map replacement behavior,
  separate from configuration composition. Do not impose source-construction
  restrictions on runtime request flags or reimplement upstream merging rules.
- Preparation uses self-contained schemas. Preserve native preparation failures
  and their causes; resource inspection reports a schema reference without
  loading or validating it. Upstream owns schema acceptance and resolution.

The authentication response-limit reason is evidence of unknown credential
acceptance. Forward native findings without converting false, unknown,
unsupported, or incomplete observations into command failures. Actual
preparation/operation errors retain the operational outcome and supported cause
identity. Native errors and their categories remain upstream-owned.

Programmatic `PromptSource`, profile/backend source construction, custom artifact
readers, and backend sibling-inheritance helpers remain application-owned upstream
APIs. Maintained examples must use the released contracts, but this adoption adds
no CommandKit wrappers or CLI commands for those construction conveniences.

### Preview and request flags

[OD-1](#od-1-preview-command-and-report-presentation) owns prepared preview;
[OD-2](#od-2-request-controls-and-provider-parameter-grammar) owns reusable flag
collections, aliases, input forms, and precedence. Expose preview as an independent
capability alongside existing suite callbacks. Call `Engine.Prepare` once and
hand its native snapshot to core under OD-1; a preliminary `ValidateRequest`
call is unnecessary.
Upstream excludes resolved credentials from prepared settings, but rendered
application content is not a redacted configuration report.

Build collections using `CommandSpec[I].Flags`, typed constructors, and
`Supplied[T]`. Existing [CaptureFlags and FlagValues.ApplyTo](../../flag_values.go)
serve ordinary deferred application. Collections and alias generation need no
new abstraction; cross-flag input ordering and shared JSON parsing use the
[additional core input prerequisites](#shared-core-cli-input-prerequisites).
Applications retain their input types, request construction, acquisition, and
execution. Keep execution-target overrides distinct from transient retries:
ordinary requests and smoke diagnostics have different upstream retry defaults.

### Namespace selection

[OD-3](#od-3-namespace-flags-and-loader-defaults) owns the opt-in namespace
composition, applicability table, and profile-identity clarification. Implement
one native view update using declared defaults and supplied fields. Verify the
selected flags against actual upstream operations; captured references and
catalog filters retain their upstream meanings.

### Shared configuration capabilities

Extend `ckconfig` through optional capabilities, exposed by `FromConfigKit` and
`ckprompt.ConfigScope`. Providers need not implement every inspection mode;
help and availability must reflect their supplied capabilities.

- Metadata discovery uses `Metadata.HistoricalPaths`, `Lookup`, `IsExplicit`,
  and `History`. It covers observed paths, not every possible schema field.
  Preserve history after absent lookup and native list-index paths. OD-4 owns
  the operator presentation and filters.
- Detailed diff reuses `Scope.Compare` and native `Difference` records under
  OD-5. Native sequence changes remain atomic; no element-matching algorithm or
  reloadable patch format is added.
- Failed-load evidence uses `LoadError.Sources()` and `Diagnostics()` alongside
  the original error. Acquisition must distinguish unavailable evidence from an
  available empty inventory. A failed load establishes no effective configuration
  or metadata capability. OD-6 owns diagnostic presentation, aggregation, and
  failure delivery; this work requires adapter changes, not only a renderer.

### Additional ConfigKit operator workflows

[OD-8](#od-8-focused-configuration-reports-and-filtering) owns focused values and
source selection. Obtain path values from native `Explain(path)` and whole
configuration values from safe `WriteEffective` output, converting both through
core. Never reconstruct inspection from mutable `Result.Config` or source files.
Select source IDs from acquired inventory; native `Source(id)` is a convenience,
not another provider requirement. Source IDs are local to one load.

[OD-9](#od-9-independent-comparison-selector-bindings) replaces the
[current comparison inheritance](../cli.md#compare-configuration-selections)
while retaining the two-input/provider lifecycle. Domain defaults and caching
remain application-owned.
[OD-10](#od-10-comparison-assertion-outcomes) uses native differences for assertions;
source/history differences alone and changed credential bytes behind unchanged
references are not necessarily effective-value differences.

[OD-11](#od-11-transient-configuration-overrides) owns temporary override syntax
and forwarding. ConfigKit recursively overlays mapping overrides and replaces
sequences, unlike PromptKit's complete provider-map replacement. Shared numeric
parsing must not erase that distinction. Source-load errors remain errors even
if a supplied override would replace the affected value.

## Shared core report output prerequisite

**Agreed scope:** add a first-class public reporting capability to CommandKit
core before implementing the downstream integration additions. An application
or integration gathers report data and hands it to core; core selects the
default or operator-requested format, renders the report, and delivers it.
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.

Deliver plain text, YAML, and JSON together in the same core feature release,
implemented in separate reviewable units as useful. Exercise all three before
downstream integration additions depend on the API, so representation decisions
are validated across formats. XML is removed from current consideration.
Markdown is not selected for this adoption. New core formats must work with
existing commands without handler refactoring or
per-command encoder registration. This supersedes both the optional YAML-helper
proposal and earlier YAML-only report restrictions. Keep implementation
proportionate; the [implementation plan](implementation.md) selects public
handoffs and the representation approach.

### Agreed universal and automatic format selection

Core owns the universal `--format` flag, its available options, help, input
validation, and renderer selection. Commands do not maintain format allowlists;
adding a renderer and format option in core makes it available to existing
commands automatically. An unknown format is a usage error before acquisition
or other command work. Use one format flag rather than separate format flags.

The initial public API does not offer command-specific format defaults. Resolve
the effective format in this order:

1. The operator's explicit `--format` choice.
2. Text when the report handoff includes a text template.
3. Core's automatic selection from the shared report representation below.

| Report content, without a text template | Automatic format |
| --- | --- |
| String | Text |
| Nonempty sequence containing only strings | Text, one item per line |
| Number or boolean | Text |
| Mapping, including an empty mapping | YAML |
| Sequence of mappings, nested sequences, or mixed values | YAML |
| Empty sequence or null | YAML, keeping the empty result visible |

Inspect the logical report representation after the selected serialization and
adaptation rules, not just the original Go type. A struct normally represents a
mapping, while a custom serializer may represent that value as a string. Use the
outer shape; do not search inside mappings for a presumed primary field. Select
once for the complete logical report, not independently for each item in a
result collection.

Omitting `--format` means "CommandKit chooses," not a fixed text default. The
choice can vary with the result: a populated string list yields text, while an
empty list yields YAML `[]`. Explicit selection provides a predictable format
when needed, including `config show --format yaml` for a configuration document
even when the selected value is a string. Core can deliberately evolve its
automatic policy in a future release.

This supersedes optional command defaults and the proposed per-command default
inventory, including explicit YAML defaults for `config show`, `config diff`,
and prepared-request preview. Applications choose report content and optional
text templates; core selects the format. Reconsider command overrides only for
a concrete demonstrated requirement.

For `config show`, hand off the selected logical configuration value, not a
string containing serialized YAML or a snapshot metadata wrapper. With no text
template, a configuration mapping naturally selects YAML and a selected string
value selects text. Native snapshot adaptation must preserve that distinction.

### Agreed format-independent reporting operation

The application or integration decides what content to report, including which
information appears normally and what is added by `--details`. Core does not
select domain facts, add detail when a format changes, or infer a summary.
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
the existing Reporter lifecycle for visibility, destinations, delivery, and
presentation failures, preserving domain outcomes and causes. This extends the
existing reporting facility rather than creating a second delivery lifecycle.

Integration handlers decide whether cancellation stops report submission or
whether already-acquired evidence should still be reported. Core renders the
submitted content through its ordinary visibility and presentation-failure
lifecycle; do not introduce a blanket invocation-cancellation check that discards
such evidence. Ordinary inspection can stop before submission, while smoke
reports and OD-6 aggregate validation preserve available evidence after
cancellation. This does not resume canceled acquisition or execution work.

### Agreed shared representation rules

**Agreed:** use Go's standard `encoding/json` serialization conventions to
interpret ordinary Go report values for core serialization. Prepare one logical
representation for YAML/JSON output and for automatic selection and text
rendering when no text template is used. Application-supplied text templates instead
receive the original Go value, as specified below. JSON conventions do not
select JSON as the default output format or expose core's intermediate data
representation as a public template contract.

Reuse the standard library's field selection, JSON tags, omission rules, nested
value handling, and supported custom JSON serialization. Avoid a new CommandKit
tag convention or reflection-based serialization engine. Suitable upstream
values can reuse their existing JSON contract; thin projections remain useful
when the desired operator content differs from that representation.

- **One serialized field interpretation.** JSON field tags and custom
  serialization govern ordinary values in core-serialized outputs. Conflicting
  YAML tags or YAML-specific serialization do not change that interpretation.
  For example, a field tagged
  `json:"retry_count" yaml:"retries"` appears as `retry_count` in both JSON and
  YAML. Do not independently serialize the original Go value with each encoder.
- **Explicit omission.** Honor omissions selected by the JSON contract. Core
  does not additionally hide zero, false, empty, or null values for brevity.
  Preserve the remaining distinctions among absent, null, false, zero, and empty
  values through conversion and rendering.
- **Preserved numeric values.** Avoid precision loss in intermediate conversion,
  including accidental rounding of large integers through floating point. This
  preserves the serialized value rather than promising precision beyond the
  supplied value and its serialization contract.
- **Observable failures.** When serialization is used, values rejected by its
  contract produce presentation errors through the existing reporting lifecycle.
  Do not silently drop unsupported data or substitute arbitrary string
  representations. Templated text executes against the original value without
  requiring a JSON round trip.

**Agreed configuration input conversion:** decode upstream safe inspection YAML
into ordinary Go report values, then use the same shared representation and
renderers as other reports. Core owns the explicit YAML-input conversion helper;
ordinary report strings are never heuristically parsed as YAML. This supersedes
the proposed separate native-YAML preservation path.

Preserve meaningful data: strings versus numbers and booleans, null versus empty
collections, absent versus present false/zero/null, numeric precision, sequence
order, and upstream redaction. Retain presence and other inspection metadata
where the selected report calls for it. Mapping order, comments, whitespace,
quoting, block/flow style, and exact numeric spelling are not preservation
requirements. Unsupported conversion must remain observable rather than silently
changing meaning. ConfigKit v1.1.0's safe inspection YAML already represents a
restricted, JSON-like value model, making this conversion proportionate.

Obtain those values from upstream safe inspection output, not application runtime
configuration structs: the latter may lose the captured snapshot, field inclusion,
disclosure rules, or inspection evidence. This is an output conversion, not a
replacement for upstream configuration loading or validation. No lossless YAML
document model or second rendering pipeline is needed.

When implementation lands, update the
[current display contract](../cli.md#show-effective-configuration) to replace
native-writer and mapping-order requirements. The aggregate presentation decision
below also replaces separate-document framing. These presentation changes follow
the ownership boundary in [ADR 0006](../adr/0006-invocation-reporting.md); they do
not require a separate successor ADR. Current display behavior remains in force
until the implementation and its canonical contracts change.

This approach reduces new machinery by reusing standard serialization and
centralizing the remaining conversion and rendering work. Exact internal
representation and adapter APIs remain implementation design tasks; a large
public document model is not selected. Validate representative reports before
assuming that an upstream type can be handed off without adaptation.

### Agreed plain-text rendering

**Agreed template boundary:** applications and integrations own the report value
and optional text template. Core prepares and executes templates using Go's
built-in `text/template`, passing the original Go value supplied in the report
handoff. Templates use Go field names, types, and standard template behavior,
not JSON field names or CommandKit's intermediate representation. For example,
a Go field `PromptID` tagged `json:"prompt_id"` is accessed as `.PromptID`.

JSON tags and custom JSON serialization govern structured rendering, not the
template's field access. An exported field tagged `json:"-"` remains accessible
to the application's template, and custom JSON serialization does not replace
the template input. The application owns that text content choice. Core retains
ownership of execution, shared helpers, delivery, and presentation failures.
Prefer reusable templates prepared during setup. Exact preparation and handoff
signatures remain implementation choices; begin with standard template functions
and add shared helpers only for concrete report needs.

When text is selected and a template is supplied, execute it as supplied and
deliver its output without applying a second formatting pass. Template syntax
or execution errors are errors, not a reason to fall back to another renderer.
Use standard `text/template` semantics rather than introducing a new template
language. A template selects text automatically only when the operator omits
`--format`; explicit YAML or JSON takes precedence and does not execute it.

**Agreed text behavior without a template:** use core's logical report
representation to select the following rendering behavior:

- Print strings directly, nonempty sequences containing only strings one item per line,
  and numbers or booleans as their values.
- For mappings, nested or mixed collections, empty collections, and null, reuse
  the shared YAML renderer. Empty sequences use this rule even when their Go
  element type is string, retaining the visible `[]` result.

Automatic selection already chooses YAML for the second group. The additional
case is explicit `--format text` with structured data and no template, such as
`config show --format text`. Text and YAML intentionally coincide in that case.
This retains universal format support without a separate hierarchical text
renderer or pretty-printer. It supersedes the proposed generic text outline.
Applications do not supply separate YAML/JSON writers, and a failing template
never enters this no-template path.

### Agreed aggregate configuration presentation

**Agreed:** `config show --scope all` produces one mapping keyed by the unique
scope identifiers. Each value is that scope's safe effective configuration:

```yaml
app:
  server:
    port: 8080
promptkit:
  backends:
    - id: local
      endpoint: https://example.test/v1
```

The example illustrates the report shape. Scope names sit outside each
configuration's namespace; no `scope` or `config` metadata field is inserted
into the configuration. Keep the scope-keyed mapping even when only one scope
is registered. Single-scope display continues to return the configuration value
directly, without a scope wrapper.

`ckconfig` collects the safe values and hands the complete ordinary Go mapping
to core once. Core renders it using the shared machinery: automatic selection
chooses YAML, explicit JSON renders the same mapping, and explicit text without
a template uses the YAML fallback. No separate-document output or special core
multi-result rendering API is needed. Applications and integrations choose how
to group other reports using ordinary report values.

Scope order has no semantic significance or output-order guarantee in this
aggregate mapping. Retain the existing availability checks and acquisition
behavior: acquire all selected views and complete provider-required validation
before report output begins; a failure prevents the combined display. The new
shape does not introduce partial-success output.

When implementation lands, update the CLI display contract and affected tests
for this aggregate shape. Scope discovery and acquisition ordering are unchanged.
The capability model in [ADR 0003](../adr/0003-configuration-scopes.md) does not
prescribe report framing or mapping order.

### Remaining core reporting implementation details

The [implementation plan](implementation.md) selects public signatures, reusable
template preparation, flag integration/collision handling, and replacement of
existing format plumbing. The decisions above do not reopen content
selection, JSON conventions for core serialization, original Go values for text
templates, no-template text rendering, universal formats, automatic selection,
safe YAML input conversion, aggregate configuration presentation, or joint
format delivery.
Report serialization is separate from the agreed CLI JSON number policy in OD-2,
also adopted for configuration overrides in OD-11.

## Shared core CLI input prerequisites

These two narrow capabilities land with the core reporting prerequisite. They
support the selected integration behavior without adding a collection framework.

### Public CLI JSON parsing boundary

Add a small public CLI JSON parsing entry point to core. It parses one JSON value
using the [OD-2 numeric policy](#od-2-request-controls-and-provider-parameter-grammar)
and returns ordinary Go values. Integrations enforce their flag's outer shape:
provider parameters require an object; configuration assignments accept a JSON
value after their pointer prefix. Keep numeric conversion and its policy comments
in one private helper behind that entry point.

The separate module paths `go.maximumdirect.net/commandkit`,
`go.maximumdirect.net/ckconfig`, and `go.maximumdirect.net/ckprompt` cannot share
core's private `internal` packages. The public CLI parser is the deliberate
cross-module boundary; no public general-purpose numeric conversion API or
separately versioned numeric package is introduced. It must work in independently
built modules, not only in the local workspace. Exact naming is implementation work.

### Ordered typed input composition

Add a small typed binding-composition capability preserving occurrence order
across participating flags. Current `RepeatFlag` and `FlagValues.ApplyTo` group
values by binding, which cannot establish OD-2's text/file winner by command-line
order. Exercise alternating text/file flags and their aliases before finalizing
the core API. Keep parsing, presence, conversion errors, and invocation isolation
in core; integrations choose how ordered typed values form their request.

Do not expose Cobra/pflag structures or reparse raw arguments in `ckprompt`.
Ordinary flag collections and scoped alias declarations keep their existing
APIs. This prerequisite adds only the ordering support those declarations lack.

## Initial report implementation approach

Use ordinary report structs/maps, standard JSON interpretation, the existing
`go.yaml.in/yaml/v4` encoder, and standard `text/template`. Share rendering across
the invocation and writer APIs. Start with built-in template functionality; add
helpers only for demonstrated report needs. No new output module, custom
serialization engine, public document model, or per-format report tree is needed.

Prefer native report values or thin projections. Align YAML-only tags with the
agreed JSON contract where needed. Small path, snapshot, location, and duration
projections serve report meaning; cosmetic field rearrangement does not justify
mirroring entire upstream object graphs. Render inspection values, not engines,
mutable runtime configurations, or credential storage. Preserve selected
presence/redaction distinctions and use the explicit YAML input conversion.

### Output implementation inventory

Core's universal `--format` controls report submissions. All report submissions
accept every core format; handlers retain no format allowlists. Existing raw
output remains an explicit delivery path, not data that core guesses how to
parse or translate. Apply the existing visibility and failure lifecycle to both.

| Output path | Implementation and format boundary |
| --- | --- |
| Core version report | Hand off version data and its ordinary text template to the shared API. |
| `config scopes`, `show`, `sources`, `explain`, and `diff` | Use shared rendering for their report projections; remove local format selection and encoders. OD-4, OD-5, OD-8, and the aggregate-show decision own content. |
| `config validate`, including `--scope all` and `--details` | Submit one report for reached scopes, including failure evidence, under OD-6. |
| Prompt/profile/backend resource inspection | Hand the native inspection results directly to core under [resource inspection](#resource-inspection). |
| Requirements show/validate, catalogs, and prepared preview | Use shared report rendering and suitable thin projections or text templates. |
| Single smoke tests and `promptkit test all` | Preserve native evidence and the aggregate test list in one report submission, including partial results and errors. |
| Maintained application-owned command example | Demonstrate report handoff, optional template, and universal formats without a local format switch. |
| Help and usage | Keep the existing help/usage text path; the report format flag does not serialize help text. |
| Warnings, progress, deferred diagnostics, and terminal failures | Keep existing diagnostic presentation and destinations; report format does not change diagnostic content or channels. |
| Shell-completion scripts/protocol output and caller-selected raw writes | Preserve raw output required by the receiving shell or caller; do not wrap or encode it as a report. |

Audit each listed path during implementation and remove obsolete format bindings and
format-specific helpers. Verify unknown format handling before domain work and
collision handling for the core-owned flag. Report aggregation belongs to each
integration; core does not gain a generic streaming-document framework. Beta
feedback should guide exact layouts; avoid tests that freeze incidental spacing
or field order.

## Implementation plan

The [staged implementation plan](implementation.md) owns ordered steps, selected
API designs, affected code, focused verification, module release handoffs, and
final independent-module validation. This feature roadmap owns target behavior,
operator intent, and the decisions below. Implementation status is recorded in
the plan; the checklist here defines the target acceptance boundaries.

## Validation and completion checklist

Select focused boundary tests under the [testing policy](../policy/testing.md).
The ownership and Go-native policy work is complete in
[architecture.md](../policy/architecture.md#ownership-boundaries). The checks below
cover implementation and its documentation across the staged work; final
release-dependent checks remain pending.
The checklist concerns core reporting and adapter/CLI behavior; it does not ask
CommandKit to retest PromptKit rendering, schema, namespace, or ConfigKit
resolution algorithms.
Default tests remain offline and independent of real credentials.

The linked sections own behavior; these checks cover consequential boundaries
rather than prescribing one test per line or exact cosmetic snapshots.

- [ ] Public report/writer APIs, the CLI JSON parser, and ordered typed input
  composition are documented. Maintained consumers exercise applicable APIs, and
  both integrations build independently. Core has no integration dependency.
- [ ] Universal format selection follows the agreed precedence and logical shapes.
  Cover explicit choices, templates, scalars, empty/nonempty collections, null,
  invalid formats before acquisition, flag collisions, and invocation isolation.
  New formats require no handler changes or local allowlists.
- [ ] JSON interpretation and explicit safe-YAML conversion preserve selected
  field omissions, numeric values, type/presence/null/empty distinctions, sequence
  order, and redaction. Unsupported serialization/conversion remains observable.
  Ordinary strings are not implicitly parsed as YAML; mapping order is not a test
  requirement. Do not substitute runtime configuration for inspection snapshots.
- [ ] Templates receive original Go values and standard template behavior.
  Explicit YAML/JSON does not execute a template; errors never trigger fallback.
  Untemplated text follows the selected scalar/string-list or YAML rules.
- [ ] Invocation and writer APIs share rendering; quiet mode, domain outcomes,
  cause identity, cancellation, and presentation failures retain their agreed
  lifecycle. Changing format does not change selected content or detail level.
  Cover handler-selected submission after cancellation for acquired smoke and
  aggregate-validation evidence, without imposing that behavior on ordinary
  inspection or restarting canceled work.
- [ ] Every path in the [output inventory](#output-implementation-inventory) is
  reviewed. Remove obsolete per-command format plumbing and duplicate encoders;
  preserve explicit raw output, help, and diagnostic boundaries.
- [ ] `config show --scope all` submits the agreed scope-keyed mapping, including
  a one-scope aggregate. Single-scope output remains unwrapped. Cover safe values,
  fields named `scope`/`config`, and failure before combined display.
- [ ] Dependency versions/checksums, attribution, and candidate notes match the
  selected v0.20.0/ConfigKit releases. Canonical docs and examples describe the
  selected contracts without legacy report/API variants or migration guidance.
- [ ] Resource commands pass native prompt/profile/backend reports to core,
  preserving returned message content, field omissions, and explicit
  zero/false/empty values across formats. No per-field report mirror or backend
  completion is added. Help distinguishes resource inspection, preparation,
  credential references, and configuration provenance.
- [ ] Backend inspection is independently optional, wired by `FromEngine`, and
  uses the selected ID, applicable configuration selectors, and backend namespace.
  Help/completion require no acquisition. Preserve native not-found errors,
  cancellation, acquisition diagnostics, and delivery failures. Boundary tests
  establish faithful forwarding and reporting, not upstream resolution rules.
- [ ] Authentication response-limit evidence and smoke preparation errors retain
  native unknown facts, supported causes, and outcomes, including no-report cases.
  Smoke aggregation preserves ordered results and partial failure/cancellation
  evidence in one report. Default tests need no live credentials or model calls.
- [ ] OD-1 preview forwards the request, calls preparation once, and hands native
  `PreparedRun` data to core unless a concrete presentation need warrants a small
  projection. It makes no model call and retains no execution handle. Help explains
  the prompt-ID argument, resource I/O, and rendered-content disclosure.
- [ ] OD-2 collections work in standard and application-owned commands with their
  own typed inputs. Preserve selected subsets, omission/empty/zero values,
  upstream retry defaults, authoritative builders, and native map replacement.
- [ ] CLI JSON parsing follows OD-2 for provider objects and configuration values.
  Cover nested values, integer boundaries, decimal/exponent forms, range errors,
  and ordinary float approximation. The private helper documents the policy and
  its limits; no arbitrary-precision fallback or public numeric framework appears.
- [ ] Canonical flags and scoped aliases follow OD-2; generated aliases cover
  enabled/applicable bindings, preserve presence, and do not claim unrelated
  application spellings. Canonical-only and convenient installation both work.
- [ ] Ordered composition selects the last text/file occurrence for each input
  name, including mixed aliases, while retaining literal empty text and file
  references. Cover reordered/interleaved flags, conversion failures, and fresh
  invocations. No prompt-input flags are added to smoke tests.
- [ ] OD-3 namespace composition and applicability match the native boundary.
  Cover defaults, explicit clearing, qualified IDs, and preservation of unrelated
  defaults/catalog filters. Requirements help explains profile identity; cover
  prompt-default fallback and short explicit profile selection without rewriting
  configured references. Custom scoped loaders remain usable without the option.
- [ ] The six-command configuration suite and optional provider capabilities
  match installed help/completion metadata. Providers supply only enabled
  capabilities; help, version, and capability discovery never trigger acquisition.
- [ ] OD-4 explanation modes, filters, and bare-help behavior distinguish explicit
  root selection, current/historical-only paths, and unavailable metadata.
  Preserve native paths/history; do not assert upstream resolution algorithms.
- [ ] OD-5 concise/detailed diff reuse the same native records and loads. Cover
  additions/deletions, missing versus null, redaction/hidden changes, empty results,
  atomic sequence changes, and delivery failure through the shared renderers.
- [ ] OD-6 validation and failed-load source evidence preserve failure and
  unavailable-versus-empty distinctions. Filters and known duplicate-message
  coordination do not mask outcomes. Aggregate validation submits one document
  with reached-scope evidence after stopping on acquisition failure/cancellation;
  no unvisited scope is reported valid. Test the changed delivery timing and
  separate operation/presentation failures without promising writer rollback.
- [ ] OD-8 focused values and source selection respect capability availability,
  one-scope path selection, absent versus null, unknown IDs, and acquisition
  failure. Filters retain source references without changing validation outcomes.
- [ ] OD-9 comparisons cover left-only, right-only, both/neither, and partially
  specified sides, including repeated values and supplied state. Each side starts
  independently; command-wide controls and the shared-state lifecycle remain
  shared. Explicit-empty application selectors stay application-defined.
- [ ] OD-10 assertion outcomes distinguish equality, changes, usage, and failures;
  concealed changes count. Ordinary diff behavior and nonzero domain outcomes
  survive presentation failure according to the reporting contract.
- [ ] OD-11 parses only the selected assignment syntax, forwards explicit values
  and safe labels to the correct side during loading, and preserves upstream
  errors/provenance. Help documents unsupported `=` paths. No alternate input,
  deduplication, conflict/precedence policy, or altered-value retry is added.
- [ ] Maintained simple/composed consumers demonstrate the new CLI tasks and
  failure workflow with deterministic fixtures. Code remains proportionate:
  thin projections, one shared rendering implementation, and focused tests.
- [ ] Update CLI/API contracts, release notes, and examples with the implementation,
  including report framing, independent comparison selections, and validation
  delivery timing. Keep contracts consistent with architecture policy and replace
  obsolete native-YAML/document-order guidance in testing policy. The ADRs own
  architectural rationale; these presentation and selector changes need no separate
  successor records. Current documentation must match the landed scope.
- [ ] Final independent-module and aligned-workspace suites pass with dependency
  identities recorded. Deferred features remain outside this adoption.

The [implementation plan](implementation.md) owns the concrete verification
sequence and commands. The [development guide](../development.md) and
[release procedure](../release.md) own routine toolchain, workspace, and release
setup. These adoption checks do not add permanent publication gates; a
dependency-only build does not establish the delivered CLI and reporting target.

## Deferred work

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.
The [shared core API](#shared-core-report-output-prerequisite) targets text,
YAML, and JSON, with automatic availability of newly added core formats.
XML is removed from current consideration; Markdown is not selected for this
adoption. The three initial formats land together in the core feature release.
Transient acquisition overrides are included under OD-11.
Output-contract override and appended-message flags are deferred under OD-2
and retained in
[future work](future.md#promptkit-inspection-and-selection-extensions).
Discovery tracing and secrets-directory bootstrap commands remain deferred:
the source inventory is not a trace of rejected search candidates, and bootstrap
performs application startup effects.

## Open Decisions

All numbered decisions are resolved for this adoption and retain their numbers
for reference. OD numbers are local to this roadmap, not the retired adoption
documents. The core prerequisite sections above own shared reporting and input
mechanics. Concrete API signatures, typed binding composition, loader wiring, flag
collision handling, and integration-owned projections are selected in the
[implementation plan](implementation.md), not unresolved product scope. Resource
reports use the native upstream fields selected under [resource inspection](#resource-inspection).

### OD-1: Preview command and report presentation

**Agreed:** use `promptkit show prepared PROMPT_ID` with the native `PreparedRun`
handed directly to core. Its existing JSON serialization fields cover the selected
report content. Introduce a small projection only for a concrete presentation
requirement; do not maintain a parallel report structure merely to copy those
fields. The structured mapping, without a dedicated text
template, selects YAML through core's automatic policy. Universal format choices
and automatic selection supersede both the earlier YAML-only restriction and
the command-specific default proposal. The argument names
the prompt to prepare, not a saved prepared object. A single native preparation
supplies both validation and preview evidence.

The command sits beside [resource inspection](#resource-inspection) and emphasizes
that the report contains resolved settings and rendered content. Use help wording
such as:
"Prepare a prompt request and show the resulting messages and settings without
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. Core's
YAML renderer also supplies explicit `--format 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

**Agreed:** execution flags are public reusable CLI collections owned by
`ckprompt`, available to standard and application-owned commands. Collections
and aliases use existing declarations; JSON parsing and cross-flag ordering use
the [core input prerequisites](#shared-core-cli-input-prerequisites). Give
validation and preview the applicable execution controls already on smoke tests,
and add a singleton `--llm-extra-params JSON` object option to all three.
Use native whole-map replacement, including native behavior for
empty maps. The single-object form is selected over repeated key assignments.

**Agreed CLI JSON number policy:** pass ordinary Go numeric values to PromptKit
and to ConfigKit for the configuration overrides selected in OD-11.
Classify numbers by their written JSON syntax, not by whether their mathematical
value could be an integer:

- Integer syntax (no decimal point or exponent) becomes `int64`. Nonnegative
  values above its range become `uint64` when representable. Reject integers
  outside those ranges with a clear input error; do not fall back to floating point.
- Decimal or exponent syntax becomes `float64`: `42.0` and `1e3` remain floating
  point even though their mathematical values are whole numbers. Accept ordinary
  floating-point approximation; exact decimal representation is not required.
  Report numeric range errors through the existing input-error path.
- Apply the same rules recursively inside JSON objects and arrays, preserving
  other JSON value types. Decode with the standard library's `UseNumber` to avoid
  premature floating-point conversion, then convert the temporary `json.Number`
  values before handing parsed values to either upstream library.

Keep this in one small, centralized internal helper dedicated to CLI JSON input.
Use standard Go numeric parsing; no arbitrary-precision fallback, general-purpose
number conversion package, public numeric conversion API, or extensible numeric
framework is selected. This applies the
[Go types and facilities policy](../policy/architecture.md#go-types-and-facilities)
to these CLI inputs: accept the selected types' precision and range without
alternate numeric representations.

**Required implementation comments:** document the syntax-based type selection,
the `int64`/`uint64`/`float64` choices, accepted floating-point approximation,
range-error behavior, and the rationale for this narrow boundary beside the
helper. The comments must make clear that ordinary Go numeric limits are an
intentional policy, not a missing feature to work around later.

This policy governs parsed CLI provider parameters and configuration override
values, not application-supplied runtime values or core report serialization.
The [public CLI parsing boundary](#public-cli-json-parsing-boundary) shares this
policy across modules while retaining private numeric conversion.
Reusing number conversion does not unify the libraries' different override
semantics or introduce a general-purpose conversion facility.

Retain the authoritative-builder rule: standard flags seed a request, and an
application builder can return its complete replacement. Do not reapply CLI
values after the builder returns.

**Agreed naming and aliases:** use `--llm-` canonical names throughout the
reusable request-control family. Standard `promptkit` commands also accept the
unprefixed convenience spellings wherever the corresponding flag applies.
Application-owned commands receive canonical names from the reusable collections;
applications may deliberately install convenience aliases on their own commands.

| Canonical flag | Convenience alias within applicable `promptkit` commands |
| --- | --- |
| `--llm-endpoint` | `--endpoint` |
| `--llm-model` | `--model` |
| `--llm-temperature` | `--temperature` |
| `--llm-max-tokens` | `--max-tokens` |
| `--llm-top-p` | `--top-p` |
| `--llm-timeout-seconds` | `--timeout-seconds` |
| `--llm-service-tier` | `--service-tier` |
| `--llm-reasoning-effort` | `--reasoning-effort` |
| `--llm-api-key-env` | `--api-key-env` |
| `--llm-transient-retries` | `--transient-retries` |
| `--llm-extra-params` | `--extra-params` |
| `--llm-backend` | `--backend` |
| `--llm-profile` | `--profile` |
| `--llm-prompt` | `--prompt` |
| `--llm-session-id` | `--session-id` |
| `--llm-var` | `--var` |
| `--llm-input-text NAME=TEXT` | `--input-text`, `--llm-input`, `--input` |
| `--llm-input-file NAME=PATH` | `--input-file` |

Retain existing value syntax and units, including integer timeout seconds.
The input naming and content changes are specified below. Commands taking a
positional prompt ID retain that argument; this naming decision does not add a redundant prompt flag. Execution,
resource-selection, and request-input collections may remain separately
composable. Namespace controls remain subject to OD-3.

**Agreed assembly approach:** keep alias generation in `ckprompt`; alias
assembly requires no core upgrade. Define each flag-to-alias relationship once
and generate existing `FlagAliasFor` routing declarations from the flags selected
for each enabled canonical command. Do not maintain a separate hand-written matrix of
all command/flag combinations. Aliases target the original flag binding rather
than introducing duplicate bindings. Both spellings retain core parsing,
presence, and occurrence-order behavior.

Offer a convenient collection containing the command family and its scoped
routing declarations, using existing `[]commandkit.Declaration` installation.
Keep `ckprompt.Command(suite)` available for canonical commands without the
convenience aliases. Exact helper names remain implementation choices. Generate
aliases only for enabled commands and applicable flags; do not install
application-wide aliases or make consumers reproduce the command/flag matrix.
Applications can install selected aliases on their own commands through the
existing core API. Subtree alias scopes and a new core declaration-bundle type
are not part of this adoption.

Help should identify canonical names and their applicable aliases using current
core presentation. Update implementation, examples, help, and documentation
together. Canonical-only installation does not supply convenience aliases.

**Agreed input forms:** include literal text alongside file input for
`promptkit requirements validate` and `promptkit show prepared`. The concrete
operator task is preparing one selected prompt with a short, disposable sample
without creating a fixture file. File inputs remain useful for substantial
content and repeatable artifacts. These operations make no model call and do
not establish model-output quality or application-workflow success. Assess
usefulness within these standard commands; speculative applicability to
multi-prompt application workflows is not a reason to add flags.

Use the explicit canonical pair `--llm-input-text NAME=TEXT` and
`--llm-input-file NAME=PATH`. The scoped aliases in the table include both
`--input` and `--llm-input` for literal text. They route to the original text
binding with the same parsing, presence, and occurrence-order behavior.
`--input` denotes literal text; file bindings use the explicit file form.
Do not infer file access from literal content that resembles a path.

Provide repeatable named bindings, splitting at the first `=` and preserving
literal content, including explicit empty text, through native `Inline` inputs.
File bindings continue to use native `File` references. Keep the canonical
forms available through reusable request-input collections; application commands
choose whether these bindings fit their workflow and may opt into aliases.
None of these aliases is application-wide by default. Do not add prompt-input
flags to smoke tests, which use their own diagnostic content.

**Agreed input precedence:** the last command-line occurrence for a given input
name wins across text and file bindings, including every alias. Implementation
must preserve actual occurrence order rather than applying one flag collection
after the other in a fixed order. Use the core
[ordered typed input composition](#ordered-typed-input-composition) prerequisite;
independent flag binding alone does not supply this behavior.

**Deferred output-contract overrides:** no CLI override is included in this
adoption. Retain the candidate in
[future work](future.md#promptkit-inspection-and-selection-extensions);
existing configuration and application builders remain available.

**Deferred appended-message flags:** no CLI message-appending option is included
in this adoption. The potential standard-command task is reproducing a request
with application-added messages for preparation validation or preview. Revisit
when that is a demonstrated operator requirement; ordinary named inputs remain
available for inspecting prompt definitions with concrete content. Retain the
candidate in [future work](future.md#promptkit-inspection-and-selection-extensions).
No message-file format, flag syntax, or role-selection interface is selected.
Native application-supplied appended messages remain part of prepared-request
inspection; deferring flags does not remove that report evidence. No
general-purpose request-building API follows from these CLI choices.

### OD-3: Namespace flags and loader defaults

**Agreed:** make the standard namespace selectors opt-in with explicit
application-supplied defaults for prompts, profiles, and backends in the suite.
`ckprompt` combines those defaults with the supplied CLI fields, then applies
one native `WithNamespaces` call. Loaders using this option leave namespace
default selection to that adapter rather than relying on hidden engine-view
state. Without the option, applications control namespace selection in their
loaders.

Omitting a selector preserves its declared default. Supplying a namespace
replaces that default for the invocation; supplying an explicitly empty value
clears it. Each resource type is independent. For example, overriding the
prompt namespace must preserve the declared profile and backend defaults.
Qualified resource IDs pass through unchanged. Catalog namespace filters remain
separate from these resource-resolution defaults.

The standard option owns composition instead of requiring an application
callback to merge every selection. Applications needing custom namespace
selection can retain their own loading behavior without enabling the option.

**Agreed names:**

| Canonical selector | Scoped alias within applicable `promptkit` commands |
| --- | --- |
| `--llm-prompt-namespace` | `--prompt-namespace` |
| `--llm-profile-namespace` | `--profile-namespace` |
| `--llm-backend-namespace` | `--backend-namespace` |

**Agreed applicability:** install only namespace selectors used by the operation
when the application enables the standard namespace option.

| Operation | Resource-resolution namespace selectors |
| --- | --- |
| `promptkit show prompt` | Prompt |
| `promptkit show profile` | Profile |
| `promptkit show backend` | Backend |
| `promptkit requirements show` | Prompt and profile |
| `promptkit requirements validate` | Prompt, profile, and backend |
| `promptkit show prepared` | Prompt, profile, and backend |
| `promptkit test KIND`, including `all` | Prompt, profile, and backend |
| Resource catalogs | None; retain existing namespace filters |
| Configuration inspection | None; configuration inspection remains global within the selected configuration scope |

Verify this table against the native calls during implementation. Do not install
a selector for symmetry when an operation cannot use it. Exact public helper
signatures remain implementation choices.

**Agreed requirements-inspection behavior:** retain optional profile selection
and the profile namespace selector. In released PromptKit v0.20.0, requirements
inspection selects and verifies a profile identity, using the explicit profile
or the prompt's default, and includes that identity in the report. It fails when
neither supplies a profile or the selected profile does not exist. The profile
need not be execution-ready or have working credentials.

The selected profile does not change the discovered prompt inputs or variables;
analysis uses the captured prompt templates, supplied variables, and session
context. Help must explain that profile selection establishes the reported
identity, not a different set of prompt requirements. The profile namespace
qualifies explicitly supplied short profile IDs; it does not rewrite the prompt's
configured default reference. Preserve this released upstream behavior without
adding a CommandKit workaround for profile-independent requirements inspection.

### OD-4: Configuration path and metadata presentation

**Agreed placement:** path discovery is part of `config explain`; no separate
path or metadata command will be added in this roadmap.

**Agreed mode selection:** bare `config explain` displays command help as a
successful help request. Help explains that an operation requires either
`--list` to discover paths or `--path POINTER` to explain a selected path. This
makes both capabilities visible instead of implicitly choosing discovery.

- Neither mode selected: show help, with success on successful help delivery.
- `--list` selected: discover configuration paths.
- `--path` supplied: explain that path.
- Both modes selected: report a usage error.

Track path presence separately from its value: explicit `--path ""` selects
the root explanation, not help. This deliberately replaces the current
missing-path usage error; automatic discovery on a bare invocation is not
selected.

**Agreed initial presentation:** supply a compact text discovery template, which
core selects automatically when no format is requested. Explicit alternatives
use core's universal `--format`. Operate on one scope at a time.
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.

Use `--under POINTER` to narrow listing to a subtree and
`--explicit=true|false` to select current explicitness. Omitting explicitness
filtering includes both states and, when requested, historical-only entries;
historical-only entries do not match either current explicitness value. Apply
subtree filtering to parsed paths, not textual prefixes. These filters and
`--historical` belong to listing mode; `--path` continues to select detailed
explanation, including its available metadata and history.

Keep values and change history out of the compact listing. Include useful field
metadata in detailed explanation without repeating existing evidence. If a
provider cannot supply discovery metadata, report that capability as unavailable
rather than presenting an empty configuration; its existing path-specific
explanation remains usable. These are sufficient starting choices for the MVP;
exact field layout and mode-specific error wording can be decided in code and
reviewed with concrete examples.

### OD-5: Detailed comparison selection and shape

**Agreed:** retain the existing concise additions/changes/deletions report as
the default for `config diff`, and add optional `--details` for investigating
changes. The default serves human operators who need a quick overview.

The detailed mode should help an operator compare old and new values,
distinguish absence from explicit null, and understand concealed changes even
when the displayed safe snapshots look equal. Present native paths, left/right
snapshots, presence, redaction, and hidden-change evidence in readable YAML.

**Agreed initial layout:** one entry per changed path in a scope-labeled YAML
report, with before/after snapshots rather than expanded versions of the three
summary categories. Display snapshot values as YAML values, preserving explicit
presence so missing and null remain distinct. Show redaction and concealed-change
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. Both concise and detailed comparison
hand off structured mappings without a text template; core's automatic policy
selects YAML. Universal format choices supersede the earlier YAML-only detailed
restriction. The same selected comparison evidence is handed to core in every
format; explicit text without a template reuses core's YAML renderer.

Keep the projection close to native report values, using the
[shared reporting approach](#initial-report-implementation-approach) rather than
extensive translation for cosmetic layout. Exact field names are implementation
choices for the initial release and can evolve with beta feedback.

Keep implementation localized to detail selection and a report projection,
with focused boundary tests, help, and examples. The existing `Scope.Compare`
contract and both native adapters already return the required difference
records. Reuse that data and existing safe-snapshot decoding; no new comparison
callback, additional load, or comparison algorithm is required. Use the shared
core report output capability; detailed comparison needs no domain-specific core
API. A side-by-side terminal display is not part of this adoption. Comparison
exit status follows OD-10.

### OD-6: Failure evidence and structured diagnostic delivery

**Agreed placement:** structured configuration diagnostics are part of
`config validate`; there will be no separate diagnostics command. Source
inventory on failure remains part of `config sources`.

**Agreed:** add `config validate --details`, consistent with the optional detail
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. Changing the output format
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`
reports acquired source inventory. These describe the current invocation, not a
previous failed command. Keep the original failure and its supported cause
identity; successfully displaying evidence must not turn failure into success.
A failed load does not imply an effective configuration is available.

Build optional `ckconfig` evidence facets that can accompany an acquisition
error. Unlike detailed comparison, the existing adapters need to carry additional
structured evidence through to reporting. Use current core reporting and outcome
handling; no generic cross-family diagnostics framework is required.

**Agreed initial presentation:** supply a detailed validation text template,
which core selects automatically unless the operator requests another format.
The template begins with scope and outcome, then shows readable findings with their available
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
within a filter match any selected value; different filters narrow results
together. Filtering never changes the validation outcome. Distinguish no native
findings, no findings matching the filters, and unavailable structured evidence.
Keep referenced sources needed to interpret selected findings.

Avoid presenting a finding both in the detailed report and as a duplicate
ordinary warning when the records have a known relationship. Do not deduplicate
by guessing from message text. Preserve unrelated messages and the terminal
failure explanation. Keep this coordination within the integration rather than
introducing a general diagnostics framework.

Structured results use the result stream and ordinary messages use the
diagnostic stream. Preserve report-delivery failures separately from the original
operation failure through existing outcome handling.

**Agreed aggregate delivery:** for `config validate --scope all`, collect results
for the scopes reached and submit one report after acquisition completes or
stops. Stop at the first acquisition failure or cancellation; retain completed-scope
results and available evidence from the failing scope. Do not claim unvisited scopes
were validated. Apply the same aggregation to concise and detailed modes, using
one ordinary report value and the shared renderers, including one JSON document.

The validation handler submits that acquired evidence even when cancellation
stopped acquisition, following the
[shared reporting cancellation boundary](#agreed-format-independent-reporting-operation).
Do not reuse an ordinary inspection helper's cancellation guard to suppress this
report. Preserve the cancellation outcome alongside any presentation failure.

This deliberately changes delivery timing: scope results are no longer written
one at a time during acquisition. Output failures are observed after acquisition
has stopped and cannot prevent already-completed loads. Preserve the original
operation failure and separate presentation failure under the existing outcome
rules. This replaces the old output-failure stopping behavior; it does not add
exhaustive validation, whole-invocation buffering, or writer rollback. Diagnostics
retain their existing lifecycle. Update the canonical validation contract and
its focused failure tests when this lands.

### OD-7: Module release and interim workspace coordination

**Agreed:** complete the core reporting/input prerequisites and planned
integration work together in the selected feature delivery.
Prepare the core release supplying those APIs, then a new ckconfig minor
release for the shared API/CLI features, and update the still-unpublished
ckprompt candidate. Both integrations must require a core version supplying the
new API, and ckprompt must require the ckconfig version supplying the shared
work. Confirm candidate status and available versions under the release
procedure before choosing versions.

Use the ignored aligned workspace during joint development. Workspace success
does not establish independent integration correctness with old core or ckconfig
requirements. Before final independent validation, pin released dependency
versions supplying the APIs and validate all three independent modules and the
aligned workspace. Dependency release order is core, ckconfig, then ckprompt.
Publication remains a separate action requiring authorization; this decision
does not authorize publication.

### OD-8: Focused configuration reports and filtering

**Agreed:** add `config show --path POINTER` and
`config sources --source-id ID`; add subtree/explicitness filters to
`config explain --list` and severity/code filters to `config validate --details`.
Keep reports unfiltered by default. The purpose is to reduce noise for a human
operator investigating a known part of the configuration.

`config show` hands off the selected logical configuration value without a text
template. Core selects from its shape: a mapping yields YAML, while a selected
string yields text. Explicit `--format yaml` renders the safe effective value as
YAML, without a snapshot wrapper containing presence/redaction/YAML fields or a
promise to preserve upstream formatting or mapping order.
All formats render the selected value through the shared representation.
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` uses the agreed [scope-keyed mapping](#agreed-aggregate-configuration-presentation).

Filters change presentation, not validation outcomes. Keep source references
needed to interpret the selected findings. Apply subtree filtering to parsed
paths; distinguish unavailable current metadata on historical-only paths from
an effective value that was not explicitly supplied.

**Selected filter grammar:** OD-4 records discovery filters and OD-6 records
diagnostic filters. Exact report field layout and remaining edge-case messages
are implementation choices for the MVP. No additional snapshot-wrapper report
or aggregate path-selected display is selected for this adoption.

### OD-9: Independent comparison selector bindings

**Agreed comparison model:** initialize the left and right sides independently
from the configuration the application ordinarily loads without CLI configuration
selections or overrides. Ordinary loading retains application discovery, files,
defaults, environment handling, and resolution; it does not mean an empty or
defaults-only configuration.

Apply each side's explicitly supplied values only to that side:

- `--config`, `--overlay`, application configuration selectors, and `--set`
  affect the left side.
- Their declared `--against-*` counterparts affect the right side.
- Every omitted field retains that side's ordinary application default and
  unsupplied state. Never copy the opposite side's value or supplied state,
  even when other fields on the right are explicitly supplied.
- Repeatable selectors follow their declared typed binding behavior on their
  own side. Left-side elements are never copied into the right collection.
- Command-wide controls such as `--scope`, `--format`, `--details`, and `--check`
  govern the comparison as a whole and remain outside this separation.

| Invocation after `app config diff` | Left selection | Right selection |
| --- | --- | --- |
| `--config candidate.yml` | `candidate.yml` | Ordinary configuration |
| `--config before.yml --against-config after.yml` | `before.yml` | `after.yml` |
| `--config base.yml --against-overlay experimental` | `base.yml` | Ordinary configuration with the selected overlay |
| `--config base.yml --against-config base.yml --against-overlay experimental` | `base.yml` | `base.yml` with the selected overlay |
| `--against-config candidate.yml` | Ordinary configuration | `candidate.yml` |
| No side-specific flags | Ordinary configuration | Ordinary configuration |

The examples retain normal application interpretation of file and overlay
selectors. Explicitly selecting the same nondefault input on both sides requires
supplying it on both sides. Equal selections remain allowed and do not skip
acquisition or comparison.

Applications declare which domain selectors support right-side values, with
explicit metadata for their `--against-*` spellings. Do not generate comparison
flags for every application option automatically. A configuration selector
without a right-side binding still affects only the left when supplied; it is
not implicitly shared. Domain parsing stays in declared typed bindings; no
generic selector language is introduced. Retain the two input preparations and
checks, one shared invocation state, and existing provider lifecycle.

This deliberately replaces the current inheritance model, including existing
config/overlay behavior and shared application selectors. Update CLI/API contracts
and examples when implementation lands. The input/state ownership in
[ADR 0001](../adr/0001-command-dispatch-and-inputs.md) remains unchanged; selector
policy does not need a separate successor ADR. Exact helper signatures and flag
collision handling remain implementation design tasks.

**Agreed collection scope:** leave explicit-empty selection for application-defined
repeatable selectors to application-declared bindings in this release. Omission
retains that side's ordinary collection; an empty string element is not implicitly
an empty collection. No additional standard collection-clearing flags, including
the earlier proposed `--against-clear-*` forms, are selected.

Actual configuration lists supported by OD-11 can be replaced with an empty list
using `--set /path=[]` or `--against-set /path=[]` on the corresponding side,
subject to upstream path and schema rules. This does not necessarily express
empty selection for an application selector that controls which sources load.
Retain general collection-clearing support as a
[future candidate](future.md#comparison-extensions) pending a concrete consumer
need. OD-9 requires no further operator-policy decision for this adoption.

### OD-10: Comparison assertion outcomes

**Agreed:** add opt-in `--check`, retaining normal report delivery and ordinary
diff behavior when omitted. Under assertion mode, use status `0` for equality,
`3` for differences, `2` for usage errors, and `1` for operational failures.
This distinguishes a successful comparison that found differences from a
comparison that could not run. Ordinary diff remains successful when it finds
differences.

Base the difference outcome on native records, including concealed changes,
not equality of the displayed safe values. Apply existing reporting outcome
rules, including preservation of a nonzero domain outcome when presentation
also fails; callers can inspect the separate presentation evidence. Document
and test that interaction explicitly. These are selected future behaviors,
not claims about the currently implemented CLI.

### OD-11: Transient configuration overrides

**Agreed scope:** include a declared, opt-in override capability for standard
configuration commands, with repeatable `--set POINTER=JSON` values passed to
application acquisition as native ConfigKit overrides. This enables validation,
inspection, and comparison of temporary settings through consistent CLI syntax.
Providers that do not accept overrides retain their existing operations. No
source file is edited, and no general application-internal convenience API is
required. Supply parsed records during the normal configuration load, like any
other explicitly supplied CLI overrides; the generic adapter cannot inject
them into an arbitrary loader after the load has completed.

**Agreed input syntax:** support only `POINTER=JSON`, split at the first `=`.
Paths containing `=` are unsupported by `--set` and `--against-set`. Document
this limitation in help; do not add alternate JSON-record syntax, an escaping
scheme, or an override-file option. This limits these flags rather than banning
such keys elsewhere in configuration. The JSON value may itself contain `=`.

**Agreed loading boundary:** CommandKit parses supplied assignments, preserves
explicit values and safe source labels, and passes the records to the appropriate
loader and comparison side. ConfigKit owns path validity, duplicate/overlap
handling, precedence, resolution, and validation. If the normal load returns a
ConfigKit error, preserve and report it through the existing diagnostic/outcome
path. CommandKit does not deduplicate records, resolve conflicts, invent a
combination or precedence policy for application-owned overrides, or retry with
altered values. Application loading retains its existing responsibilities.
Exact loader signatures and wiring remain implementation design tasks.

**Agreed numeric conversion:** both assignment flags use the
[OD-2 numeric policy](#od-2-request-controls-and-provider-parameter-grammar),
including nested values, through core's public CLI JSON parser. ConfigKit receives
ordinary Go values; the shared numeric helper and policy comments remain private.

**Agreed comparison behavior:** `--set` supplies override records only to the
left side; `--against-set` supplies records only to the right. Each side starts
from its ordinary configuration under OD-9. Omission supplies no CLI override
records for that side; it never inherits records from the other side. Normal
application-owned overrides are part of ordinary loading and are not erased by
omitting these flags.

For example, `config diff --set /workers=4` compares the left configuration with
that override against the ordinary right configuration. Adding
`--against-set /workers=8` explicitly overrides the right configuration as well.
Repeat the same `--set` assignments as `--against-set` assignments when both
sides should use them. There is no shared CLI override baseline and no
`--against-clear-set` flag is needed to undo inheritance.

Implement the selected handoff without reimplementing upstream behavior:

- Split at the first `=`; JSON supplies typed null, boolean, string, numeric,
  array, and object values, with the agreed numeric policy above.
- Forward explicit records only, with safe display labels such as `--set`,
  never raw value-bearing arguments as provenance labels. Preserve native
  duplicate/overlap handling rather than silently collapsing assignments.
- Let ConfigKit enforce its released mapping-path constraints, including
  root/index and schema-version restrictions, without introducing a generic
  patch language. Empty, false, zero, and null remain intentional supplied values.
- Reflect native CLI origins and subsequent resolution in existing reports.
  Test CommandKit parsing, forwarding, and outcome/report adaptation, leaving
  ConfigKit's override algorithm to its own tests.

Application-specific typed flags remain available, but are not a substitute for
the selected standard CLI capability. No persistent configuration mutation is
authorized by this decision. OD-11 requires no further operator-policy decision
for this adoption.