commandkit/docs/roadmap/documentation-refresh.md

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 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. Dependency alignment and publication remain separate work under the release procedure.

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, ckconfig README, and ckprompt README.

• 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, 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, ConfigKit example, and composed example.

• 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 and the package introductions in core, ckconfig, and ckprompt.

• 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 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 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 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 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 and testing policy. 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.