Complete documentation reconciliation and final review

docs/cli.md

@@ -149,9 +149,10 @@ order, with a `# scope: NAME` comment at each document boundary. For ordinary
 block documents the comment follows the marker. When a native opening marker
 contains inline content, the comment precedes that marker so it does not
 interrupt the native value. Existing native markers and leading comments are
-retained; documents without a marker receive one. Scope labels containing line control characters are quoted to keep them on
+retained; documents without a marker receive one. Scope labels containing line
-one comment line. A provider failure leaves the output stream empty. A rendering
+control characters are quoted to keep them on one comment line. A provider
-or output failure may leave an aggregate prefix, and the outcome reports
+failure leaves the output stream empty. A rendering or output failure may leave
+an aggregate prefix, and the outcome reports
 incomplete report delivery.
 
 ### List configuration sources
@@ -230,12 +231,12 @@ serialized as `[]`.
 ## PromptKit definition inspection
 
 Applications can install prompt and profile inspection independently with
-`RegisterPromptKit`. Each installed handler invokes its registered inspection
+`RegisterPromptKit`. When acquisition is reached, the handler invokes its
-callback once with the caller's selection and context. The bundled
+registered inspection callback once with the caller's selection and context.
-`NewPromptKitSuite` helper acquires an engine through the application loader and
+The bundled `NewPromptKitSuite` helper acquires an engine through the application
-asks PromptKit to inspect its captured named definition. The loader can construct
+loader and asks PromptKit to inspect its captured named definition. The loader
-or reuse an engine; direct suite callbacks retain their own implementation and
+can construct or reuse an engine; direct suite callbacks retain their own
-lifecycle.
+implementation and lifecycle.
 
 CommandKit's inspection path does not execute prompts, contact model providers,
 or resolve provider credential values. Application acquisition and direct

docs/internal/overview.md

@@ -17,17 +17,16 @@ The root lowers registered command metadata into the internal adapter's neutral
 bridge. The adapter returns raw parsed values and neutral syntax-failure data;
 the root prepares typed input, invokes application/standard handlers, and
 coordinates outcomes and diagnostic delivery. Application callbacks and their
-supported error identity remain in the root's typed contracts rather than
+supported error identity are handled in the root through its typed contracts.
-crossing the backend bridge. Context and streams are passed to the adapter for
+Context and streams are passed to the adapter for its parsing and help operations.
-its parsing and help operations.
 
 ## `internal/cobra`
 
 This package owns the Cobra-specific command tree, argument/flag parsing,
-and help rendering. It translates neutral command metadata and parsed values into a bridge
+and help rendering. It translates neutral command metadata and parsed values
-result consumed by the root package. It does not import `commandkit` and does not
+into a bridge result consumed by the root package. It does not import `commandkit`
-own registry policy, public command declarations, provider loading, or standard
+and does not own registry policy, public command declarations, provider loading,
-inspection report rendering.
+or standard inspection report rendering.
 
 ## External implementation boundaries
 

docs/roadmap/implementation.md

@@ -797,11 +797,11 @@ func RegisterPromptKit[C any](app *App, suite PromptKitSuite[C]) error
    bookkeeping. Configuration scope installation remains independent.
 3. Accept ID as one required operand. Prompt alone has singleton `--version`
    (default empty). Both accept standard Config/Overlay selection, context-selector
-   bindings, and `--format text|yaml` (text default), plus help. No built-in configuration-scope selector is
+   bindings, and `--format text|yaml` (text default), plus help. No built-in
-   installed for definition commands; a custom context selector can use the name
+   configuration-scope selector is installed for definition commands; a custom
-   `scope` when it does not collide with an installed flag. Selector target is
+   context selector can use the name `scope` when it does not collide with an
-   `promptkit`; empty Scopes
+   installed flag. Selector target is `promptkit`; empty Scopes or a list containing
-   or a list containing promptkit applies, independent of a config scope registry.
+   promptkit applies, independent of a config scope registry.
    Other explicit targets are miswired metadata at registration.
 4. Reuse Stage 7's input/context creation and input-check rules. Missing ID is
    usage; a supplied blank/unknown/ambiguous selection reaching the owning API is

docs/roadmap/initial.md

@@ -46,9 +46,9 @@ owns current package inventory and mechanics.
 | Compare safe semantic snapshots with sensitivity union and explicit coverage gaps when comparison is enabled. | [ADR 0008](../adr/0008-semantic-configuration-diff.md) | deferred DIFF-01 |
 | Declare scope capabilities; default to `app`; preserve the meaning and coverage of `all`; order scopes consistently. | [ADR 0009](../adr/0009-configuration-scopes.md) | CFG-01–05, INT-01 |
 
