configkit/docs/roadmap/documentation.md

User and Operator Documentation Readability Review

Reviewed revision: 08bb3a20c6a565646d98f68688d268c7bae39573.

Status: complete. All D01–D18 revisions have been applied and reviewed together for consistency. The catalog below preserves the proposals that guided the work; the completion record identifies their implemented locations. The previous consistency audit remains in Git history; its two findings were corrected in 94d1e33.

Completion record

Proposal	Implemented result
D01	README leads with the loading outcome and minimal example, followed by optional tasks and platform/licensing links.
D02	Consumer guide starts with task routes, defaults, validation, and inspection; example background and the test inventory follow usage.
D03	Reference introduction supplies topic routes, YAML illustrations, path definitions, and common-versus-detailed subheadings.
D04	Sources, results, and resource lifetime explain copying, reuse, saved inspection, and caller-owned resources.
D05	Priority, strict combination, and defaults have visible examples and retain collection exceptions.
D06	Discovery shows the four attempted paths and distinguishes optional absence, required absence, and selected-file failure.
D07	Imports introduce the three selectors, option applicability, requiredness, ordering, and earlier syntax separately.
D08	Placement illustrates files and assembled YAML; contexts explain later resource access and ownership.
D09	Identified lists show replace, append, and whole-record upsert before registration and policy-lifetime details.
D10	Inheritance starts with parent/child settings, then cancellation and identified records before exact scheduling rules.
D11	Versions introduce application acceptance, a mode table, mounted headers, and the limits of observed evidence.
D12	Callbacks have task and helper tables, a derived-default example, and entry-state/lifetime guidance.
D13	Secrets separate lookup, hiding, and bootstrap; bootstrap explains empty existing variables and partial reports.
D14	Inspection starts with reader needs and a default/main/overlay example; diffs explain snapshot flags and hidden changes.
D15	YAML, defaults, projection, and failures have practical examples; descriptor caching moved to the internal overview.
D16	Package documentation and the targeted public declarations explain purpose, paths, returned copies, and saved state while retaining precise contracts.
D17	Migration guidance leads with numbered consumer actions and explains package type identity alongside the retained old/new table.
D18	Release procedure defines operational terms and explains Go selection, publication statuses, and tag-object recovery without changing command blocks or gates.

Audience and Scope

ConfigKit is a library. Developers integrating its public API are its users; they need different documentation from contributors maintaining the engine. Configuration authors may know YAML without knowing Go reflection or graph algorithms. Release maintainers are the audience for its operational runbook. ConfigKit has no standalone application CLI or application deployment procedure to explain.

Material	Primary readers	Treatment in this review
Root README	People evaluating or starting with ConfigKit	Explain outcomes and direct readers to a useful next page.
Consumer guide	Application developers adopting or upgrading ConfigKit	Explain tasks and examples before advanced terminology.
Configuration reference	Configuration authors and API users checking exact rules	Add context while keeping precise contracts available.
Package documentation and public declaration comments	Users browsing the Go API	Explain practical effects alongside symbol names and conditions.
Release procedure	Maintainers publishing or recovering a release	Clarify operational language while preserving the workflow.
Release history	Users considering an upgrade	Preserve historical records. Future notes can lead with user impact and required action.
Attribution, COPYRIGHT, and license texts	Users checking rights and notices	Preserve formal notices and license language; no rewrite proposed.
Development guide, internal docs, ADRs, policies, and roadmaps	Repository contributors and decision reviewers	Outside the main rewrite scope; retain links for implementation and rationale.

The adopted policies should not acquire local wording changes solely for this exercise. Accepted ADR decisions and historical release records retain their established treatment under the documentation policy.

Editorial Direction

Introduce each topic through the reader's task or the observable result. Explain unfamiliar terms where they become useful. More words are appropriate when they supply the background needed to understand a rule.

Follow introductory explanations with precise reference material. Retain names readers will encounter in Go and YAML, and explain them rather than inventing new API terminology. Use small illustrations beside the explanation and link to maintained files for complete runnable examples. Initially, improve the existing pages rather than introducing a new documentation tree.

These are contextual explanations, not global replacement instructions:

Existing term	Useful explanation on first use
Mapping / sequence / scalar	A YAML group of named values / a list / a single value such as a string or number.
Precedence	Which input takes priority when different layers supply a setting.
Provenance / origin	Where a value came from, including application processing that changed it.
Explicit presence	Whether input supplied a setting, even when its value is false, 0, empty, or null.
Detached record	A returned copy whose mutation cannot change ConfigKit's stored record. Explain borrowed filesystem ownership separately.
Frozen snapshot	The saved configuration state that inspection continues to describe after loading.
Source-local coordinates	Paths within one input document, before its destination is added.
Canonical projection	A consistent representation of typed values used for comparison or inspection; introduce its relevant effect before the internal term.
Dependency-ready order	Process a contribution after its dependencies are ready, using the documented tie-break rule when several are ready.

