configkit/docs/roadmap/documentation.md

# Documentation Consistency Audit

Reviewed revision: `b4477a236aa01e60c17ee353bccaebca7ce919d7`.

This audit compares current documentation with the implementation, maintained
examples, tests, and architectural decisions. It records proposed corrections;
it does not change the public contract or implement the corrections.

## 1. Discovery reference names a removed public constructor

**Status:** Complete. The discovery introduction now names `SearchPaths`.

**Documentation:** [Configuration discovery](../config.md#configuration-discovery),
line 34, tells consumers to construct a search from literal `Paths`.

**Discrepancy:** The public constructor is now `SearchPaths`, declared in
[discovery.go](../../discovery.go), lines 55–56. There is no public `Paths`
compatibility alias. The private engine retains that name, but consumers cannot
use it through the supported public package. The same reference section already
uses `SearchPaths()` when explaining empty searches, and the
[migration table](../consumers/README.md#pre-v1-public-api-cleanup) correctly
records the rename.

**Impact:** A consumer following the introductory instruction can attempt to call
an unavailable public API. This is a documentation defect, not a missing API.

**Potential remediation:** Change the introductory constructor name to
`SearchPaths`. Preserve the historical old-name entry in the migration table and
the private engine name; neither needs changing for this finding.

## 2. Four focused-test instructions are truncated in rendered documentation

**Status:** Complete. All four rows now escape their regex pipes consistently
with adjacent rows. Rendered commands retain ordinary regex alternation.

**Documentation:** The [development test map](../development.md#task-to-test-map),
lines 276, 277, 283, and 290, contains these affected rows:

- Explicit main-file discovery and absent-input loading.
- Import defaults, empty-selection evidence, and dependency-ready ordering.
- Input and relative-import destinations, mounted sources, and source ownership.
- Effective configuration diff.

**Discrepancy:** These rows put unescaped regex alternation pipes inside inline
code in Markdown table cells. GitHub-flavored Markdown treats those pipes as cell
separators even inside backticks. The table has three columns, so the remainder of
each instruction falls outside the displayed command cell. For example, the
discovery command renders as the incomplete text
`` `go test ./internal/engine -run 'Discovery `` rather than the complete command
and its two companion commands.

The intended Go regexes are valid: `|` separates alternatives. Rendering the
current guide with the already module-selected Goldmark v2.1.6 GFM parser and
renderer reproduced all four truncated cells. Neighboring older rows escape
their pipes and render complete commands. Existing tests referenced by these
instructions run successfully in the complete suite; their implementation is
not the problem.

**Impact:** Readers of the rendered contributor guide lose the complete test
selection instructions and can copy an unterminated shell command. The existing
documentation-link check does not validate rendered table cells.

**Potential remediation:** Escape the table pipes consistently with adjacent
rows, or move the affected commands into fenced blocks outside the table. Inspect
the rendered result and execute the resulting shell commands with ordinary regex
alternation. Markdown escaping should not introduce literal escaped pipes into
the command users copy. No new release gate or production change is needed.

## Review Coverage and Validation

Reviewed the root README and package/API documentation, the configuration
reference, consumer guide and executable examples, development instructions,
internal component/import documentation, and release procedure against their
corresponding implementation and tests. Checked module identity, declared Go and
ReleaseKit versions, release-profile wiring, and licensing/attribution navigation.
No additional actionable discrepancy was identified in those areas. This was not
an upstream licensing review or an attempted release.

Historical release notes, dated extraction records, superseded ADR decisions,
explicitly proposed ADRs, migration tables, and deferred roadmap candidates were
treated according to their stated status. Their historical terminology and
proposed behavior are not findings merely because current behavior differs.

Validation used Go 1.26.10 with local toolchain selection and dependency downloads
disabled:

```sh
GOTOOLCHAIN=local GOPROXY=off go test ./... -count=1
GOTOOLCHAIN=local GOPROXY=off go test . -run 'TestLocalDocumentationLinks|TestDependencyImportBoundary|TestPublicFacadeBoundary|^Example' -count=1
```

Both passed, including maintained consumer examples. An external disposable GFM
rendering probe substantiated finding 2. No production code, existing tests,
current documentation contracts, release tags, or consumer dependencies were
changed during the audit.

Remediation validation: all 13 commands in the four corrected rows render in
full, with ordinary regex alternation. All 11 distinct rendered commands passed,
as did the local documentation-link check and whitespace review.