-The [four earlier roadmaps](01-cli-plan.md), [dispatcher proposal](02-dispatch.md),
+The [CLI planning record](01-cli-plan.md), [dispatcher record](02-dispatch.md),
-[backend proposal](03-backend.md), and [facade proposal](04-facade.md) supply design
+[backend record](03-backend.md), and [facade record](04-facade.md) preserve the
-evidence. Carry these controlling corrections into implementation:
+review history. These corrections were selected for the initial target:
 
 - Singleton flags use the last supplied occurrence, including mixed `--name value`
   and `--name=value` spellings. Repeatable flags accumulate in order.
@@ -58,8 +58,10 @@ evidence. Carry these controlling corrections into implementation:
 - Partial capabilities remain useful; neither scopes nor families need every verb.
 - Preparing every selected view before report output is a `config show`
   requirement. Other operations have their own output timing.
-- The older acquisition graph, shared-load mandates, selector inheritance rules,
+- The older acquisition graph and shared-load mandates were superseded by
-  illustrative Go declarations, and exact report layouts remain proposals.
+  application-composed callbacks. Exact declarations, selector behavior, and
+  report layouts are owned by GoDoc and the CLI reference. Old illustrations
+  remain historical evidence.
 
 ## Initial delivery scope
 

docs/roadmap/remediation.md

@@ -1,6 +1,6 @@
 # Documentation reconciliation work
 
-Status: reconciliation in progress.
+Status: all twelve documentation remediation units complete.
 
 Date: 2026-10-07.
 
@@ -68,7 +68,8 @@ Owner: [01-cli-plan.md](01-cli-plan.md).
 - [x] Label superseded alternatives and dated sibling-checkout evidence clearly.
   Replace duplicated current contracts with concise summaries and canonical links.
 
-**Completion:** Retired completed CLI work and reconciled obsolete choices; current contracts link to their owners and future work remains explicit.
+**Completion:** Retired completed CLI work and reconciled obsolete choices;
+current contracts link to their owners and future work remains explicit.
 
 ## D-02: reconcile dispatcher planning
 
@@ -84,7 +85,8 @@ Owner: [02-dispatch.md](02-dispatch.md).
   [consumer guide](../consumers/guide.md), and current mechanics to the internal
   overview. Preserve application migration work as separate future work.
 
-**Completion:** Replaced pending dispatcher work with a completed planning record and links to implemented API, consumer, and internal owners.
+**Completion:** Replaced pending dispatcher work with a completed planning
+record and links to implemented API, consumer, and internal owners.
 
 ## D-03: reconcile backend planning
 
@@ -99,7 +101,8 @@ Owner: [03-backend.md](03-backend.md).
   and evidence tasks. Link current behavior to its owners; retain backend
   replacement and consumer adoption only as future work where applicable.
 
-**Completion:** Recorded the implemented backend, retired completed adaptation tasks, and replaced singleton-rejection proposals with canonical references.
+**Completion:** Recorded the implemented backend, retired completed adaptation
+tasks, and replaced singleton-rejection proposals with canonical references.
 
 ## D-04: reconcile facade planning
 
@@ -115,7 +118,9 @@ Owner: [04-facade.md](04-facade.md).
 - [x] Keep old automated boundary-checker suggestions clearly historical or
   optional; do not turn them into a new implementation requirement.
 
-**Completion:** Recorded facade completion, retired illustrative extra packages, and preserved backend replacement and proportionate-check considerations.
+**Completion:** Recorded facade completion, retired illustrative extra
+packages, and preserved backend replacement and proportionate-check
+considerations.
 
 ## D-05: close the preparation checklist
 
@@ -128,7 +133,8 @@ Owner: [initial-plan.md](initial-plan.md).
 - [x] Check the completed final handoff item and label the preparation process
   and recommended outline as historical planning material.
 
-**Completion:** Closed the planning handoff, checked its final item, and labeled the retained process and outline as historical.
+**Completion:** Closed the planning handoff, checked its final item, and
+labeled the retained process and outline as historical.
 
 ## D-06: clarify completed feature and implementation records
 
@@ -146,7 +152,9 @@ Owners: [initial.md](initial.md) and [implementation.md](implementation.md).
   context. Keep diff/catalog and other genuine deferrals visible; completed
   design records must not become competing current API/CLI references.
 