Catalog of Proposed Revisions

The identifiers below name proposals, not implementation stages. High priority means a proposal helps readers understand a common or foundational task. Medium priority addresses a specialized task or reference detail.

D01 — Introduce ConfigKit through its useful outcomes

Target: README introduction. Priority: High.

The feature inventory precedes the minimal example and introduces "snapshotted mappings," "detached metadata," "audited defaulting," and "source/derivation history" in quick succession.

Lead with what the application receives and what its author supplies. Suggested direction: "ConfigKit loads YAML into your application's Go configuration type, combines the inputs you choose, and lets you inspect where the final values came from." Bring the existing minimal example forward. Follow it with short capability summaries and links, introducing optional features when readers select them. Keep platform and licensing navigation easy to find. Detailed scheduling and ADR links can follow the consumer-oriented navigation.

D02 — Make the consumer guide a route through common tasks

Target: Consumer introduction and entry-point selection, the example-shape table, and Happy path. Priority: High.

The guide begins with a long responsibility inventory and examples named after other applications. Its happy-path snippet immediately presents imports, overlays, overrides, and a predeclared rules value.

Offer a short task index: load one file, supply defaults and validation, add bundled lower-priority settings, select an overlay, and inspect a result. Point the simplest case to the README example, then introduce additional options as needed. Describe examples by their demonstrated task before their original application names. Move extraction background and test-owner inventories below usage guidance. Preserve links to maintained examples.

D03 — Give the reference useful starting points

Target: Configuration reference introduction. Priority: High.

The opening says the document "owns" contracts and describes private parser boundaries. The page mixes basic input selection with advanced lifecycle and inspection details across a long reference.

Introduce it as the reference for accepted YAML, input combination, and loading behavior. Add a compact topic index with routes for configuration authors and Go API users. Introduce mappings, lists, layers, and configuration paths with small illustrations. Separate common behavior, advanced interactions, and limits through subheadings within the existing document. Keep detailed rules available after their introductions; a separate general-purpose glossary is unnecessary initially.

D04 — Explain source selection and ownership in practical terms

Target: Sources, single-source loading, and resource lifetime. Priority: High.

"Opaque source," "consumption," "claimed once," "defensive source list," and "publication copy" put implementation vocabulary ahead of caller actions.

Introduce sources as inputs passed to Load. Explain which are copied immediately, which are read again on each load, and why a Reader source is single-use. Keep the constructor table and explain who closes each resource. Introduce the result before explaining copying mechanics. Suggested wording: "You can change Result.Config after loading. Inspection methods continue to describe the configuration as it was when the load finished." Preserve the separate rule that borrowed filesystems remain under caller control and later resource reads observe those filesystems.

D05 — Teach combination rules with visible input and output

Target: README philosophy, layered loading, strict composition, and defaults. Priority: High.

Readers encounter "tier," "strict peers," "recursive precedence," and "typed baseline" before seeing a combined configuration. Priority order and processing order are also easy to confuse.

Use a small mapping example to show independent same-tier contributions and an intentional higher-layer change. Explain same-tier conflicts. Show a priority diagram separately from the processing timeline, explaining why defaults have low priority while being applied during decoding. Keep the README summary brief and link to full reference rules. Add a defaults example distinguishing omission, explicit false/zero, an empty list, and null where the Go field permits it. Keep collection exceptions visible; avoid a blanket "last file wins" explanation.

D06 — Describe discovery as an ordered search

Target: Configuration discovery and consumer discovery guidance. Priority: High.

"Directory-first Cartesian product," "ordered concatenation," and "optional exhaustion" require translation into actual attempted filenames.

Show two directories and two filenames as an ordered list of candidates. Explain that ConfigKit finishes the filenames for one directory before moving to the next. Explain no-match behavior, required searches, and selected-file failure. Keep the terminal selected-file error rule prominent so readers understand why a bad selected file does not cause another search. Follow with the existing preset table and specialized filesystem-context rules.

D07 — Introduce imports through the three selection tasks

Target: Explicit imports and import defaults guidance. Priority: High.

The opening combines enablement, structural controls, selector shapes, requiredness, destinations, removed syntax, and diagnostic codes. Later passages refer to "namespace-path lexical order" and "scoped assembly order."

Start with including a named file, searching a directory, and matching a path pattern. Use small YAML illustrations and link to complete examples. Explain shared options in a selector-applicability table. Separate optional missing inputs from unreadable or invalid inputs. Explain that required path lists check each named target, while required directory/glob searches need a selected file; retain the empty path: [] case. Explain observed ordering with a short dependency example before its exact reference rules. Move legacy migration notes below the first explanation of current syntax.

