commandkit/docs/roadmap/documentation-refresh.md

# Documentation refresh

Status: implemented and verified. Release/dependency alignment remains separate
work in [future.md](future.md#pending-release-and-integration-work).

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

- [x] README openings explain purpose and give a clear starting path.
- [x] CLI sections explain operator tasks before reference detail; necessary
  behavior, report fields, status rules, and limitations remain discoverable.
- [x] Example setup is explicit, commands have nearby explanations, and intended
  failures are labeled.
- [x] Consumer guidance demonstrates formatted reporting, has a coherent initial
  example, and distinguishes published compatibility from current source needs.
- [x] Package introductions and generated help use clear, accurate language;
  precise API contracts remain intact.
- [x] Unpublished release notes explain benefits and consumer impact while
  historical records and required notices remain preserved.
- [x] Changed commands, snippets, and help have appropriate verification; local
  links and Markdown whitespace checks pass.
- [x] Final review confirms consistent terminology, canonical ownership, and no
  unintended behavior or contract changes.

## Implementation and verification

Completed the six work areas above. READMEs and package introductions now lead
with purpose and starting points; the CLI reference separates operator tasks
from report detail and developer wiring. Examples are grouped by task with
setup, expected results, and intentional failures explained nearby. The consumer
guide demonstrates shared report formatting and distinguishes published modules
from current source. Help strings and unpublished candidate notes use the same
plain language. Exact symbol contracts and runtime behavior were preserved.

Verification used Go 1.27.0 and existing cached dependencies:

- The aligned workspace suites passed for core, ckconfig, and ckprompt, including
  their maintained examples.
- Independent core and ckconfig suites passed with `GOWORK=off`.
- Independent ckprompt compilation confirmed the existing dependency limitation:
  released ckconfig v0.4.0 lacks `AdaptDiagnostics`. No module requirements,
  checksums, or workspace files were changed to hide it. Its README, example,
  consumer guidance, and candidate note identify the pending alignment.
- All 48 `go run` invocations in the three example READMEs were exercised with
  binaries built from the aligned workspace, from the documented directories.
  Results matched the walkthroughs, including two failed-load examples, missing
  request input, and comparison status 3. Shared help and completion behavior
  also passed the existing suites; representative rendered help was inspected.
- Both new consumer-guide report snippets compiled in a temporary consumer using
  local core. Six checks confirmed greeting counts, empty-list output, and YAML
  and JSON formatting.
- Local Markdown links, including incoming links to renamed sections, and
  whitespace were checked. Go source changes are limited to help strings,
  package comments, and formatting; no new tests or validation framework were
  added.
- The authoritative remote had neither the core v0.5.0 nor ckprompt v0.3.0 tag
  when their candidate notes were revised. Published notes, accepted ADRs,
  policies, and license/attribution records were left intact.

The updated ckprompt candidate still requires dependency guidance to be finalized
when release alignment occurs. This is release preparation, not unfinished
editorial work or evidence of an independently buildable candidate.