Record config explain modes and default help behavior

docs/roadmap/future.md

@@ -57,7 +57,8 @@ now includes the shared operator tasks previously retained here: metadata/path
 discovery and explicitness, failed-load source inventory, detailed comparison,
 and structured diagnostics. Path discovery is a mode of `config explain`, and
 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,
 source-ID selection, metadata/diagnostic filters, independent comparison
 selectors, and assertion mode. The original four shared proposals had ConfigKit

docs/roadmap/promptkit-v0.19.0.md

@@ -110,9 +110,10 @@ in the decisions at the end of this document.
 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. Mode flags such as `--list` and `--diagnostics`, report shapes, and
-filter spellings remain proposals under OD-4, OD-6, and OD-8. No separate path
-inventory or diagnostics subcommand is planned.
+is agreed. OD-4 selects `--list` and `--path` as the explanation modes, with
+help on a bare invocation. Diagnostic mode flags, report shapes, and filter
+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
 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
   discovery and validation diagnostics are modes of existing commands, with
   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
   historical paths, retains available history on absent lookup, and projects
   native field/change records.
@@ -613,20 +617,28 @@ agreement on default composition.
 **Agreed placement:** path discovery is part of `config explain`; no separate
 path or metadata command will be added in this roadmap.
 
-**Recommendation:** add an explicit discovery mode such as
-`config explain --list`, with effective paths by default, optional historical
-selection, and subtree/explicitness filters. Keep `config explain --path POINTER` for detailed
-explanation, including optional field metadata. This retains the current
-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.
+**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.
 
-**Alternative:** make omission of `--path` select discovery automatically, while
-supplying it selects detailed explanation. This reduces flags and gives bare
-explanation a useful behavior, but deliberately changes today's missing-path
-error and can make an accidentally omitted path harder to notice. Both designs
-keep discovery and detailed history together in one command.
+- 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.
+
+**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