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

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

## Status

Accepted.

## 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.

## Decision

CommandKit supplies help and version reporting and defines ConfigKit 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.

Adoption can use the supported subset under
[ADR 0001](0001-command-dispatch-and-inputs.md). Missing comparison or catalog
capabilities leave other inspection operations available.

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.

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.

The [CLI reference](../cli.md) owns exact flags, operands, defaults, and report
schemas for implemented operations.

## 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. |

## 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.

The [scope model](0009-configuration-scopes.md) and
[comparison policy](0008-semantic-configuration-diff.md) describe related
capability and behavioral decisions.