D08 — Separate configuration placement from filesystem paths

Target: Input destinations, resource contexts, and mounted collection guidance. Priority: High.

"Effective destination," "projected through that item," "nearest resolved enclosing collection container," and "passive resource context" are difficult without a picture of the configuration and the files on disk.

Show a tiny file tree beside a resulting YAML shape. Explain that a destination chooses where settings appear, while an import filename resolves from its declaring file. Walk through opening one resource: follow its value's source ID to SourceContext, join BaseDir, and close the file the application opens. Introduce fallback destination evidence after exact placement. Preserve composite-origin ambiguity, caller-owned resource lifetimes, and the distinction between saved configuration and later resource I/O.

D09 — Explain collection identity and operations before policy lifetime

Target: Collection rules and identified sequence guidance. Priority: High.

Selectors, normalized field sets, type-tagged tuples, registrations, and retained policy appear before the operation table. Readers who want to combine a list of named records need substantial background first.

Start with a record list and an id field. Show before/after results for replace, append, and upsert, including an upsert whose omitted lower fields disappear during source assembly. Explain duplicate rejection within a strict tier. Next introduce YAML declarations and Go registrations, including their different final-validation guarantees. Label compound identity, exact numeric equality, wildcard selectors, pending declarations, and record-owned policy as advanced reference material. Preserve the existing operation and presence tables.

D10 — Introduce inheritance with a parent and child

Target: Sibling inheritance and consumer inheritance guidance. Priority: Medium.

The opening quickly moves from named siblings to identified records, root restrictions, cancellation, and dependency scheduling.

Begin with a small base/custom mapping example and show the resulting child. Explain "sibling" as another entry in the same enclosing mapping. Explain that inheritance uses the settings remaining after source combination. Add cancellation and identified-record examples next, followed by exact ordering. Retain destination-local nested resolution, identity-field ownership, cycle/missing-parent errors, and ordinary validation of parent records.

D11 — Explain version checking as application-defined acceptance

Target: Application versions, shared checks, and consumer version guidance. Priority: Medium.

"Accepted non-main declarations are consumed from their owned payload" and "destination-prefixed application path" combine several concepts in one sentence.

Explain first that the application chooses the version field and supported identifiers. Add a behavior table for the three modes, distinguishing missing main headers, missing other headers, explicit null, and NoSource. Use a mounted document example to separate checking a header inside a file from protecting its assembled path. Explain that accepted non-main headers are removed before combination. Preserve the distinctions between observing a declaration, running a checker, and acceptance, including disclosure limits on VersionEvidence.

D12 — Explain callbacks through the application's work

Target: Recorded resolution, semantic validation, and consumer task guidance. Priority: High.

"Audited net resolution operations," "helper-assigned values," "covering record," and "post-decode entry state" obscure when to use each callback.

Introduce fixed defaults, deriving or normalizing values in Resolve, and checking rules in Validate as separate tasks. Compare Default, Normalize, and the two Record* methods, identifying which assign values. Explain that EntryInfo describes callback-entry state even after the resolver changes values. Use a small derived-value example to explain recording and dependencies. State callback lifetime and read-only validation rules directly. Retain panic, error-reporting, and helper-writeback behavior in the detailed reference.

D13 — Separate secret references, hiding output, and file bootstrap

Target: Typed references, classification/rendering, and file bootstrap. Priority: High.

"Credential-bearing fields," "sensitivity closure," "preflight/apply," and "existing empty winner" demand familiarity with several different mechanisms.

Explain the YAML environment-variable name, the credential read during loading, and the separate choice to hide a configuration field in inspection. Make clear that reference names are visible unless separately classified. Explain the optional helper as reading files into environment variables before a later load, with a filename/name/value illustration using dummy data. Explain skipped_existing with the already-set-but-empty case, then show how to read a partial report. Preserve partial writes, lack of rollback, lookup timing, application-owned safe messages, and visibility limits. Keep exact byte/name limits in their reference paragraphs or tables.

D14 — Explain inspection through the information readers need

Target: Metadata, explanations, diffs, and their consumer examples. Priority: High.

"Canonical typed projection," "decoding reconciliation," and "cross-protected context" are demanding introductions to inspecting a setting.

Organize the introduction around the final value, its source, its earlier definitions, and changes between two loads. Walk through a setting with a default, supplied value, and later override. Distinguish metadata history from value explanations. Explain Present, Redacted, and HiddenChanged with a small table and hidden-change example. Keep source-versus-typed representation details, atomic list comparisons, combined sensitivity, and unchanged-reference credential rotation. Clarify which outputs contain values and which contain attribution only.

D15 — Lead YAML and Go type rules with authoring examples

Target: YAML documents, scalars, schema binding, decoding, projection/ownership, and safe failures. Priority: Medium.

