commandkit/docs/adr/0004-standard-inspection-surface.md

# ADR 0004: Define standard inspection operations by family and capability

## Status

Proposed

## Date

2026-10-06

## Context

CommandKit serves applications with shared ConfigKit and PromptKit inspection
needs. A defined operator surface establishes the infrastructure CommandKit
provides. Different integrations expose different resources and inspection
capabilities, while shared verbs benefit from consistent meanings.

[ADR 0001](0001-command-dispatch-and-inputs.md) establishes dispatch, registration,
capability-based installation, and the boundary of CommandKit policy. The remaining
decisions are the operator questions the initial standard answers.

## Decision

CommandKit supplies help and version reporting and defines ConfitKit and
PromptKit inspection operations. Each family defines its own supported set of
operations. Registration installs handlers for the capabilities supplied by the
integration and exposes their availability through help and discovery metadata.

| Standard operation | Responsibility |
| --- | --- |
| `help` | Describe registered standard and application commands. |
| `version` | Report application version by default; report embedded CommandKit version when explicitly selected. |
| `config scopes` | List registered configuration scopes and supported operations. |
| `config validate` | Validate the selected configuration and its configured definitions. |
| `config show` | Display final effective configuration. |
| `config sources` | Describe the acquired and synthetic input source inventory. |
| `config explain` | Explain effective or historical values and provenance at a selected path. |
| `config diff` | Compare effective configuration selections semantically. |

The optional PromptKit suite supplies `promptkit list prompts`,
`promptkit list profiles`, `promptkit show prompt`, and `promptkit show profile`.
These operations expose captured definition catalogs, prompt metadata, and
backend-completed named execution targets. PromptKit definition capabilities and
its configuration scope are registered according to their available provider
operations. Either can be integrated independently.

CommandKit assembles each installed family from its declared capabilities, keeping
standard handlers and metadata together. The inventory describes available
standard operations; adoption can use the supported subset. Semantic diff depends
on safe comparison snapshots for its selected scope. Its availability is
independent of display, validation, and other inspection capabilities.

Shared verbs keep consistent purposes: `list` enumerates resources, `show`
displays a selected resource, and `diff` compares supported representations. Each
family specializes those purposes for its own resources. For example, a future
FeedKit family could supply `list` and `show` as its intended operation set.

`app version` and root `app --version` report application version. The version
command defaults to `--scope app`; `app version --scope commandkit` reports the
embedded CommandKit release version. `--format` selects presentation of the same
subject. Future component identities can use registered version metadata. Version
subjects are independent of configuration scopes and loading providers.

CommandKit owns vocabulary and observable contracts within its standard families.
Custom execution, rendering, serving, sessions, and artifact workflows retain
their application-owned meanings. Additional shared operations enter through
versioned CommandKit releases under the
[release policy](../policy/release.md#versioning-and-compatibility).

The CLI reference owns exact flags, operands, defaults, and report schemas when
implemented. This record owns operation purposes and capability-based availability.

## Alternatives considered

| Alternative | Analysis |
| --- | --- |
| Initial operations limited to validation and display | Accelerates first integrations. Source explanation, comparison, and discovery remain repeated application infrastructure. |
| Require every operation for every integration | Gives a uniform inventory. One unavailable capability blocks other useful operations and future resource families. |
| Definition inspection through configuration operations alone | Source values and provenance share one path. Captured catalogs and completed execution targets require additional interpretation. |
| Standardize execution and mutation alongside inspection | Expands shared vocabulary to more workflows. Additional domain and state-management contracts require their own evidence and design. |
| Display dependency identities in ordinary application version output | Makes dependency information immediately visible. Application identity becomes coupled to dependency reporting. |
| A combined dependency-version option | Gives a useful diagnostic inventory. Scoped version reporting also supports selecting one identity. |

## Consequences

CommandKit supplies shared handlers with predictable meanings and discovers their
availability from registration. Each enabled operation needs its own data
contract: comparison needs safe snapshots, catalogs need enumeration, and profile
display needs safe execution-target inspection.

Shared operations retain clear purposes. CommandKit release notes describe changes
to its published operations. Coordinated application documentation and caller
updates are recommended migration practices.

Help and discovery describe actual supported capabilities. The
[scope model](0009-configuration-scopes.md),
[inspection lifecycle](0008-inspection-lifecycle.md), and
[comparison policy](0011-semantic-configuration-diff.md) describe the proposed
provider and behavioral contracts supporting this surface.