Record the documentation refresh roadmap

docs/development.md

@@ -62,6 +62,7 @@ capability proposals in [future work](roadmap/future.md).
 | Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0002](adr/0002-public-facade-and-cli-backend.md), [ADR 0004](adr/0004-optional-integration-modules.md), and the architecture policy |
 | Module ownership and public contracts | [Consumer guide](consumers/guide.md), [internal overview](internal/overview.md), [core GoDoc](../doc.go), [ckconfig GoDoc](../integrations/ckconfig/doc.go), [ckprompt GoDoc](../integrations/ckprompt/doc.go), and applicable ADRs |
 | Unfinished work and capability proposals | [Future work](roadmap/future.md) |
+| Documentation refresh sprint | [Documentation roadmap](roadmap/documentation-refresh.md) |
 | Completed planning and implementation history | [Completed dependency upgrades, PromptKit validation, discovery, smoke testing, and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/a6278a6d9f940948ec7745955d745523aaff0734/docs/roadmap), [earlier ConfigKit and PromptKit adoption and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/8a82620dfcd34c0ae56bbecb0d014eb49786bc92/docs/roadmap), [earlier retired records](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap), and [completed module implementation and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/bb2528532b78d30e52f5082e491a5e1fd9b0fb99/docs/roadmap) in Git history |
 | Release tooling | [Maintainer release procedure](release.md) |
 | Performance maintenance | [Internal overview](internal/overview.md), existing benchmarks, and [possible further efficiency work](roadmap/future.md#possible-further-efficiency-work) |

docs/roadmap/documentation-refresh.md

@@ -0,0 +1,214 @@
+# Documentation refresh
+
+Status: agreed scope; ready for implementation planning. The refresh has not
+been implemented.
+
+## Purpose
+
+Refresh CommandKit's documentation for the next minor release. Operators should
+be able to find a command, understand what it does, and interpret its results
+without learning the implementation. Application developers should have a short
+path from choosing a module to using its public API. Maintainer documentation
+and exact API contracts can retain technical detail where it is useful.
+
+This roadmap captures the accepted documentation review recommendations. The
+[documentation policy](../policy/documentation.md) remains authoritative for
+audience, canonical ownership, examples, and document lifecycle. No new policy,
+documentation framework, or ADR is needed.
+
+## Scope and boundaries
+
+The sprint covers current READMEs, the CLI reference, consumer guidance,
+maintained example instructions, generated help descriptions, package
+introductions, and release notes being prepared for publication.
+
+Preserve API and CLI behavior: command and flag names, defaults, format
+selection, report fields, status semantics, availability, and ownership rules.
+Source edits for help text and GoDoc are in scope; runtime refactoring and new
+features are not. If review exposes a behavioral defect or an unresolved
+contract, record it separately rather than silently changing behavior through
+an editorial revision.
+
+Use existing documentation owners. Move useful detail to its appropriate owner
+or link to the existing explanation; do not duplicate contracts. Keep exact
+ownership, callback lifetime, error identity, and concurrency rules in GoDoc.
+Internal documentation and maintainer procedures need only changes justified by
+clarity or affected navigation, not a wholesale simplification.
+
+Preserve accepted ADR decisions, historical published release records, license
+texts, and attribution. Apply release-note editing to unpublished candidates
+after checking their publication status under the
+[release policy](../policy/release.md). Dependency alignment and publication
+remain separate work under the [release procedure](../release.md).
+
+## Audience and writing approach
+
+| Audience | Starting points | Approach |
+| --- | --- | --- |
+| Prospective users | Root and integration READMEs | Explain purpose, useful capabilities, and where to start. |
+| CLI operators | CLI reference and generated help | Lead with tasks, commands, results, and relevant limitations. |
+| Go application developers | Consumer guide, examples, package introductions | Show a small useful integration first; explain choices and responsibilities next. |
+| API users and maintainers | Symbol GoDoc, internal docs, development and release guides | Retain precise technical detail needed for correct use and maintenance. |
+
+Use short, direct sentences and familiar terms. Define necessary domain terms
+where first used; avoid a separate glossary unless one proves useful. For
+example, explain a configuration scope as a named configuration such as `app`
+or `promptkit`.
+
+Where meaning permits, prefer “load configuration” to “acquire configuration,”
+“command output” to “substantive results,” and “files and other sources used to
+load configuration” to “source inventory captured during acquisition.” These
+are editorial examples, not a mechanical replacement list. Keep technical names
+when referring to an API symbol or a distinction that matters to the reader.
+
+## Work areas
+
+### 1. Product and module introductions
+
+Update the [root README](../../README.md), [ckconfig README](../../integrations/ckconfig/README.md),
+and [ckprompt README](../../integrations/ckprompt/README.md).
+
+- Explain what the library helps applications and operators do before describing
+  declarations, adapters, or reporting internals.
+- Keep the module overview, explicit installation distinction, and navigation.
+  Link to the consumer guide for compatibility and integration details.
+- Provide the shortest useful starting example or a direct link to it, rather
+  than a catalog of callback counts or implementation responsibilities.
+
+An illustrative root opening is: “CommandKit helps Go applications build
+consistent command-line interfaces. It provides typed flags and arguments,
+help, output formatting, and error reporting. Optional integrations add commands
+for inspecting configuration and working with PromptKit.” Final wording can
+evolve during implementation.
+
+### 2. CLI tasks and reference detail
+
+Refresh the [CLI reference](../cli.md), particularly reporting, configuration,
+prepared-request preview, requirements, and smoke testing.
+
+- Begin each operation with its purpose and a small command example. Explain
+  results and important limitations before detailed report fields.
+- Replace installation and callback introductions with an operator explanation
+  of command availability; link to the consumer guide for application wiring.
+- Move API-only material such as callback construction, writer ownership, and
+  `Outcome.Presentation` access to its existing developer-facing owner where
+  appropriate. Retain observable output, failure, and status behavior here.
+- Organize detailed report shapes and edge cases into reference subsections so
+  they remain available without interrupting the ordinary task.
+- Make application-defined flags and optional convenience aliases identifiable;
+  examples must not imply every application installs them.
+
+Retain distinctions operators need: omission versus an explicit empty value,
+concise versus detailed reports, independent comparison sides, redaction,
+partial evidence on failure, and which operations can contact providers.
+Explain that requirements discovery, request validation, prepared preview, and
+smoke testing answer different questions. Successful preparation does not
+guarantee later execution, and a smoke command's successful status does not
+mean every reported observation is positive.
+
+### 3. Guided examples
+
+Refresh the [core example](../../examples/core/README.md),
+[ConfigKit example](../../integrations/ckconfig/examples/simple/README.md), and
+[composed example](../../integrations/ckprompt/examples/composed/README.md).
+
+- State the working directory, required Go version, and applicable workspace or
+  independent-module setup before commands.
+- Start with a few useful commands and explain expected results beside them.
+  Group additional examples by task rather than presenting one long command block.
+- Label intentional failures beside the relevant command, including how to
+  interpret the result. Distinguish application status from `go run`'s own exit
+  behavior when explaining shell results.
+- Explain early that the composed example uses local fixtures and requires no
+  model service or credentials; do not imply this about every consuming app.
+- Put alias wiring, shared state, and cache explanations after the walkthrough,
+  linking to API contracts rather than repeating them.
+
+### 4. Consumer guide and public API orientation
+
+Update the [consumer guide](../consumers/guide.md) and the package introductions
+in [core](../../doc.go), [ckconfig](../../integrations/ckconfig/doc.go), and
+[ckprompt](../../integrations/ckprompt/doc.go).
+
+- Demonstrate `Reporter.Report` with a small value so the recommended path to
+  shared `--format` support is visible. Explain raw output as a separate choice.
+- Make the initial greeting example's name, description, and output agree; it
+  currently prints the count rather than a greeting.
+- Present module compatibility in a compact table that distinguishes published
+  releases from current source requirements. Keep exact version guidance in
+  this owner and link from module introductions.
+- Lead package introductions with purpose and primary entry points. Keep exact
+  symbol contracts in GoDoc, including factory timing, supplied values, error
+  handling, and object ownership.
+
+Recheck compatibility statements when implementing the refresh. Current source
+and released dependencies can differ; the
+[pending alignment work](future.md#pending-release-and-integration-work) owns
+the outstanding release work. Do not present workspace success as proof that
+the selected published dependencies support an independent build.
+
+### 5. Generated help
+
+Review command summaries, descriptions, flag usage, and argument usage across
+core and both integrations. These strings are operator documentation even when
+stored in Go source.
+
+Use action-oriented descriptions and explain choices where useful. In
+particular, the [smoke command](../../integrations/ckprompt/smoke_command.go)
+should explain that it can run one test or all tests and identify accepted kinds;
+“Run one PromptKit smoke test” and “Native smoke-test kind” are insufficient.
+The [request flag descriptions](../../integrations/ckprompt/request_flags.go)
+can use direct wording such as “Use this model.” Preserve flag names, grammar,
+defaults, and supported operations.
+
+### 6. Release notes
+
+Review the [core v0.5.0 note](../releases/v0.5.0.md) and applicable unpublished
+integration candidates for the upcoming releases. Explain user benefits before
+implementation mechanisms: accepted deferred messages are no longer lost,
+YAML values retain their intended types, and installation and help avoid repeated
+work. Remove unnecessary discussion of scratch paths, chain suffixes, and batch
+detachment from the release summary.
+
+Retain compatibility guidance, required consumer actions, meaningful API names,
+and license/attribution links. Verify candidate dependencies against the versions
+actually selected for publication. Do not invent release dates or performance
+guarantees, or revise published historical notes as part of this refresh.
+
+## Suggested sprint sequence
+
+1. Refresh README introductions and the CLI reference together to establish
+   vocabulary and the operator/developer split.
+2. Update example walkthroughs and generated help to match that language.
+3. Polish consumer guidance, package introductions, and candidate release notes.
+4. Review the changed documentation together for consistency and validate the
+   affected examples, help, and navigation.
+
+No unresolved product decision blocks implementation planning. Exact wording,
+section placement, and illustrative examples are ordinary editorial choices.
+
+## Validation and completion checklist
+
+Use the existing [documentation checks](../development.md#documentation-validation)
+and [testing policy](../policy/testing.md). Review prose and local links; run
+affected maintained examples and inspect representative help when those change.
+For Go example or help-source edits, run the relevant existing package tests.
+Do not add wording snapshots, readability gates, or a new checker framework.
+Record workspace and independent-module results separately, including any
+dependency limitation. This work adds no release gates.
+
+- [ ] README openings explain purpose and give a clear starting path.
+- [ ] CLI sections explain operator tasks before reference detail; necessary
+  behavior, report fields, status rules, and limitations remain discoverable.
+- [ ] Example setup is explicit, commands have nearby explanations, and intended
+  failures are labeled.
+- [ ] Consumer guidance demonstrates formatted reporting, has a coherent initial
+  example, and distinguishes published compatibility from current source needs.
+- [ ] Package introductions and generated help use clear, accurate language;
+  precise API contracts remain intact.
+- [ ] Unpublished release notes explain benefits and consumer impact while
+  historical records and required notices remain preserved.
+- [ ] Changed commands, snippets, and help have appropriate verification; local
+  links and Markdown whitespace checks pass.
+- [ ] Final review confirms consistent terminology, canonical ownership, and no
+  unintended behavior or contract changes.

docs/roadmap/future.md

@@ -1,7 +1,7 @@
 # Future work
 
-Status: pending release/dependency alignment, optional shell validation, and
-future capability proposals.
+Status: documentation refresh, pending release/dependency alignment, optional
+shell validation, and future capability proposals.
 No delivery dates are selected here.
 
 ## Purpose and authority
@@ -30,6 +30,13 @@ an idea here does not select its syntax, API, priority, or delivery date.
 
 ## Pending release and integration work
 
+### Documentation refresh
+
+The agreed [documentation roadmap](documentation-refresh.md) owns the upcoming
+clarity refresh, its scope, sequence, and completion checklist. The work covers
+operator instructions and public introductions while retaining necessary
+technical detail in developer documentation.
+
 ### Audit remediation release alignment
 
 The audit remediation is complete in source. The released ckconfig v0.4.0 does