base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Record config explain modes and default help behavior

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-06 18:27:39 +00:00
parent 9076cb2c9c
commit 61bcd80171
2 changed files with 30 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/roadmap/future.md
View File

@@ -57,7 +57,8 @@ now includes the shared operator tasks previously retained here: metadata/path
discovery and explicitness, failed-load source inventory, detailed comparison, discovery and explicitness, failed-load source inventory, detailed comparison,
and structured diagnostics. Path discovery is a mode of `config explain`, and and structured diagnostics. Path discovery is a mode of `config explain`, and
structured diagnostics belong to `config validate`; the suite retains six structured diagnostics belong to `config validate`; the suite retains six
subcommands. Their exact mode flags and report shapes remain open in the roadmap. subcommands. The roadmap records the agreed explanation modes and help behavior;
diagnostic mode spelling, report shapes, and filters remain open.
It also includes focused effective display, It also includes focused effective display,
source-ID selection, metadata/diagnostic filters, independent comparison source-ID selection, metadata/diagnostic filters, independent comparison
selectors, and assertion mode. The original four shared proposals had ConfigKit selectors, and assertion mode. The original four shared proposals had ConfigKit

44
docs/roadmap/promptkit-v0.19.0.md
View File

@@ -110,9 +110,10 @@ in the decisions at the end of this document.
The configuration suite retains six subcommands: `scopes`, `validate`, `show`, The configuration suite retains six subcommands: `scopes`, `validate`, `show`,
`sources`, `explain`, and `diff`. Path discovery belongs within `config explain`; `sources`, `explain`, and `diff`. Path discovery belongs within `config explain`;
structured diagnostics belong within `config validate`. This command placement structured diagnostics belong within `config validate`. This command placement
is agreed. Mode flags such as `--list` and `--diagnostics`, report shapes, and is agreed. OD-4 selects `--list` and `--path` as the explanation modes, with
filter spellings remain proposals under OD-4, OD-6, and OD-8. No separate path help on a bare invocation. Diagnostic mode flags, report shapes, and filter
inventory or diagnostics subcommand is planned. spellings remain proposals under OD-4, OD-6, and OD-8. No separate path inventory
or diagnostics subcommand is planned.
Transient configuration overrides are an open scope decision under OD-11, with Transient configuration overrides are an open scope decision under OD-11, with
a recommendation to include them as an optional loader capability. Illustrative a recommendation to include them as an optional loader capability. Illustrative
@@ -375,6 +376,9 @@ Default tests remain offline and independent of real credentials.
- [ ] The full configuration suite retains six subcommands. Explanation - [ ] The full configuration suite retains six subcommands. Explanation
discovery and validation diagnostics are modes of existing commands, with discovery and validation diagnostics are modes of existing commands, with
capability-aware help and selected mode/flag combination checks. capability-aware help and selected mode/flag combination checks.
- [ ] Bare `config explain` displays help successfully, presenting `--list` and
`--path` as the two alternatives. Selecting both modes is a usage error;
explicitly supplied `--path ""` selects root explanation rather than help.
- [ ] Metadata discovery through `config explain` distinguishes effective and - [ ] Metadata discovery through `config explain` distinguishes effective and
historical paths, retains available history on absent lookup, and projects historical paths, retains available history on absent lookup, and projects
native field/change records. native field/change records.
@@ -613,20 +617,28 @@ agreement on default composition.
**Agreed placement:** path discovery is part of `config explain`; no separate **Agreed placement:** path discovery is part of `config explain`; no separate
path or metadata command will be added in this roadmap. path or metadata command will be added in this roadmap.
**Recommendation:** add an explicit discovery mode such as **Agreed mode selection:** bare `config explain` displays command help as a
`config explain --list`, with effective paths by default, optional historical successful help request. Help explains that an operation requires either
selection, and subtree/explicitness filters. Keep `config explain --path POINTER` for detailed `--list` to discover paths or `--path POINTER` to explain a selected path. This
explanation, including optional field metadata. This retains the current makes both capabilities visible instead of implicitly choosing discovery.
missing-path usage error outside discovery mode and makes the operator's intent
clear. Use the current single-scope model. Define mode combinations, formats,
and unavailable metadata handling before implementation; exact flag spellings
remain open.
**Alternative:** make omission of `--path` select discovery automatically, while - Neither mode selected: show help, with success on successful help delivery.
supplying it selects detailed explanation. This reduces flags and gives bare - `--list` selected: discover configuration paths.
explanation a useful behavior, but deliberately changes today's missing-path - `--path` supplied: explain that path.
error and can make an accidentally omitted path harder to notice. Both designs - Both modes selected: report a usage error.
keep discovery and detailed history together in one command.
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.
**Remaining presentation recommendations:** list effective paths by default,
offer optional historical selection and subtree/explicitness filters, and
include available field metadata in detailed explanation. Use the current
single-scope model. A compact text discovery report with YAML available for
scripts is recommended. Define report fields, historical/filter spellings,
mode-specific option combinations, and unavailable metadata handling before
implementation; these details remain open.
### OD-5: Detailed comparison selection and shape ### OD-5: Detailed comparison selection and shape