"Private reflection descriptor graph," "paired text scalars," and "recursive acyclic objects" precede common authoring needs. Safe failures explains classifications before showing how to use a report.

Start with a YAML/Go field pairing and everyday examples: quote yes to use it as text, write durations as strings, and use supported lowercase booleans. Retain the scalar/defaults tables. Explain nil versus empty containers, ignored fields, and omitempty through visible results. Put codec method sets and recursive-type rules in advanced reference material. Explain diagnostic code, configuration path, and source location with a small safe report and a link to maintained error handling. Retain exact limits and error behavior. Move purely internal caching or tree-storage explanations to existing internal docs where useful, preserving all observable ownership guarantees.

D16 — Make Go API comments understandable on their own

Target: doc.go, public declarations in lifecycle.go, path.go, records.go, inspection.go, and diff.go. Priority: Medium.

The package comment is chiefly a feature inventory. Resolution introduces "entry-state input provenance"; Difference introduces a "canonical changed region"; several result comments rely on "detached" without explaining its effect.

Give major types an action-oriented first sentence followed by their precise contracts. Illustrate configuration paths with a key/index example, and explain returned-copy and saved-state behavior where relevant. Keep symbol-specific errors, nil/zero behavior, ownership, and lifetime rules beside declarations. Link to shared YAML semantics and maintained examples rather than repeating the full configuration reference. Preserve public names and Go doc conventions.

D17 — Turn migration prose into recognizable consumer actions

Target: Migration changes, module-path migration, and API cleanup. Priority: Medium.

The old/new symbol table is useful, but "serialized diagnostic/provenance expectations" and "migration evidence" assume repository history and advanced Go package knowledge.

Lead with actions: update requirements and imports together, replace listed old symbols, and review any stored or compared layer/code strings. Explain distinct Go type identity through another dependency passing ConfigKit values to the application. Retain the old/new table, historical-tag limitations, and the difference between API and YAML changes. Keep downstream migration-status caveats in a short background note. Do not choose a release version or claim that another application has migrated.

D18 — Make the release runbook easier to follow and recover from

Target: Release procedure, especially Go selection, publication status, and recovery. Priority: Medium.

"Module-selected native executable," "consumer minimum," "bounded authoritative reconciliation," and "peeled commit" require substantial release-tool knowledge.

Explain a candidate as the committed revision intended for release, the consumer minimum as the oldest supported Go version, and the selected tool as the ReleaseKit version recorded in go.mod. Use the existing Go patch example to distinguish validation toolchain from consumer minimum. Keep command blocks intact unless a separately verified wording change needs an accompanying adjustment. Put exit statuses and next actions in a compact table. Explain why the tag-object ID matters before asking the operator to compare it. Keep recovery's exact URL, candidate, and tag identity conditions together.

Preserve pushing the candidate before publishing the tag, publication authorization, immutable published tags, a single publication command, and optional consumer verification. Keep CI waiting and macOS validation outside the release gates. Plain language must not turn uncertain publication into permission to retry, delete a published tag, or declare success.

Priorities and Review Boundaries

The highest-impact starting points are the README and consumer entry routes (D01–D03), combination/presence explanations (D05), and secret/inspection guidance (D13–D14). The other proposals develop a selected task or reference topic. These priorities are editorial recommendations, not additional release gates.

These revisions preserve existing contracts, diagnostic identifiers, defaults, limits, security boundaries, and exceptions. Keep precise material available after its plain-language introduction. A simpler explanation must not imply universal last-value replacement, universal null support, transactional loading, refreshed inspection after caller mutation, or stronger filesystem isolation.

Implementation changes consumer-facing prose and Go declaration comments, with the relocated descriptor-caching explanation in the existing internal overview. Policies, accepted ADRs, release history, license notices, dependencies, and production behavior remain unchanged. Validation includes exercising the revised illustrations against the library, checking local links and Markdown tables, comparing Go tokens to confirm comment-only edits, and verifying that release command blocks remain identical to the implementation baseline e74c26a.

Completed validation with Go 1.26.10 and dependency downloads disabled:

• ./scripts/check.sh passed formatting, whitespace, all tests (including local links and executable examples), vet, and build.
• Temporary programs outside the repository exercised the revised README, callbacks, YAML, discovery, imports, collection operations, placement, inheritance, version modes, inspection, secret bootstrap, defaults, and projection illustrations against the current library; all passed.
• A Go scanner comparison confirmed identical non-comment tokens in all six changed Go files. All 12 release command blocks are byte-for-byte unchanged.
• The six affected Markdown pages rendered successfully with the project's Markdown parser; all 27 tables have consistent column counts. Existing navigation anchors remain available.

The final consistency pass checked terminology, worked results, public comments, cross-page links, documentation ownership, and the preserved release workflow.