-**Completion:** Labeled feature specifications and staged instructions as completed history, linked current owners, and recorded later code fixes and selector-name behavior.
+**Completion:** Labeled feature specifications and staged instructions as
+completed history, linked current owners, and recorded later code fixes and
+selector-name behavior.
 
 ## D-07: correct the current CLI reference
 
@@ -166,7 +174,8 @@ Owner: [cli.md](../cli.md).
   CommandKit's standard-handler boundaries as well as returned by PromptKit.
   Preserve supported error identity and operational classification.
 
-**Completion:** Corrected native marker/comment placement, qualified callback and engine lifecycle claims, and reconciled cancellation attribution.
+**Completion:** Corrected native marker/comment placement, qualified callback
+and engine lifecycle claims, and reconciled cancellation attribution.
 
 ## D-08: remove stale policy status statements
 
@@ -180,7 +189,8 @@ Owners: [testing.md](../policy/testing.md) and [oss.md](../policy/oss.md).
 - [x] Preserve policy rules and upstream provenance while correcting local
   implementation status. This work does not add testing or licensing gates.
 
-**Completion:** Removed stale Go-suite and dependency-status claims while preserving policy rules, adopted versions, and upstream provenance.
+**Completion:** Removed stale Go-suite and dependency-status claims while
+preserving policy rules, adopted versions, and upstream provenance.
 
 ## D-09: correct the internal bridge description
 
@@ -192,7 +202,9 @@ Owner: [internal/overview.md](../internal/overview.md).
 - [x] Keep inventory/mechanics here and normative responsibility boundaries in
   the architecture policy.
 
-**Completion:** Corrected neutral metadata/results flow and root callback ownership; distinguished adapter help rendering from standard inspection reports.
+**Completion:** Corrected neutral metadata/results flow and root callback
+ownership; distinguished adapter help rendering from standard inspection
+reports.
 
 ## D-10: reconcile navigation and reading guidance
 
@@ -205,7 +217,8 @@ Owners: [development.md](../development.md) and [README.md](../../README.md).
 - [x] Update README roadmap labels/navigation to match the reconciled statuses.
   Keep genuine future-work navigation discoverable without duplicating contracts.
 
-**Completion:** Routed current work to canonical contracts and mechanics, labeled completed planning records, and exposed genuine deferrals separately.
+**Completion:** Routed current work to canonical contracts and mechanics,
+labeled completed planning records, and exposed genuine deferrals separately.
 
 ## D-11: remove temporary references from durable ADRs
 
@@ -222,21 +235,36 @@ Owners:
   must not change architectural decisions or manufacture new requirements.
 - [x] Confirm that no ADR retains a temporary-roadmap reference after the edits.
 
-**Completion:** Removed all temporary-roadmap links from ADRs through editorial reference updates; accepted statuses, dates, and architectural choices remain unchanged.
+**Completion:** Removed all temporary-roadmap links from ADRs through editorial
+reference updates; accepted statuses, dates, and architectural choices remain
+unchanged.
 
 ## D-12: review the reconciled documentation
 
-- [ ] Review every changed document against its canonical owner and current code.
+- [x] Review every changed document against its canonical owner and current code.
   Verify command spellings, defaults, outcomes, ownership, and report descriptions
   affected by the corrections.
-- [ ] Check local links and heading targets, including links affected by retiring
+- [x] Check local links and heading targets, including links affected by retiring
   sections. The audit found no unresolved local prose links or heading targets;
   preserve that result.
-- [ ] Check diffs for whitespace, stale references, and claims that delivered
+- [x] Check diffs for whitespace, stale references, and claims that delivered
   components are absent or superseded choices remain active requirements.
   Historical baselines and explicitly labeled rejected alternatives remain valid.
-- [ ] Confirm that deferred features are still identified accurately and that
+- [x] Confirm that deferred features are still identified accurately and that
   reconciliation introduces no new APIs, commands, guarantees, or consumer policy.
-- [ ] Record completion here and commit completed documentation units under the
+- [x] Record completion here and commit completed documentation units under the
   local commit policy. Use document review for this prose work; do not add tests
   or validation machinery solely to reconcile documentation.
+
+**Completion:** Reviewed all changed documentation against current code and
+owners; local links, headings, whitespace, deferrals, and preserved ADR/policy
+scope checked.
+
+## Final reconciliation evidence
+
+All D-01 through D-12 items are complete. The completed records distinguish
+historical planning from implemented contracts and genuine future work. Review
+confirmed that only Markdown documents changed, accepted ADR metadata and
+architectural choices were preserved, and policy source/version provenance was
+retained. Local prose links and heading targets resolve; diff whitespace checks
+passed. No Go tests were added or run for this documentation-only work.