Adopt shared policies and record CommandKit architecture

docs/adr/0001-command-dispatch-and-inputs.md

@@ -0,0 +1,179 @@
+# ADR 0001: Own dispatch through an explicit registry and typed inputs
+
+## Status
+
+Accepted.
+
+## Date
+
+2026-10-06
+
+## Context
+
+Audita, Narratio, Notarius, and Scriptorium repeat configuration inspection,
+routing, parsing, help, and error handling. Their command vocabulary and syntax
+have diverged. CommandKit aims to provide one implementation of standard
+inspection, consistent vocabulary and mechanics, and less application
+infrastructure. Application migrations are expected to make breaking changes.
+
+Applications have genuine domain commands, such as Narratio's `session restore`,
+that remain outside the standard suite. Merely forwarding standard families from
+separate application dispatchers would leave custom-command mechanics and root
+help dependent on each application's implementation.
+
+Input handling also needs a common boundary. Raw argv handlers or string-based
+flag retrieval leave repeated parsing and input assembly with applications.
+Presence matters for configuration overrides: omitted values differ from
+explicitly supplied empty strings, false, and zero.
+
+## Decision
+
+### Ownership and namespace structure
+
+CommandKit owns the dispatcher, shared parsing and presence tracking, help,
+syntax diagnostics, and standard-family handlers and outcomes. Applications own
+custom command names, domain meaning, validation, effects, artifacts, and
+operational outcomes.
+
+Use namespace/resource-first syntax for the standard suite. The `config` family
+and an installed `promptkit` family belong to CommandKit. PromptKit definition
+inspection uses the single `promptkit` namespace; root `prompt` and `profile`
+names remain available to applications. This provides a clear family ownership
+boundary without spreading a namespace across root verbs.
+
+Applications register commands outside reserved families. They cannot replace
+standard handlers or add private operations underneath a reserved family.
+Standard-family context selectors and typed overrides use the defined input
+extension mechanism rather than introducing application-owned operations there.
+
+Applications retain `main`, signal handling, context creation, stream selection,
+runtime construction, and final process exit. CommandKit returns invocation
+outcomes and does not terminate the process. Configuration schemas, acquisition,
+domain resolution and validation, and provider construction remain application
+integration responsibilities. ConfigKit and PromptKit retain their own
+configuration, provenance, safe inspection, and native rendering semantics.
+
+### Explicit registry and capability installation
+
+Each explicitly constructed application instance owns a registry. Applications
+register individual commands and composable groups. There is no package-global
+registry or import-time `init` registration.
+
+Definitions provide paths, descriptions, flags and defaults, repetition and
+presence metadata, operand requirements, and execution handlers. One definition
+supplies routing, parsing, and help. Duplicate paths and attempts to replace
+reserved commands return registration errors; order does not select a winner.
+
+Help and version are installed automatically using supplied application identity
+and build metadata. Configuration and PromptKit families are installed when the
+application supplies their providers. Supplying a capability installs its complete
+standard family, not a collection requiring manual operation-by-operation wiring.
+
+Registering providers does not execute them. Construction may diagnose missing
+or invalid wiring without reading configuration, resolving credentials, or
+building engines. Invalid configuration is an invocation-time failure. Command
+declarations, help, and version remain available independently of application
+initialization. The selected handler acquires dependencies when it needs them.
+
+Do not install placeholder commands. Omitting the configuration provider does
+not make a partial integration a complete core adopter. PromptKit is optional;
+its selected family is installed as a complete capability. The CLI roadmap owns
+the proposed command inventory and the remaining choices for that standard.
+
+### Typed inputs with explicit bindings
+
+Use application-defined input structs for custom commands and CommandKit-defined
+inputs for standard handlers. Explicit registration binds flags and operands to
+their input fields. The declarations also supply parsing and help metadata.
+Handlers do not retrieve primitive values by flag name or parse the complete argv.
+
+Use ordinary typed fields where omission has no separate meaning. Where it does,
+keep supplied/not-supplied state beside the value in a presence-aware field.
+Defaults do not mark input as explicitly supplied. Preserve explicit empty,
+false, and zero values.
+
+Create fresh input storage per invocation. Registered commands must not capture
+one mutable input permanently or retain prior values, collections, or presence.
+This decision addresses lifetime without establishing concurrent dispatch.
+
+Supply context and stream access separately from CLI inputs. Input declarations
+and binding setup must not construct execution dependencies. Applications perform
+domain validation and may interpret parsed domain values or supply a custom value
+parser through the binding system.
+
+The public factory, binding, registration, and handler signatures and presence
+type names remain API design choices. No illustrative declaration establishes
+an exact public API.
+
+### Outcomes and domain behavior
+
+Resolve the command and handle help/version before loading application state.
+For execution, allocate fresh inputs, apply shared parsing and operand checks,
+then invoke the typed handler. Return its invocation outcome to the application.
+
+Shared usage errors and standard-family outcomes belong to CommandKit. Custom
+handlers must communicate application-specific outcomes without silent generic
+reclassification. For example, Scriptorium output validation and Notarius artifact
+outcomes remain application concerns. Do not classify domain errors by matching
+message strings or print usage unconditionally for runtime failures.
+
+Common mechanics do not require a common success-report format for custom
+commands. The application owns its artifact and operational output contracts.
+Exact result/error interfaces and unresolved grammar choices are separate design
+work, not approvals implied by this decision.
+
+## Alternatives considered
+
+### Dispatcher and ownership
+
+| Alternative | Analysis |
+| --- | --- |
+| Application-owned dispatcher forwarding standard families | Small integration surface and convenient migration, but custom syntax, root help, and errors still need cross-dispatcher coordination; removes less infrastructure. |
+| Standard definitions mounted into an application's framework | Reuses routing infrastructure, but application configuration can preserve inconsistent behavior outside mounted families. Internal framework reuse remains compatible with this decision. |
+| Shared metadata/help with separate routing | Unifies discovery but adds synchronization among metadata, routing, and parsing. One dispatcher avoids it. |
+| Both full dispatch and embeddable family handlers | Serves established external CLI architectures but adds integration surfaces and maintenance. Add embedding only for a concrete need. |
+| Raw-argument handlers for custom commands | Eases migration but leaves parsing and help responsibilities with applications. A future transition adapter needs explicit limitations and is not full adoption. |
+| Universal application runtime framework | Could absorb startup and operational services, but expands beyond the demonstrated CLI boundary and domain ownership. |
+| Verb-first standard paths | Groups actions but distributes namespace ownership among individual routes. Namespace/resource-first paths keep family ownership clear. |
+| Reserve root `prompt` and `profile` | Provides short resource paths but consumes application namespaces. A single `promptkit` family gives the library one ownership boundary. |
+
+### Registration
+
+| Alternative | Analysis |
+| --- | --- |
+| Declarative tree passed to construction | Makes assembly visible together; larger applications still need group composition. May become a convenience over the same registry. |
+| Constructor options for every command/group | Compact setup, but excessive options can obscure commands versus application settings. Option conventions remain API design work. |
+| Global registry populated by `init` | Less entry-point code, but hidden import effects, shared mutable state, and unclear ownership. Explicit instances avoid those costs. |
+
+### Handler inputs
+
+| Alternative | Analysis |
+| --- | --- |
+| Parsed-value accessor object | Uniform handlers, but string-based lookup, runtime type errors, and repeated assembly remain. |
+| Individual typed parameters | Clear for small commands; grows into long signatures and adapter machinery. Typed structs scale more naturally. |
+| Reflection and struct tags | Compact declarations, but adds a tag language, field-discovery rules, and runtime declaration validation. Explicit bindings keep declarations visible. |
+| Typed command objects | Can organize complex handlers; must separate fresh input from dependency and execution lifetimes. Applications may use objects without making them mandatory. |
+| Generated bindings/adapters | Can combine compact authoring and typing, but adds tooling and generated-file maintenance without demonstrated need. |
+| Raw arguments | Simple routing integration, but returns common parsing and help to applications. |
+
+## Consequences
+
+One command system removes repeated routing, parser setup, help assembly, and
+shared error plumbing as well as standard inspection handlers. Domain handlers
+and their declarations remain recognizable application code.
+
+The public registration surface is larger than family delegation, and explicit
+bindings require connecting declarations to the correct fields. Those costs
+support consistent mechanics without requiring reflection or generated code.
+
+Shared parsing defects can affect every adopter. Consumer and backend integration
+evidence must protect selected semantics, including ownership conflicts, help
+without configuration, presence, fresh input, cancellation, and domain outcomes.
+Intentional migration changes require coordinated application documentation and
+subprocess-consumer updates.
+
+The [architecture policy](../policy/architecture.md) owns normative boundaries.
+The [dispatcher roadmap](../roadmap/02-dispatch.md) owns implementation status and
+pending API design. The [CLI roadmap](../roadmap/01-cli-plan.md) retains command
+proposals and their approval status. [ADR 0002](0002-cobra-backend.md) selects the
+backend, and [ADR 0003](0003-public-facade.md) defines its public/internal boundary.

docs/adr/0002-cobra-backend.md

@@ -0,0 +1,95 @@
+# ADR 0002: Use Cobra and pflag as the initial internal CLI backend
+
+## Status
+
+Accepted.
+
+## Date
+
+2026-10-06
+
+## Context
+
+CommandKit's selected dispatcher model needs nested routing, flags and operands,
+generated help, usage diagnostics, and invocation execution. Reimplementing this
+generic infrastructure would add work beyond the suite-specific inspection and
+consistency behavior that motivates the library.
+
+Cobra and urfave/cli v3 were the finalists. The latter's destination bindings and
+duplicate controls offered a close fit for the explicit-input model. The author
+strongly preferred Cobra because of its broader adoption. Familiarity and the
+availability of contributors who know the framework are useful maintenance
+considerations across several related applications.
+
+The selection was based on documentation and API review. Ecosystem adoption is
+the selection rationale, not evidence that every backend default is an appropriate
+CommandKit contract.
+
+## Decision
+
+Use Cobra with pflag as the sole initial CLI backend. CommandKit translates its
+registrations into backend command trees, flag bindings, and execution callbacks.
+Reuse their routing, option parsing, help, context, and stream mechanisms and add
+adaptation where selected CommandKit semantics require it.
+
+CommandKit retains its own public registration API, typed inputs, standard
+families, and observable contracts. Applications do not construct Cobra commands
+or use pflag getters in handlers. [ADR 0003](0003-public-facade.md) isolates the
+backend behind an internal adapter and root-owned public contracts.
+
+Applications retain process lifecycle and domain execution. ConfigKit and
+PromptKit retain configuration and inspection semantics. Framework selection
+does not transfer those responsibilities to Cobra or CommandKit.
+
+Build fresh backend command/flag state and input storage per invocation. A fresh
+command tree constructed from registered definitions is the initial approach.
+Tree construction must not load configuration or create application runtime.
+
+Implement one concrete backend. There is no initial public backend selector or
+pluggable framework. A future replacement can change internal implementation
+while preserving the public API and selected behavioral contracts.
+
+## Alternatives considered
+
+| Alternative | Advantages | Reason not selected |
+| --- | --- | --- |
+| urfave/cli v3 | Destination bindings for flags and named operands, presence queries, and duplicate controls fit the chosen input model closely. | Credible alternative; Cobra's broader adoption is the preferred maintenance tradeoff. |
+| pflag alone | Established parsing with a smaller integration surface. | Leaves more routing, help integration, and command infrastructure to implement. |
+| Kong | Compact typed-struct and tag-driven declarations. | Its main declaration model differs from the explicit-binding API; adaptation reduces its benefit. |
+| Standard `flag` alone | Familiar variable binding and custom value parsing. | First-operand stopping requires adaptation for the intended syntax, with more custom command infrastructure. |
+| Expose Cobra as the public API | Less adapter code and the full framework surface. | Couples consumers to backend structures and framework-specific configuration. |
+| Interchangeable backends immediately | Future integration flexibility. | Adds abstraction and behavior surfaces without a current requirement. |
+
+## Consequences
+
+The framework supplies established generic CLI machinery. CommandKit still owns
+registration conflicts, reserved families, typed bindings and presence, standard
+help and diagnostics, provider integration, and selected reports and outcomes.
+
+The adapter must accommodate explicit empty/false/zero values, fresh state,
+selected repetition and operand rules, and help without configuration. Backend
+features do not expand the standard automatically: for example, completion
+commands remain deferred unless deliberately selected.
+
+Backend error handling must preserve application outcomes, avoid duplicate
+diagnostics, and return control to the application's entry point. Native YAML
+inspection and multi-document scope display remain integration work using the
+owning libraries. Choosing a framework introduces no JSON report requirement.
+
+Exact dependency versions and attribution are selected when dependencies are
+incorporated. Meaningful integration evidence must exercise the real adapter
+against selected contracts. A dependency update or replacement can change CLI
+behavior even with unchanged Go signatures and is subject to compatibility policy.
+
+The [architecture policy](../policy/architecture.md) owns normative boundaries;
+the [backend roadmap](../roadmap/03-backend.md) owns implementation tasks and status.
+[ADR 0001](0001-command-dispatch-and-inputs.md) records the dispatcher and input
+model. Remaining command and grammar proposals belong to the CLI roadmap.
+
+Reviewed primary references from the selection:
+
+- [Cobra API](https://pkg.go.dev/github.com/spf13/cobra).
+- [Cobra command and help guide](https://github.com/spf13/cobra/blob/main/site/content/user_guide.md).
+- [Cobra flag bindings](https://cobra.dev/docs/how-to-guides/working-with-flags/).
+- [pflag syntax and extension points](https://github.com/spf13/pflag).
+- [urfave/cli v3 API](https://pkg.go.dev/github.com/urfave/cli/v3).

docs/adr/0003-public-facade.md

@@ -0,0 +1,109 @@
+# ADR 0003: Own public contracts through a root facade and internal CLI adapter
+
+## Status
+
+Accepted.
+
+## Date
+
+2026-10-06
+
+## Context
+
+CommandKit needs room to change implementation while consumers retain stable
+registration, input, and invocation contracts. Exposing backend assembly or
+extension structures would let applications depend on details that maintainers
+may later replace.
+
+ConfigKit, PromptKit, and ReleaseKit demonstrate facades that own public types and
+delegate through private state and explicit conversion. ConfigKit also translates
+upstream YAML parser structures into an independent internal document model.
+ReleaseKit has a second facade for a distinct lightweight runtime responsibility;
+CommandKit has no corresponding requirement for another public package initially.
+
+The Cobra selection is compatible with dependency isolation. Public API
+independence needs a genuine contract boundary, and keeping backend structures
+out of shared internal representations also makes future replacement easier.
+
+## Decision
+
+Use the module root `commandkit` as the sole initial supported public facade.
+Define CommandKit's public named types there and expose only selected operations,
+extension contracts, and documented methods. Handles keep implementation state in
+private fields.
+
+Implementation packages belong under Go's `internal/` boundary. Public code
+forwards inward with explicit wrappers and conversions; internal production
+packages do not import the root. Shared internal contracts live inside that
+boundary. Additional public packages require a deliberate decision based on a
+durable consumer responsibility.
+
+Do not alias public types to internal or backend types, anonymously embed those
+types to promote methods, or expose implementation bridge methods. Exported
+fields, signatures, variables, callbacks, interface methods, constraints, and
+method sets must not reveal internal or Cobra/pflag structures. Loosely typed
+values and returned errors must not provide indirect backend-object access.
+
+Standard contracts such as `context.Context` and `io.Writer` remain appropriate.
+ConfigKit or PromptKit public types may be selected as deliberate integration
+dependencies. Application input types remain application-owned. Go declarations
+and GoDoc own exact exported contracts.
+
+Confine Cobra/pflag types and operations to an internal adapter. Registry logic,
+standard handlers, and shared definitions use CommandKit-owned representations.
+The adapter translates paths, descriptions, bindings, presence, callbacks, and
+selected help/outcome semantics into backend machinery. Do not reproduce Cobra's
+complete API through renamed wrappers.
+
+Typed input factories and handlers can cross the facade through private callbacks
+without internal packages importing public declarations. Preserve fresh input and
+backend state per invocation. Introduce narrow internal interfaces where actual
+engine/adapter interaction justifies them; exact package names and splits remain
+implementation choices.
+
+Use one concrete backend initially. There is no public backend interface, plugin
+registry, or requirement for a second implementation. Replacement is a future
+maintainer change.
+
+Translate backend-owned syntax failures into CommandKit diagnostics and outcomes.
+Preserve useful public identity for application handler errors and cancellation
+according to the invocation contract. Explicit conversions must preserve value
+ownership, callback lifetime, presence, and supported error semantics.
+
+## Alternatives considered
+
+| Alternative | Analysis |
+| --- | --- |
+| Keep all machinery in the public root | Less forwarding, but harder consumer navigation and easier accidental public expansion. |
+| Alias or embed implementation types | Less conversion code, but couples public type identity, fields, or method sets to internal choices. |
+| Hide Cobra only behind the public facade | Hides types from applications but allows backend structures to spread through internal logic, complicating replacement. |
+| Mirror Cobra's API with wrappers | Removes dependency names while preserving its conceptual coupling and compatibility surface. |
+| Public packages for registry, bindings, backend, and other mechanisms | Adds supported imports and assembly contracts without a distinct consumer responsibility. |
+| Selectable/pluggable backends immediately | Adds selection and extension machinery before a concrete need exists. |
+
+## Consequences
+
+Consumers depend on deliberate root contracts while internal algorithms,
+collaborators, and package boundaries can evolve. Useful application registration
+capabilities still need a proportionate API; minimizing accidental exports must
+not recreate repetitive consumer infrastructure.
+
+Explicit forwarding and conversion require maintenance. Type identity, ownership,
+method sets, callback lifetime, and error semantics must be protected by evidence,
+not inferred from package relocation.
+
+Compiled public API checks protect aliases, fields, signatures, constraints, and
+promoted methods. Import checks keep the backend in its adapter and internal
+production code independent of root. External-package tests protect consumer
+semantics through the real adapter. ConfigKit and ReleaseKit provide precedents
+for these checks without requiring their full validation workflows.
+
+Backend replacement can preserve the public Go API but must also preserve selected
+CLI behavior or follow the release policy for intentional incompatibilities.
+Backend defaults do not independently establish new CommandKit contracts.
+
+The [architecture policy](../policy/architecture.md) owns normative boundaries.
+The [facade roadmap](../roadmap/04-facade.md) owns implementation status, package
+layout illustrations, and pending work. [ADR 0001](0001-command-dispatch-and-inputs.md)
+records the dispatcher/input model, and [ADR 0002](0002-cobra-backend.md) selects
+the initial backend. The CLI roadmap retains individual command approval status.

docs/development.md

@@ -0,0 +1,82 @@
+# Developing CommandKit
+
+CommandKit currently contains adopted repository policies, accepted architectural
+decisions, and implementation plans. There is no Go module or implemented command
+dispatcher yet. The [README](../README.md) provides project orientation; the
+[documentation policy](policy/documentation.md#canonical-ownership) assigns
+canonical documentation owners.
+
+## Initial orientation
+
+1. Inspect the worktree and preserve unrelated staged and unstaged changes.
+2. Read the [agent policy](policy/agents.md) and select other applicable policies
+   using the guide below.
+3. Read the owning roadmap for proposals and implementation status, and the
+   applicable ADR for accepted decisions and rationale.
+4. Inspect implementation and relevant consumer contracts when they exist.
+
+## Policy Reading Guide
+
+| Policy | Read before… |
+| --- | --- |
+| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
+| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
+| [Architecture](policy/architecture.md) | Planning or changing Go library code or its structure. |
+| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
+| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
+| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
+| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. |
+
+- Read applicable policies before making decisions they govern; multiple policies
+  may apply.
+- Select policies using the task triggers above. Follow cross-references to
+  relevant sections when needed to resolve a concrete question.
+- Reuse policies already available in context; reread when changed or no longer
+  available.
+- Expand reading when the task's scope expands.
+- When revising a policy itself, read that policy and any provisions elsewhere
+  affected by the revision.
+
+## Task-specific reading guide
+
+| Task | Read |
+| --- | --- |
+| Standard command vocabulary, reports, or remaining operator-contract proposals | [CLI plan](roadmap/01-cli-plan.md) |
+| Dispatcher, registration, or typed input design | [Dispatcher roadmap](roadmap/02-dispatch.md) and [ADR 0001](adr/0001-command-dispatch-and-inputs.md) |
+| Backend integration | [Backend roadmap](roadmap/03-backend.md) and [ADR 0002](adr/0002-cobra-backend.md) |
+| Public API or internal adapter boundaries | [Facade roadmap](roadmap/04-facade.md), [ADR 0003](adr/0003-public-facade.md), and the architecture policy |
+| Licensing or incorporated material | [Project grant](../COPYRIGHT), [license texts](../LICENSE), and [attribution](oss/attribution.md) |
+| Policy provenance and adoption follow-up | [Policy provenance](policy/meta.md) and [adoption record and follow-up](roadmap/policy.md) |
+
+Read all applicable rows for cross-cutting work. These roadmaps describe future
+implementation; their illustrative Go types and package layouts are not APIs.
+
+## Documentation validation
+
+For current prose work, inspect relevant diffs, check local links and fragment
+destinations, check provenance and template residue, and confirm that statements
+about current behavior match the repository. Include intended new files in that
+review. Preserve supplied license-text formatting and compare copied texts with
+their pinned source.
+
+For tracked and staged prose, run from the repository root:
+
+```sh
+git diff --check -- '*.md' COPYRIGHT
+git diff --cached --check -- '*.md' COPYRIGHT
+```
+
+These commands do not cover untracked files. Review their contents and whitespace
+before staging, or use the staged check after staging only the intended files.
+Sibling-checkout evidence links in the CLI proposal are review references, not
+build dependencies; durable implemented contracts will belong in CommandKit.
+
+There is no Go suite or release command to run in the current repository. Add
+concrete development commands with their implementation. Future code validation
+follows the testing policy; the release procedure and publication tooling will be
+introduced with a releasable module under the release policy.
+
+Follow the [local commit policy](policy/agents.md#git-commit-policy). Completed
+units receive local commits by default, subject to explicit user instructions.
+Preserve unrelated work; default commit authorization does not authorize pushing
+or publishing.

docs/oss/attribution.md

@@ -0,0 +1,20 @@
+# Open Source Attribution Notices
+
+## Standard Repository Policies
+
+Material: `docs/policy/meta.md`, `docs/policy/agents.md`,
+`docs/policy/architecture.md`, `docs/policy/testing.md`,
+`docs/policy/documentation.md`, `docs/policy/release.md`, and
+`docs/policy/oss.md`; the root `AGENTS.md` orientation after the knowledge-graph
+instructions; and the Policy Reading Guide in `docs/development.md`, adapted for
+this repository.
+
+Copyright (C) 2026 Eric Rakestraw
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+
+License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) |
+[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE).
+
+[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843).

docs/oss/licenses/CC-BY-SA-4.0.txt

@@ -0,0 +1,170 @@
+Creative Commons Attribution-ShareAlike 4.0 International
+
+ Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
+
+Considerations for licensors: Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. More considerations for licensors.
+
+Considerations for the public: By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described.
+
+Although not required by our licenses, you are encouraged to respect those requests where reasonable. More considerations for the public.
+
+Creative Commons Attribution-ShareAlike 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
+
+Section 1 – Definitions.
+
+     a.	Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
+
+     b.	Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
+
+     c.	BY-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, approved by Creative Commons as essentially the equivalent of this Public License.
+
+     d.	Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
+
+     e.	Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
+
+     f.	Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
+
+     g.	License Elements means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike.
+
+     h.	Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
+
+     i.	Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
+
+     j.	Licensor means the individual(s) or entity(ies) granting rights under this Public License.
+
+     k.	Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
+
+     l.	Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
+
+     m.	You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
+
+Section 2 – Scope.
+
+     a.	License grant.
+
+          1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
+
+               A. reproduce and Share the Licensed Material, in whole or in part; and
+
+               B. produce, reproduce, and Share Adapted Material.
+
+          2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
+
+          3. Term. The term of this Public License is specified in Section 6(a).
+
+          4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
+
+          5. Downstream recipients.
+
+               A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
+
+               B. Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply.
+
+               C. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
+
+          6. No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
+
+     b.	Other rights.
+
+          1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
+
+          2. Patent and trademark rights are not licensed under this Public License.
+
+          3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.
+
+Section 3 – License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the following conditions.
+
+     a.	Attribution.
+
+          1. If You Share the Licensed Material (including in modified form), You must:
+
+               A. retain the following if it is supplied by the Licensor with the Licensed Material:
+
+                    i.	identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
+
+                    ii.	a copyright notice;
+
+                    iii. a notice that refers to this Public License;
+
+                    iv.	a notice that refers to the disclaimer of warranties;
+
+                    v.	a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
+
+               B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
+
+               C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
+
+          2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
+
+          3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
+
+     b.	ShareAlike.In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply.
+
+          1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License.
+
+          2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material.
+
+          3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply.
+
+Section 4 – Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
+
+     a.	for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;
+
+     b.	if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and
+
+     c.	You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
+For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
+
+Section 5 – Disclaimer of Warranties and Limitation of Liability.
+
+     a.	Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.
+
+     b.	To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.
+
+     c.	The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
+
+Section 6 – Term and Termination.
+
+     a.	This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
+
+     b.	Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
+
+          1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
+
+          2. upon express reinstatement by the Licensor.
+
+     c.	For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
+
+     d.	For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
+
+     e.	Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
+
+Section 7 – Other Terms and Conditions.
+
+     a.	The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
+
+     b.	Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
+
+Section 8 – Interpretation.
+
+     a.	For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
+
+     b.	To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
+
+     c.	No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
+
+     d.	Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
+
+Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at creativecommons.org/policies, Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
+
+Creative Commons may be contacted at creativecommons.org.

docs/policy/agents.md

@@ -0,0 +1,97 @@
+# Agent Policy
+
+**Base Policy Version:** 1.3
+
+**Last Updated**: 2026-10-06
+
+**Upstream Source:** [agents.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md)
+
+## Purpose
+
+Agents must read and follow these rules.
+
+## Implementation Discipline
+
+**KEY PRINCIPLES:** Write the simplest idiomatic code that satisfies the user's
+request. Do not implicitly strengthen requirements, restrictions, or guarantees
+beyond what the user actually requested.
+
+**Keep implementation machinery proportionate.** Use straightforward,
+idiomatic code and introduce only the machinery needed to support the requested
+behavior and flexibility. Optimize for conceptual simplicity and
+maintainability, not for the fewest lines, fewest options, or narrowest product
+surface.
+
+**Do not invent restrictions.** Do not reject, prohibit, constrain, cap,
+harden, or otherwise narrow behavior unless required by the user, an explicit
+repository contract, or an unavoidable correctness constraint. Preserve
+operator and caller choice where policy has not been established. If an
+additional restriction appears advisable, present it as a decision rather than
+silently implementing it.
+
+**Do not invent guarantees.** Do not strengthen public contracts, guarantees,
+or invariants beyond those expressly requested by the user.
+
+**Use the standard library.** For example: in almost every case, the best
+approach to copying files is to use the standard library. Writing custom code to
+implement power-loss protection at the application level, or to guard against
+bad actors with privileged and concurrent access to the host's filesystem,
+is wasteful, unnecessary, and not idiomatic. Stick to the simple, standard, and
+idiomatic approach unless another path is expressly requested by the user.
+
+**An implementation detail is not repository policy.** Tests and documentation
+must not elevate incidental behavior into a durable guarantee or restriction
+unless that behavior was expressly selected as part of the contract.
+
+## CommandKit Contract Authority
+
+Existing explicit contracts and deliberately accepted decisions remain
+authoritative. Changing or weakening one requires a deliberate decision.
+Agent-authored plans, tests, documentation, and prior implementations do not
+independently establish additional requirements. Identify the authorizing
+requirement or decision; when authority is unclear, surface that ambiguity.
+
+A correctness constraint must follow from requested behavior or an established
+invariant, not from the convenience of the selected implementation. Explain the
+specific failure it prevents and why a less restrictive implementation cannot
+satisfy the contract.
+
+The CLI roadmap distinguishes accepted choices from remaining proposals. Do not
+approve proposed commands, grammar, statuses, or illustrative API declarations
+merely by repeating them in implementation or tests. Cobra/pflag defaults do not
+independently establish CommandKit contracts.
+
+## Git Commit Policy
+
+By default, commit each completed, nonempty unit of work using a
+concise, plain-English message describing what changed. This policy is standing
+authorization to create those local commits; a separate user request is not
+required. An explicit user instruction to leave work uncommitted takes precedence.
+
+A unit of work is a focused, reviewable outcome, including its relevant tests and
+documentation.
+Complete the appropriate validation before committing. If work is incomplete or
+validation is blocked, report that state accurately.
+
+Before committing:
+
+1. Run `git status --short` and review the relevant diff, including any staged
+   changes. Identify changes that predate the current unit of work.
+2. Exclude secrets, local environment files, generated junk, and unrelated changes.
+3. Stage only the files or hunks belonging to the completed unit. Use `git add .`
+   only when every included change belongs to that unit. Preserve unrelated
+   staged and unstaged work.
+4. Review `git diff --staged` and run appropriate checks for the change. Reuse
+   successful checks for unchanged content.
+5. Review `git log --oneline -n 10` and use
+   `git commit -m "<concise plain-English commit message>"`.
+6. Report the commit identifier and any remaining uncommitted work.
+
+If the unit cannot be safely separated from pre-existing work, leave it uncommitted
+and explain the overlap rather than silently including that work. If a commit
+fails, preserve the changes and report the failure; do not bypass hooks.
+
+Default commit authorization does not authorize pushing, publishing, amending,
+resetting, reverting, or rewriting history. Those actions require a separate user
+instruction. Do not use `git commit -a` or `git commit --no-verify` to bypass the
+staging and validation discipline above.

docs/policy/architecture.md

@@ -0,0 +1,151 @@
+# Architecture Policy
+
+**Base Policy Version:** 1.3
+
+**Last Updated**: 2026-10-06
+
+**Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
+
+## Purpose And Ownership
+
+CommandKit is an opinionated Go library for standard inspection commands,
+consistent CLI syntax, and reduced application command infrastructure. This
+policy owns normative responsibility boundaries, dependency direction, and
+architectural constraints. ADRs own decision rationale; the
+[implementation roadmaps](../development.md#task-specific-reading-guide) own
+proposals, sequencing, and implementation status.
+
+Architectural constraints govern future implementation. Concrete package
+inventory and mechanics belong in internal documentation when implemented.
+Exact exported contracts belong in Go declarations and GoDoc; implemented
+operator behavior belongs in the CLI reference. Do not describe planned packages
+or APIs as existing implementation.
+
+## Success Criteria
+
+Evaluate designs and adoption against both criteria:
+
+1. Applications adopt consistent command vocabulary, syntax, and inspection
+   behavior for the standard suite.
+2. Applications remove substantial repeated CLI infrastructure while keeping
+   clear ownership of domain behavior.
+
+Existing applications supply evidence of needs, not compatibility requirements
+for CommandKit. Adoption is expected to make breaking changes to divergent
+consumer conventions. Once CommandKit publishes its own contracts, changes to
+those contracts follow the [release policy](release.md).
+
+Use representative simple and complex consumers to substantiate API designs.
+Replacing parsing and dispatch plumbing with equally repetitive registration or
+callback bookkeeping does not satisfy infrastructure reduction. Keep enough
+flexibility to express genuine application requirements within one command model.
+
+## Command And Application Ownership
+
+[ADR 0001](../adr/0001-command-dispatch-and-inputs.md) records the selected
+CommandKit-owned dispatcher, per-instance registry, and typed-input model.
+
+CommandKit owns dispatch, common parsing, presence tracking, help, shared syntax
+diagnostics, and the handlers and observable contracts of its standard families.
+Applications register domain commands outside those families and own their
+meaning, effects, domain validation, artifacts, and operational outcomes.
+Namespaces provide the ownership boundary: standard `config` and an installed
+`promptkit` family remain CommandKit-owned. Applications do not replace their
+handlers or add private operations beneath them.
+
+Applications own their executable entry points, context creation, signals,
+stream selection, runtime construction, and final process exit. CommandKit
+returns invocation outcomes and must not terminate the process. Its common
+mechanics apply to custom commands without taking ownership of their domain
+semantics or success-report formats.
+
+Use explicit instance construction and composable command registration, not
+package-global or import-time registries. One definition supplies routing,
+parsing, and help metadata. Duplicate paths and attempts to replace reserved
+commands report errors rather than letting registration order select a winner.
+
+Standard families are installed from supplied capabilities. Help and version use
+application identity/build metadata; configuration and PromptKit providers install
+their complete corresponding families. Provider registration is lazy and does
+not acquire configuration or construct engines. Help and version remain available
+with missing or invalid configuration. Do not install placeholder commands or
+claim complete adoption for unsupported operations.
+
+## Handler Inputs And Invocation State
+
+Handlers receive typed input structs with explicit flag and operand bindings.
+Use presence-aware fields where omission matters; preserve explicitly supplied
+empty, false, and zero values independently of parser defaults. Context, streams,
+and execution dependencies are separate from CLI inputs.
+
+Create fresh input and backend command/flag state per invocation. Registered
+commands must not retain input values, collections, or presence state across
+runs. This does not establish a concurrent-dispatch guarantee.
+
+Applications may interpret parsed domain values and provide domain value parsers
+through the binding system. Raw-argument parsing is not the primary handler model.
+Keep input declarations available without application initialization.
+
+## Public Facade And Dependency Direction
+
+[ADR 0003](../adr/0003-public-facade.md) records the root `commandkit` facade and
+internal adapter boundary. The root is the sole initial supported public package
+and defines CommandKit's public named types. Additional public packages require a
+deliberate decision based on a durable consumer responsibility.
+
+Public handles retain private implementation state and expose explicitly selected
+methods. Use explicit forwarding and conversions that preserve type identity,
+value ownership, callback lifetime, presence, and public error semantics. Do not
+alias or anonymously embed implementation types into the public API, promote
+internal methods, or expose backend bridge methods.
+
+Implementation belongs under Go's `internal/` boundary. Dependencies run from the
+facade inward; internal production packages do not import the root. Shared
+implementation contracts belong inside the internal boundary. Public signatures,
+fields, callbacks, constraints, and method sets must not expose internal or
+Cobra/pflag types. Backend objects must not escape through loosely typed values
+or returned errors.
+
+Standard contracts such as `context.Context` and `io.Writer` remain appropriate.
+Other public dependency types require deliberate API selection. Application-owned
+input types remain application-owned. Do not expand exports merely to simplify
+internal assembly.
+
+## Backend And Library Integration
+
+[ADR 0002](../adr/0002-cobra-backend.md) selects Cobra with pflag as the sole
+initial backend. Their types and operations stay inside an internal adapter that
+translates CommandKit-owned definitions into backend machinery. Registry logic,
+standard handlers, and shared internal representations remain independent of
+backend-specific structures.
+
+Reuse backend routing and parsing mechanisms, adapting them to selected
+CommandKit semantics. Do not replicate Cobra's entire API through renamed
+wrappers. Introduce narrow internal interfaces where actual interactions justify
+them; a public backend selection or plugin framework is not part of the design.
+
+ConfigKit and PromptKit own configuration composition, provenance, inspection
+semantics, secret classification, and native rendering. Applications provide
+schemas, acquisition, domain resolution and validation, and construction of
+inspection providers. CommandKit exposes those capabilities without implementing
+a parallel configuration or prompt engine. Use independently released public
+contracts; do not import sibling internal packages or depend on adjacent checkouts.
+
+## Scope And Non-goals
+
+Keep packages and abstractions proportionate to cohesive responsibilities. The
+library is not a general application runtime, dependency-injection framework,
+logging system, hosted service, or standalone application. It does not prescribe
+domain execution vocabulary outside the standard suite.
+
+The [CLI roadmap](../roadmap/01-cli-plan.md) distinguishes accepted operator
+choices from remaining command and grammar proposals. Backend defaults and
+incidental consumer behavior do not establish new contracts. A replacement
+backend must preserve published CLI behavior or follow deliberate compatibility
+changes under the release policy.
+
+Base restrictions and guarantees on selected requirements. Configuration and
+prompt libraries retain their own confidentiality contracts; standard output
+must use their safe inspection APIs without promising that arbitrary application
+content is safe for public disclosure. New threat scope or restrictions require
+a deliberate decision under the [agent policy](agents.md).

docs/policy/documentation.md

@@ -0,0 +1,180 @@
+# Documentation Policy
+
+**Base Policy Version:** 1.11
+
+**Last Updated**: 2026-10-06
+
+**Upstream Source:** [documentation.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md)
+
+## Purpose
+
+This policy assigns each documentation topic to one canonical owner. Its goal is
+to keep CommandKit's documentation accurate, concise, discoverable, and resistant
+to drift for consumers, operators, maintainers, developers, and coding agents.
+
+## Core Rules
+
+### One Canonical Owner
+
+Each authoritative fact belongs in one document. A non-owning document may give
+a short, stable summary for orientation, but it must link to the canonical owner
+for volatile details.
+
+Volatile details include commands, flags, configuration fields and defaults,
+module keys, schemas, file names, paths, status codes, retry behavior, and
+runtime guarantees. If readers could reasonably treat a statement as a
+contract, maintain it only in the owning document.
+
+### Current And Future Behavior
+
+Outside `docs/roadmap/`, documentation describes implemented behavior only.
+Partial features may be described only to their implemented boundary.
+
+Architectural constraints may govern future changes. Describe current structure
+from implemented behavior.
+
+ADRs may record an accepted architectural decision before implementation. The
+roadmap owns implementation status and sequencing until the decision is
+implemented. Current architecture, user, operator, integration, and internal
+documentation are updated when the behavior lands.
+
+### Audience And Detail
+
+Write for the document's stated audience and include only the detail needed for
+its owned topic. Keep user and operator docs focused on using and operating the
+application. Developer docs should link to user-facing and external contracts
+for their definitions.
+
+### Examples
+
+Complete copyable files belong in `examples/`. Documentation may use the
+smallest illustrative snippet needed to explain its owned topic, but should link
+to maintained examples for complete copyable files.
+
+Examples must be valid, secret-free, and tested where practical. Commands and
+configuration used in documentation should match the application.
+
+### Security And Privacy
+
+Documentation and examples must not contain real credentials, private keys,
+private environment dumps, sensitive source material, or private infrastructure
+details unless intentionally public. Document secret-handling mechanisms, not
+secret values.
+
+## Canonical Ownership
+
+| Topic | Canonical owner | Owned content | Content owned elsewhere |
+| --- | --- | --- | --- |
+| Product orientation and minimal example | `README.md` | Purpose, current status, shortest useful example when implemented, and navigation, including licensing and attribution. | Complete command reference, configuration reference, operational procedures, implementation detail. |
+| Contributor entry point | `docs/development.md` | Task-oriented reading guide, contributor orientation, baseline validation commands, and canonical links. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. |
+| CommandKit architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
+| Policy-set provenance and upstream navigation | `docs/policy/meta.md` | Policy-set origin, local authority, adoption baselines, and upstream adoption and update links. | Task-specific reading triggers, detailed adoption procedures, and formal attribution notices. |
+| Agent policy | `docs/policy/agents.md` | Proportionate, idiomatic implementation; rules against inventing requirements, restrictions, guarantees, or policy. | Application contracts, architecture, testing policy, and contributor procedures. |
+| Documentation policy | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
+| Testing policy | `docs/policy/testing.md` | Test philosophy, risk sufficiency, boundaries, doubles, coverage, regressions, and test maintenance. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
+| Release policy | `docs/policy/release.md` | Versioning, compatibility, release integrity and immutability, release documentation, proportionate gates, publication controls, completion, and required versus optional checks. | Repository-specific commands, product installation guidance, CLI version semantics, historical release summaries, and CI implementation detail. |
+| Open source licensing and attribution policy | `docs/policy/oss.md` | License defaults and author choices, COPYRIGHT and attribution formats, license/notice links, discoverability, maintenance, and concrete exceptions. | Component entries, license texts, release commands, and dependency security review. |
+| Project copyright and license grant | `COPYRIGHT` | Project identity, copyright holders and years, SPDX expression, grant, separately licensed document scope, warranty disclaimer, and third-party statement. | Complete license texts and upstream component attribution. |
+| Project license texts | `LICENSE` | Complete project and incorporated companion license texts, with required project-specific fields. | General licensing policy and upstream component attribution. |
+| Upstream component attribution | `docs/oss/attribution.md` | House Format component entries: identity, material scope and modifications where applicable, copyright, license, required notices, and license, notice, and source links. | General attribution policy, exception reasoning, research narratives, compliance commentary, and complete standard license texts. |
+| Standard license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by applicable entries, including copied documentation. | Project-specific upstream notices, attribution prose, and policy interpretation. |
+| Repository-specific release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, validation and publication commands and automated guards, asynchronous deliverables, delivery status, optional consumer verification, and recovery. | General release requirements, product installation guidance, historical release summaries, and current compatibility contracts. |
+| CLI contract (if applicable) | `docs/cli.md` | Standard commands, arguments, flags, invocation semantics, report contracts, and status semantics. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
+| Exported Go API (when implemented) | Go declarations and GoDoc | Exact symbol contracts, errors, ownership, and lifecycle semantics. | Consumer walkthroughs, CLI contracts, integration protocols, and internal mechanics. |
+| Consumer guidance for the public Go API (if applicable) | `docs/consumers/` | Task-oriented public Go API usage, minimal examples, and consumer responsibilities. | HTTP wire semantics, external protocol contracts, internal implementation detail. |
+| Integration contracts for external components (if applicable) | `docs/integrations/` | External formats and protocols, upstream and downstream contracts, logical output paths and schemas, media types, and compatibility. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
+| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
+| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
+| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
+| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
+| Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
+| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
+
+Create supporting documents when substantive content is available for an
+implemented responsibility. Go API, CLI, consumer, integration, internal,
+example, and release-procedure documents become owners as their implementation
+lands; do not create empty shells. ADRs may record accepted decisions before
+implementation. The roadmaps retain implementation status and proposals.
+
+## Boundary Rules
+
+### Orientation
+
+Link among orientation, architecture, and internal documents; maintain each
+package or behavior description in its canonical owner.
+
+### Go API, CLI, And Owning Libraries
+
+Go declarations and GoDoc own exact exported contracts. Consumer guides explain
+tasks and link to those declarations. CLI documentation owns CommandKit's
+implemented standard syntax, reports, and status semantics, even though CommandKit
+is a library used by applications.
+
+ConfigKit and PromptKit own configuration schemas, resolution and inspection
+semantics, and prompt formats. Document how CommandKit exposes those capabilities
+and link to their owning contracts rather than maintaining duplicate references.
+Application runtime operations and custom-command domain behavior remain with
+the consuming application.
+
+### Releases
+
+The release policy defines requirements and invariants that every release must
+satisfy. The repository-specific release procedure defines the commands and
+workflow maintainers use to satisfy that policy. Release notes record history
+at immutable tags. Maintain current behavior in its canonical documentation,
+update it with the corresponding behavior changes, and keep release procedures
+consistent with adopted policy.
+
+### Project Licensing And Upstream Attribution
+
+README and release documents link to the canonical licensing and attribution
+materials under the [OSS policy](oss.md). The release procedure owns URL
+construction and publication mechanics.
+
+### Contracts And Implementation
+
+GoDoc, CLI, and integration documents define externally observable shapes and
+semantics. Internal docs explain how CommandKit implements or consumes those
+contracts. Internal docs may name a field, file, or protocol to identify a
+dependency, but must link to its canonical contract for the definition.
+
+### Security Topics
+
+This policy owns what documentation and examples may contain. Architecture owns
+selected security invariants. Owning library and application contracts define
+credential supply and runtime handling. Internal docs own implementation
+mechanisms only.
+
+## Architecture Decision Records
+
+Use sequentially numbered ADR filenames such as
+`0001-record-architecture-decisions.md`. Follow the lightweight Nygard format:
+
+1. title;
+2. status;
+3. date;
+4. context;
+5. decision;
+6. alternatives considered;
+7. consequences.
+
+Treat the decision content of an accepted ADR as immutable. When a decision
+changes, create a new ADR and update the earlier ADR's status to superseded.
+Rejected architectural alternatives belong in the ADR; rejected product ideas
+belong in the roadmap.
+
+## Maintenance
+
+When behavior changes, update its canonical owner in the same change. If
+ownership moves, remove the old definition and replace it with a link where
+navigation remains useful.
+
+Before completing documentation work:
+
+- verify affected behavior and examples;
+- check commands, flags, fields, defaults, schemas, and paths against their
+  implementation;
+- keep unimplemented behavior in the roadmap, subject to the ADR exception;
+- remove stale references and validate links;
+- confirm that non-owning documents summarize and link rather than redefine;
+- confirm that no secrets or sensitive private data were added.

docs/policy/meta.md

@@ -0,0 +1,27 @@
+# Policy Set Provenance
+
+**Base Policy Version:** 1.0
+
+**Last Updated**: 2026-10-06
+
+**Upstream Source:** [meta.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md)
+
+## Origin And Local Authority
+
+This repository's policy set is adapted from
+[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy).
+The adopted local policies govern work in this repository. Upstream revisions
+become local policy through deliberate adoption, preserving local decisions.
+Each policy's `Upstream Source` identifies its adopted baseline.
+
+## Adoption And Updates
+
+For policy adoption, upstream revision reviews, and updates, consult the
+[upstream adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
+That guide and the reference example collection are maintained upstream and
+accessed through links. Keep discovery links pointed at the current upstream
+project and guide; keep adopted-source and example links pinned to commits.
+
+The local [developer guide](../development.md) routes tasks to applicable
+policies. Formal credit and licensing notices for the copied policy material
+belong in the local [attribution document](../oss/attribution.md).

docs/policy/oss.md

@@ -0,0 +1,229 @@
+# Open Source Licensing And Attribution Policy
+
+**Base Policy Version:** 1.8
+
+**Last Updated**: 2026-10-06
+
+**Upstream Source:** [oss.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md)
+
+## Purpose And Scope
+
+This policy defines project licensing conventions and a repeatable House Format
+for upstream attribution and license notices. It covers the project's own code
+and upstream components incorporated into or distributed with the application
+or library, including relevant transitive dependencies and copied code,
+documentation, or assets.
+Determine treatment from the component's terms and actual use.
+
+Consulting development guidance or using tooling alone does not require an
+attribution entry. Copying or adapting documentation for inclusion in the
+repository is different: preserve its applicable attribution and license terms.
+A material's role as development guidance does not exempt copied documents.
+Apply any express permissions for attribution-free reuse of example formatting.
+
+The baseline is a publicly available source repository with releases published
+alongside it. The format is independent of language, forge, and build system.
+It does not require attribution for every development tool, establish license
+compatibility, or resolve every obligation arising from use or distribution.
+
+## CommandKit Licensing Scope
+
+CommandKit's project grant is `LGPL-3.0-or-later`, recorded in root `COPYRIGHT`.
+Root `LICENSE` retains the complete LGPL v3 text and its incorporated GPL v3 text.
+Adapted repository policies and the copied orientation and reading-guide material
+have separate CC-BY-SA-4.0 scope identified in `COPYRIGHT` and the attribution
+entry. That scope does not relicense independently supplied knowledge-graph
+instructions or unrelated code and documentation.
+
+The source project is [CommandKit](https://gitea.maximumdirect.net/eric/CommandKit).
+Concrete release-channel URLs and publication mechanics belong in the release
+procedure when it is implemented. Cobra and pflag have been selected as the
+initial backend, but are not yet incorporated dependencies. Add their notices
+and applicable license texts when actual versions are introduced.
+
+## Canonical Locations
+
+The [documentation policy](documentation.md) assigns ownership:
+
+- `COPYRIGHT`: project name, copyright statements, SPDX expression, grant,
+  warranty disclaimer, and third-party statement.
+- `LICENSE` contains the complete, unmodified project license text, including
+  incorporated companion text. Dependency attribution does not relicense the project.
+- `docs/oss/attribution.md`: canonical component entries.
+- `docs/oss/licenses/`: complete, verbatim standard and applicable companion texts.
+
+Use recognizable license filenames, such as `Apache-2.0.txt` or `LGPL-3.0.txt`.
+A shared standard text may serve multiple entries. Keep explanations outside
+license texts and preserve distinct versions and exceptions.
+
+## Upstream Reference Examples
+
+Use the commit-pinned upstream examples to create actual project notices.
+The selected baseline's [standard license reference collection](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/oss/licenses/README.md)
+provides source texts.
+Retain their links and keep the example collection upstream; keep applicable
+license texts locally as specified above.
+
+## Project Licensing
+
+Unless the author specifies otherwise, use **GPL version 3 or later**
+(`GPL-3.0-or-later`) for applications and **LGPL version 3 or later**
+(`LGPL-3.0-or-later`) for libraries. An author's explicit choice takes precedence:
+for example, a one-off script may use MIT. Such a choice requires no exception
+rationale, additional approval, or compensating controls under this policy.
+
+These defaults guide new license selection. Adopting this policy does not
+relicense existing code or override third-party terms. Preserve an existing
+license unless the author deliberately changes it. For mixed-purpose projects,
+follow the author's selected scope rather than inferring different licenses for
+individual packages.
+
+Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/application/COPYRIGHT)
+or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/library/COPYRIGHT)
+to create the project’s root `COPYRIGHT` file.
+Use verified project names, contribution years, and copyright holders.
+For another selected license, adapt the grant, SPDX expression, disclaimer, and
+text references together to reflect the author's selected grant.
+
+For GPLv3 projects, copy the complete GPLv3 text into `LICENSE`. For LGPLv3
+projects, place the complete LGPLv3 text followed by the complete GPLv3 text in
+`LICENSE`; the LGPL incorporates the GPL terms. Keep the texts unmodified and
+place project-specific statements in `COPYRIGHT`. For the default grants, the
+grant and SPDX expression in `COPYRIGHT` must expressly identify `or-later`;
+follow the author’s choice if a different grant is selected.
+
+For other licenses, provide their complete text and any required project-specific
+fields; the standard reference collection remains unchanged. Keep `COPYRIGHT`,
+`LICENSE`, SPDX expressions, and README descriptions consistent with the actual
+grant. This convention introduces no blanket requirement for per-file headers;
+preserve notices or add them where the applicable terms require them.
+
+Identify separately licensed documentation or assets in the project grant, with
+links to their attribution and license information. An application's default
+code license does not override the terms of incorporated documentation.
+
+## Upstream Attribution House Format
+
+Begin `docs/oss/attribution.md` with `# Open Source Attribution Notices`,
+followed directly by component entries. These comprise the complete document.
+
+Each entry presents these five fields in order, with blank lines between them:
+
+1. **Project name** as a level-two heading. An optional identification paragraph
+   may follow, such as `Selected module: MODULE at VERSION.` with the module and
+   version in backticks. For copied documentation, a concise `Material:` sentence
+   may identify the affected files and whether they were adapted or copied
+   without modification. A factual qualifier such as `(transitive dependency)`
+   is permitted. Limit optional identification prose to factual component and
+   material scope.
+2. **Upstream copyright statement or statements**, preserving their wording.
+   Put multiple statements in separate paragraphs. Include this field when the
+   selected upstream source supplies an applicable statement; otherwise, omit it.
+3. **SPDX license identifier or expression**, when applicable, using
+   `SPDX-License-Identifier: EXPRESSION`.
+4. **License and notice links**, beginning `License and notices:`, separated
+   by ` | `, and ending with a period. Label local standard texts by license
+   name, such as `MIT` or `Apache 2.0`. Label upstream files by their actual
+   filenames, such as `COPYRIGHT`, `LICENSE`, `NOTICE`, or `PATENTS`.
+5. **Source repository link**, rendered exactly as `[Source](COMMIT_URL).`.
+
+Use the upstream [attribution example](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/attribution.md)
+to create the project’s `docs/oss/attribution.md`.
+The example illustrates omitted fields and multiple copyrights and licenses.
+Replace the uppercase placeholders and illustrative URLs with actual component
+information. Local license links are relative to the destination
+`docs/oss/attribution.md`; copy the applicable texts into its `licenses/`
+directory. Do not copy example entries for components the project does not use.
+
+These are five fields, not a line limit. Omit the SPDX field when no applicable
+identifier exists; identify nonstandard terms through the linked text. Preserve
+licensing alternatives and exceptions, and record a selected option when
+relevant through the factual license identification. Do not invent an identifier
+or silently resolve an unsettled licensing choice.
+
+Keep entries factual. Do not add agent-authored explanations of license
+expressions, file-level license scope, research performed, retained source
+notices, or compliance conclusions. Avoid filler such as "none is invented
+here" and embellished link labels such as "upstream LICENSE", "additional
+patent grant", or "at the imported commit". Preserve actual required upstream
+content; this rule excludes editorial additions, not required notices. Policy
+interpretation and exception reasoning belong in the adopted OSS policy or an
+appropriate decision record, not the attribution document.
+
+## License Texts And Upstream Links
+
+Link standard license texts to their local copies. Link project-specific
+notices to their upstream copies. Every upstream repository or notice link must
+identify the exact commit corresponding to the
+imported version, including the selected source revision for copied material.
+
+Classify material according to its contents. An upstream `LICENSE`,
+`COPYING`, or similar file may contain project-specific notices or exceptions
+in addition to standard wording. Link both the local standard text and the
+commit-specific upstream file when needed. Make companion license texts directly
+reachable from the entry.
+
+For project-specific license and attribution material, this policy accepts
+direct links to the applicable upstream texts as satisfying reproduction,
+inclusion, or copy requirements. This is the adopted house interpretation.
+Agents must apply it without adding local-copy requirements or seeking repeated
+approval solely because a license uses those terms.
+
+This interpretation concerns notice reproduction. Concrete obligations such as
+marking modified files or supplying corresponding source receive their own
+applicable treatment. Preserve required notices already present in incorporated
+source files; the central attribution entry does not authorize stripping them.
+
+## Discoverability
+
+End the project's README with two friendly statements linking to its actual
+grant in `COPYRIGHT` and the attribution document. For example, for a project
+with the stated license:
+
+```markdown
+PROJECT_NAME is licensed under the [LGPL v3.0 or later](COPYRIGHT).
+
+[Open Source attribution notices](docs/oss/attribution.md) are available.
+```
+
+Each new checked-in release document and its hosted download page must end
+with links whose visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute
+URLs to those files at the release's immutable tag or corresponding immutable source
+revision so the links work in both locations. This release navigation is distinct
+from upstream component links, which must use the imported commit.
+
+Reuse the checked-in release document as the hosted release body where supported.
+The release procedure owns concrete URLs and publication mechanics for delivering
+the links through the selected channel. Do not maintain duplicate notice lists.
+These conventions do not by themselves require separate downloadable license
+assets, source bundles, or a different binary package format.
+
+## Maintenance And Exceptions
+
+Update project licensing statements together when the author changes the grant
+or its scope. Update upstream notices in the change that adds, removes, upgrades,
+copies, or changes the distribution of a relevant component. Check the selected source's license
+and notices rather than assuming they are unchanged. Update affected entries,
+commit links, and texts; retain historical versions through Git.
+
+Check affected statements, faithful standard-text copies, and link destinations
+as part of ordinary change review. For a future release tag, check intended file
+paths against the candidate source; the tag need not resolve remotely before
+publication. Do not add publication-time network checks, CI polling, recurring
+legal sign-offs, mandatory scanners, or a full software bill of materials merely
+to implement this policy.
+
+Use the House Format routinely. Raise an exception only for a concrete obligation
+or unresolved rights question it does not address, including any arising from a
+particular distribution channel. Record the issue and selected treatment in the
+adopted OSS policy or an appropriate decision record. Attribution entries
+contain the resulting factual identification and required material, without
+repeating that reasoning. Resolve the issue before the affected use or
+distribution without reopening settled choices.
+Common ownership of projects is neither required nor a blanket exception.
+
+Apply the formatting convention prospectively. Do not rewrite published tags,
+notes, binaries, or checksums to retrofit it. Address actual omissions deliberately
+under the applicable terms and the [release correction policy](release.md#immutability-and-failure-recovery).
+Ordinary attribution maintenance and release links are preparation work, not new
+release approval gates.

docs/policy/release.md

@@ -0,0 +1,219 @@
+# Release Policy
+
+**Base Policy Version:** 1.4
+
+**Last Updated**: 2026-10-06
+
+**Upstream Source:** [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md)
+
+## Purpose
+
+This policy defines a proportionate workflow for validating and publishing an
+intended source revision under a fresh version. Releases should require little
+routine intervention, avoid repeated work, and preserve published contents.
+
+The repository-specific commands belong in `docs/release.md`. Historical release
+summaries belong in `docs/releases/`. The procedure must agree with the adopted
+policy and link to it rather than introduce additional release requirements.
+
+## CommandKit Release Scope
+
+CommandKit releases source-only Go modules. Standard CLI behavior is exposed by
+consuming applications; CommandKit does not declare binary deliverables or a
+cross-platform build matrix. The publication procedure and its tooling will be
+introduced with a releasable module. Do not create a placeholder publisher or
+claim that a release command exists before implementation.
+
+ReleaseKit may provide future publication mechanics, but its integration has not
+been selected. Adopt concrete checks for CommandKit's risks; do not copy another
+repository's platform commitments or validation gates.
+
+## Release Model And Completion
+
+A source release identifies one exact committed source revision through an
+immutable version tag and a version-matched, checked-in release note. The
+primary release branch is `main` unless the adopted policy specifies otherwise.
+The procedure must name the authoritative publication remote.
+
+A successful push of the intended tag, with its source commit available on the
+authoritative primary branch, completes the release. The source commit may be
+pushed before the tag or published together with it through an atomic push.
+The procedure must choose and document the supported approach.
+
+Release commands must finish at successful publication. They must not wait for
+or poll CI, require successful CI status, inspect downloadable artifacts, or
+check consumer installation or Go module availability as completion gates.
+A failed or ambiguous push requires resolving the authoritative remote state
+before declaring success or retrying; successful pushes do not require a
+separate remote read-back gate.
+
+Repositories may publish source only. Additional binaries, images, packages,
+checksums, or other declared deliverables may be published asynchronously from
+the tagged source. The procedure must identify those deliverables and the
+responsibility of their automation. Published deliverables must be traceable
+to that source and identify the same version.
+
+Track source-release completion and artifact delivery separately. Report delivery
+failures and optional investigations under artifact-delivery status.
+
+## Versioning And Compatibility
+
+Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
+no leading zeroes. Prereleases require an explicit adopted policy defining
+their format and use.
+
+The selected version must be unused locally and on the authoritative remote.
+Do not require queries to every configured remote or publication service.
+A version known to have already been published must not be reused, even if the
+normal guards do not inspect that channel. Adding a distribution channel
+requires a deliberate update to the policy and procedure where needed.
+
+For releases at or after `v1.0.0`:
+
+- a major release may make intentional incompatible changes;
+- a minor release may add backward-compatible behavior; and
+- a patch release may make backward-compatible fixes.
+
+Before `v1.0.0`, a minor release may change a documented public, operational,
+configuration, data, integration, or compatibility contract when the release
+note explains the impact and required consumer action. A patch release must
+not intentionally break those contracts within its minor line.
+
+CommandKit compatibility includes its public Go API and published standard CLI
+contracts: commands, parsing, scopes, reports, YAML document semantics, and
+status behavior. A backend upgrade can be incompatible even with unchanged Go
+signatures. Initial application migrations may intentionally replace divergent
+consumer conventions; that does not waive compatibility obligations for later
+published CommandKit contracts.
+
+Additional compatibility promises and deliberate exceptions belong in the
+adopted policy or canonical contract documentation. Release notes explain
+changes; they do not redefine current compatibility contracts.
+
+## Release Documentation And Preparation
+
+Every new release must include `docs/releases/<version>.md` in the tagged
+source tree. Use the complete version tag as the filename and begin with a
+title containing the product name and that exact version.
+
+Include a short summary and any relevant compatibility impact or upgrade
+instructions. Choose sections suited to the release and keep the note
+proportionate to the change.
+
+Keep exact current contracts in their canonical documents and update affected
+documentation with the behavior change. Link to those documents from the note
+where useful. If annotated tags are used, derive their summary from the
+checked-in note.
+
+Include the release footer defined by the [OSS policy](oss.md#discoverability)
+in each new release document and preserve it on the hosted download page. The
+release procedure defines the concrete URLs and publication mechanics. Prepare
+these links with the release note; they do not add a network check or approval
+gate.
+
+Handle version selection, release-note content, and retirement of completed
+roadmaps during preparation. Preserve planned and deferred work and repair
+affected links when retiring roadmaps. Reuse ordinary change review for
+unintended files, credentials, and private data. Scope release-content review
+to the tagged source.
+
+## Candidate Validation
+
+Provide one publication command that validates the final committed candidate,
+checks publication state, and publishes the intended refs. A validation-only
+mode or command may be provided for diagnosis, but must not be a required step
+before publication repeats the same checks.
+
+Run the complete deterministic, offline default test suite once for the final
+candidate, following the [testing policy](testing.md). For repositories that
+publish builds, verify the required build targets. Select those targets for
+the application's actual support commitments; native testing on each platform
+and access to particular hardware are not default release prerequisites.
+
+Additional gates must address a concrete risk that the existing checks do not
+adequately cover. Do not automatically require linting, race testing, module
+hygiene audits, documentation audits, credential scans, example validation, or
+expanded platform matrices solely because they are possible. Retain such
+checks when their distinct protection justifies their cost. A one-time migration
+check must not silently become a permanent release requirement.
+
+Release tests must not require real credentials, mutable application services,
+paid APIs, provider probes, or inference calls. The procedure may describe dependency
+preparation separately from offline validation.
+
+Avoid duplicate validation across release phases. Successful checks for the
+same final candidate need not be repeated solely to satisfy another phase;
+any reuse must clearly apply to that exact candidate. Persistent validation
+caches are not required. If the candidate changes, validate the new candidate.
+Cheap publication-state checks may be repeated immediately before pushing
+because local or remote state may have changed during validation.
+
+Automate mechanical guards. Human review gates are strongly disfavored: add one
+only through an explicit project-specific policy decision explaining the
+concrete risk and why ordinary change review or automation is insufficient.
+Do not add routine confirmations for checks the command can perform itself.
+
+## Publication Guards
+
+Automate the checks needed to publish the intended source under a fresh version:
+
+- the version has the adopted format and is unused locally and on the
+  authoritative remote;
+- the worktree and index are clean on the primary release branch;
+- the source being published is the exact candidate that passed validation,
+  including its matching release note;
+- the remote primary branch already identifies that candidate, or an atomic
+  source/tag push will advance it to that candidate without discarding remote
+  history; and
+- the tag identifies the validated candidate and only the intended refs are
+  published.
+
+Fetch the authoritative branch and tag state as needed for these checks.
+Do not force branch or tag updates to bypass a failed guard. Publish explicit
+refs rather than all local tags. Do not require CI success, publication-service
+availability checks, or a separate manual confirmation for each guard.
+
+## Immutability And Failure Recovery
+
+Published version tags and published contents are immutable. Do not move,
+overwrite, recreate, or delete a published tag, or replace a published artifact,
+checksum, signature, provenance statement, or release note under that version.
+The checked-in note at the immutable tag is that release's historical record.
+
+If validation fails before publication, correct and commit the candidate and
+rerun the publication command. If a push fails or its outcome is ambiguous,
+inspect the authoritative remote before retrying. Remove an unpublished local
+tag only after confirming it was never published or used by a release channel.
+An unavailable remote leaves publication status unknown; do not overwrite a tag
+to resolve uncertainty.
+
+Transient network, authentication, CI, or consumer-availability failures do not
+by themselves require a new version. Asynchronous delivery may be retried from
+the same immutable tag. Missing artifacts may be published later, provided
+existing published contents are not replaced and the additions remain consistent
+with the tagged source and any already-published checksum manifest. If that
+cannot be achieved, publish a new version.
+
+A defect requiring changes to published source or contents requires a corrected
+commit, a new semantically appropriate version, a matching release note, and
+the release procedure again. Leave the original release intact. A channel's
+yank, deprecation, or advisory mechanism may warn consumers away from a defective
+release without replacing its contents or reusing its version.
+
+## Repository Release Procedure
+
+Maintain `docs/release.md` as a short, executable maintainer runbook. It must
+identify:
+
+1. prerequisites, primary branch, and authoritative remote;
+2. version and release-note preparation;
+3. one publication command with its selected local checks and automated guards;
+4. declared deliverables, required build targets, and automation responsibilities;
+5. the successful-push completion point and separately reported delivery status;
+   and
+6. failure handling, ambiguous-push recovery, and asynchronous delivery retries.
+
+Use copyable commands where practical. Keep optional diagnostics and consumer
+verification clearly optional. The procedure must not turn preparation work,
+ordinary change review, or post-publication investigation into additional
+release gates.

docs/policy/testing.md

@@ -0,0 +1,295 @@
+# Testing Policy
+
+**Base Policy Version:** 1.3
+
+**Last Updated**: 2026-10-06
+
+**Upstream Source:** [testing.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md)
+
+## Purpose
+
+Our tests exist to make **incorrect changes expensive and correct changes cheap**.
+
+We optimize for sufficient confidence in important behavior while minimizing friction on future development.
+
+## Every test has a cost
+
+Every test has an immediate and continuing cost: writing, review, execution,
+diagnosis, fixture maintenance, and updates when legitimate behavior changes.
+Tests can also constrain refactoring, duplicate policy, and add failure noise.
+
+A test is warranted only when the confidence it provides justifies these costs.
+Evaluate that tradeoff at two levels:
+
+1. **Per test:** What realistic defect does this test detect, how consequential would that defect be, and is that protection worth the test's lifetime cost?
+2. **Across the suite:** Does this collection provide materially more confidence than a smaller, simpler suite would?
+
+Some friction is intentional. Tests should make dangerous changes—such as breaking compatibility, corrupting data, violating security boundaries, or reintroducing subtle bugs—require deliberate review. Keep ordinary internal changes inexpensive.
+
+Evaluate maintenance cost against the specific failure being protected. When omitting a plausible test, be able to state why the protected failure is low-risk, already covered, obvious, reversible, or cheaper to detect elsewhere. For consequential, subtle, or difficult-to-observe behavior, the presumption should favor testing.
+
+## Default testing style
+
+Use a **classical/Detroit-style** approach:
+
+- Test observable behavior, resulting state, contracts, and invariants.
+- Use real internal collaborators when they are fast and deterministic.
+- Use fakes, stubs, or mocks primarily at expensive, nondeterministic, destructive, or external boundaries.
+- Prefer package-level behavioral tests over tests coupled to private helpers or internal call sequences.
+- Treat exact collaborator interactions as testable behavior only when the interaction itself is a requirement.
+
+Examples of appropriate seams include clocks, randomness, subprocesses, remote APIs, object storage, email, and paid LLM calls.
+
+## Test execution requirements
+
+CommandKit is a library that defines CLI behavior. Its public consumer boundary
+is the root facade, and backend integration belongs behind the internal adapter.
+Select validation proportionate to the change. The developer guide owns concrete
+commands as implementation lands; there is currently no Go suite. Prose-only
+policy adoption requires document review, not new tests or checker code.
+
+Tests in the default suite must be deterministic, offline, and independent of real credentials. They must not invoke paid APIs or depend on mutable external services. Tests that require live infrastructure must be explicitly opt-in and clearly separated from the default suite.
+
+Control clocks, randomness, environment variables, and other process-global or machine-specific state when they affect behavior. Tests should be safe to run repeatedly and alongside other tests without depending on execution order or state left by an earlier test.
+
+## What deserves tests
+
+For CommandKit, prioritize the following as the corresponding behavior is
+implemented:
+
+- Registration collisions, reserved-family ownership, and nested custom commands.
+- Typed flag and operand mapping, explicit presence of empty/false/zero values,
+  and fresh state across repeated invocations.
+- Help and command discovery without provider loading or runtime construction.
+- Provider failures, cancellation, output errors, and preservation of application
+  outcomes and public error identity.
+- Selected inspection/report contracts, including native YAML and document order
+  for `config show --scope all`.
+- Public type ownership and the internal Cobra/pflag import boundary selected by
+  [ADR 0003](../adr/0003-public-facade.md).
+
+Use external-package consumer tests for facade semantics and real backend
+integration where correctness depends on that interaction. Internal package
+tests own focused mechanisms. Do not retest the dependencies' complete suites.
+Boundary checks protect selected architectural constraints; behavioral evidence
+protects invocation semantics and ownership through conversions.
+
+Do not infer concurrent-dispatch support from fresh invocation state. Test
+concurrency guarantees only if deliberately selected. Coverage targets, race
+testing, static analysis, example gates, and platform matrices require their own
+risk justification; another library's workflow does not establish them here.
+
+To the extent the following features are present in the application, prioritize tests for:
+
+1. Public and package-level contracts.
+2. Domain rules and important invariants.
+3. Boundary conditions and malformed input.
+4. Failure handling, cancellation, retries, recovery, and partial success.
+5. Serialization, schemas, compatibility, and round trips.
+6. Previously observed or plausible regressions.
+7. Representative integration and end-to-end workflows.
+
+A package-level contract comprises behavior relied upon by another package or major collaborator.
+
+Choose tests for requested behavior and established contracts. Tests must not
+introduce new restrictions, guarantees, or threat scenarios merely because they
+could be asserted. Follow the [agent policy](agents.md) when deciding whether a
+behavior belongs to the contract; current implementation behavior alone is not
+sufficient authority.
+
+For established behavior involving **data integrity, destructive operations,
+compatibility, security, concurrency, idempotency, or recovery**, favor durable
+tests for realistic failures whose consequences warrant protection. Identify
+the failure and the existing contract it would violate. These categories call
+for attention, not an automatic test inventory or permission to strengthen the
+application's guarantees. Account for protection already provided at other layers.
+
+Do not add tests merely because a function, branch, or line exists. Do not add a test when the same meaningful risk is already adequately protected elsewhere.
+
+## Choose the right test boundary
+
+Choose the narrowest stable boundary that expresses the behavior clearly and
+provides durable confidence with minimal incidental coupling.
+
+This is often the package API, but it may instead be:
+
+- a smaller pure function when dense domain logic is most clearly isolated there;
+- a package-level operation when several internal collaborators jointly produce the behavior; or
+- a larger integration boundary when correctness emerges from interaction with a real dependency.
+
+## Test behavior, not implementation
+
+A test should protect a selected decision, contract, or invariant.
+
+A test is suspect when it primarily detects changes to private constants or
+helpers, equivalent operation ordering, incidental formatting, equivalent
+algorithms, or internal structure that preserves behavior.
+
+Behavioral tests should normally remain stable through internal refactoring that preserves the contract.
+
+## Expected effects of different changes
+
+Use the following expectations when evaluating test failures and test maintenance:
+
+| Change | Expected effect on tests |
+|---|---|
+| Internal refactor that preserves behavior | Existing tests should normally remain unchanged and continue to pass. |
+| Change to an internal default with no contractual significance | Behavioral tests should normally remain unchanged; tests should derive expectations from configuration or relationships rather than duplicate the old value. |
+| Intentional change to public behavior, policy, schema, or compatibility guarantees | The relevant tests should be reviewed and changed deliberately. |
+| Accidental violation of a contract or invariant | Tests should fail; fix the production code rather than rewriting the tests to accept the defect. |
+
+A test failing is not the same as a test needing to be edited. Many tests may correctly fail because of one production defect. The maintenance smell is a correct internal change that requires unrelated expectation updates throughout the suite.
+
+## Separate mechanism from policy
+
+Derive expectations from test-controlled configuration and relationships.
+
+For this example, assume the selected contract rejects a request to start more
+processes than a configured limit. Do not encode its production default indirectly:
+
+```go
+// Production default:
+const maxConcurrency = 4
+
+// Brittle test:
+err := startProcesses(5)
+require.Error(t, err)
+```
+
+Instead, test the mechanism relationally:
+
+```go
+const limit = 2
+runner := NewRunner(limit)
+
+require.NoError(t, runner.Start(limit))
+require.ErrorIs(t, runner.Start(limit+1), ErrTooMuchConcurrency)
+```
+
+For this selected contract, the test should prove:
+
+- the configured limit is accepted; and
+- one beyond the configured limit is rejected.
+
+Rejection is not a general requirement for concurrency control. If the selected
+contract queues excess work or limits active workers while accepting larger
+batches, test that behavior instead. Do not add rejection or a configurable
+limit solely to reproduce this example.
+
+The production default should be tested exactly only when its literal value is itself a public, operational, safety, protocol, or compatibility requirement.
+
+Apply the same rule to limits, timeouts, capacities, retry counts, and ranges: test relationships and behavior.
+
+For established concurrency limits, distinguish these behaviors where the contract requires them:
+
+1. **Configuration handling:** values are accepted or rejected according to the selected contract.
+2. **Runtime enforcement:** observed peak concurrency never exceeds the configured limit.
+
+Use a test-controlled limit and measure the behavior relative to that limit.
+
+## Assign each behavior a test owner
+
+Where these layers exist, assign ownership as follows:
+
+- Parser tests own parsing cases.
+- Validator tests own validation rules.
+- Domain tests own transformations and invariants.
+- Adapter tests own external integration behavior.
+- Orchestrator tests own coordination and failure propagation.
+- CLI tests own argument and configuration mapping.
+- End-to-end tests prove that representative assembled workflows work.
+
+Give each layer its distinct responsibility and keep expectation updates localized to the contract being changed.
+
+## Use test doubles deliberately
+
+Choose the least elaborate test double that provides the required control or observation.
+
+As a default:
+
+1. Prefer real collaborators when they are fast and deterministic.
+2. Use small in-memory fakes when realistic stateful behavior is helpful.
+3. Use stubs when a dependency only needs to provide controlled responses.
+4. Use mocks when the interaction itself is contractual.
+
+Mocks are appropriate when the contract includes facts such as:
+
+- a notification is sent exactly once;
+- a transaction is committed only after successful writes;
+- cancellation reaches a subprocess;
+- an expensive API is called no more than once; or
+- a security audit event is emitted.
+
+## Go-specific guidance
+
+Select techniques by behavior and risk:
+
+- table-driven tests for meaningful behavioral categories and boundaries;
+- `t.TempDir()` for real filesystem behavior;
+- `httptest.Server` for realistic HTTP interactions;
+- fuzz tests when exploring broad input spaces, such as parsers or path handling, adds useful protection beyond representative cases;
+- golden files only when the complete output is intentionally stable;
+- integration tests where correctness depends on component interaction; and
+- a small number of representative end-to-end tests when assembled workflows expose meaningful risks not adequately covered at narrower boundaries.
+
+Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields. Use exact error-wording assertions only when the wording is contractual.
+
+At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Use complete diagnostic snapshots only when the wording is contractual.
+
+Golden-file updates must require an explicit local flag. CI must not update golden files automatically, and reviewers must inspect the semantic diff before accepting an update.
+
+Keep tests readable and direct. Size test helpers and fixture frameworks to the maintenance benefit they provide.
+
+## Coverage
+
+Use coverage to locate untested critical branches and unexpectedly weak packages. Evaluate test quality through meaningful behavioral protection and choose coverage according to risk.
+
+Pure domain logic will often warrant higher coverage than CLI wiring or external adapters. Uneven coverage is acceptable when it reflects risk.
+
+## Regression tests
+
+A bug fix should normally include a regression test that fails before the fix and passes afterward.
+
+Retain the test when the defect could realistically recur and its consequences justify the ongoing cost. Prefer the narrowest durable test of the violated contract or invariant.
+
+Remove or consolidate a test when the underlying design has made recurrence impossible, its protection is redundant, or a stronger invariant test subsumes it.
+
+## Deleting or rewriting tests
+
+Delete or rewrite tests when maintenance cost exceeds their continuing
+protective value.
+
+Strong candidates include tests that:
+
+- require updates after harmless internal changes;
+- assert incidental private constants or snapshot large amounts of incidental output;
+- verify mock choreography rather than outcomes;
+- duplicate policy across layers, retest trivial helpers covered by package
+  behavior, or protect risks covered more effectively elsewhere;
+- are flaky, misleading, obsolete, or disproportionately expensive to diagnose; or
+- no longer correspond to a plausible failure mode.
+
+Several brittle tests may encode one genuine requirement. Consolidate them into one durable behavior-level or invariant test.
+
+## Reviewing a proposed test
+
+Use the following questions when a proposed test needs closer evaluation. Significant test additions should be reviewable against them; written answers are optional for routine tests.
+
+1. Which requested behavior or established contract does it protect, and what realistic defect would violate it?
+2. How likely and consequential is that defect, and is it already protected elsewhere?
+3. What is the narrowest stable boundary that can test it clearly?
+4. Would a correct internal refactor or a change to an incidental default require test edits?
+5. Does its confidence justify its maintenance, execution, and diagnostic cost, or would a smaller test suffice?
+
+## Definition of sufficient
+
+A test suite is sufficient when:
+
+- important requested behavior and established contracts are protected against realistic, consequential failures;
+- boundaries and component interactions have coverage where they introduce meaningful risks not protected elsewhere;
+- failures provide useful, distinct signals;
+- tests usually remain stable through legitimate internal changes; and
+- additional tests would mostly repeat existing protection or preserve inconsequential implementation details.
+
+Reassess sufficiency as the application, its users, and the consequences of
+failure evolve.

docs/roadmap/01-cli-plan.md

@@ -0,0 +1,819 @@
+# CommandKit CLI standard proposal
+
+Status: proposed; no commands in this document are implemented by CommandKit.
+
+Date: 2026-10-06.
+
+This proposal defines the command suite, operator behavior, and ownership boundary
+recommended for CommandKit. Audita, Narratio, Notarius, and Scriptorium provide
+evidence, rather than compatibility requirements. Adoption is expected to produce
+breaking changes. The decisions recorded below are accepted; other recommendations
+remain proposed. Implementation details and exact Go API declarations remain
+future work.
+
+### Accepted planning decisions
+
+- Use namespace/resource first: `app config show` and `app promptkit show`.
+  Whether the first noun describes a resource or a library namespace does not
+  change the command grammar or its ownership boundary.
+- Put PromptKit definition inspection under the single `promptkit` family.
+  CommandKit does not reserve the root `prompt` and `profile` names.
+- Support `config show --scope all`, with the application configuration followed
+  by the PromptKit configuration when registered, as separate YAML documents.
+- Defer JSON output from the initial implementation. YAML supports automated
+  consumption as well as operator inspection; JSON may never be needed and is
+  not a promised later milestone. JSON Pointer remains the configuration path
+  syntax and is independent of report format.
+
+## 1. Purpose and ownership
+
+**Recommendation:** CommandKit owns the entire `config` command family, root help,
+and version reporting. It also offers the standard `promptkit` inspection family
+for applications that integrate PromptKit. Applications own commands
+outside these families, such as `narratio session restore`, `narratio publish`,
+`audita process`, and `scriptorium serve`.
+
+Ownership includes command names, accepted flags and arguments, defaults, help,
+report shapes, diagnostic presentation, streams, and exit behavior. Applications
+provide configuration schemas, source acquisition, domain resolution, validation,
+build metadata, and PromptKit engine construction. These collaborators supply data
+and perform domain work; they do not replace CommandKit's handlers or renderers.
+
+An application's registration of a standard family adopts its complete contract.
+It cannot redefine `config show`, add a private `config artifacts` operation, or
+choose a different meaning for `config sources`. Domain reports belong outside
+the reserved family. New shared operations become part of CommandKit through an
+explicit standard change.
+
+Applications may register context selectors and typed configuration overrides
+through the extension mechanism described in section 5. This is a defined input
+extension, not permission to alter standard operations or output.
+
+**Alternatives:**
+
+- **Share helpers while applications own their handlers.** Easy to integrate,
+  but permits the same naming, scope, and output drift that motivates CommandKit.
+- **Allow arbitrary subcommands beneath standard families.** Convenient initially,
+  but makes the standard unpredictable and creates future name collisions.
+- **Own every command in every application.** Unnecessary for the stated goals;
+  domain operations have responsibilities that a shared inspection library cannot
+  usefully prescribe. CommandKit can supply common parsing and help machinery
+  without owning their business semantics.
+
+## 2. Evidence and conclusions
+
+The current checkouts demonstrate both reuse opportunities and choices that need
+to be replaced rather than preserved.
+
+| Evidence | Conclusion for the standard |
+| --- | --- |
+| Audita uses `config print-effective`; Notarius uses `config effective`; Narratio and Scriptorium use `config show`. | Select one verb: `show`. |
+| Audita combines settings, selected profiles, and provenance under `--view`; Notarius uses `--scope`; Scriptorium has a separate framework configuration family. | Separate the operation from the inspected configuration scope. |
+| Narratio's `config sources` reports field ownership; Scriptorium lists acquired source records. | Give source inventory and field explanation distinct contracts. |
+| Scriptorium's application and framework handlers repeat parsing, loading, warnings, dispatch, and output handling. | CommandKit should implement one inspection command family. |
+| Notarius and Scriptorium inspect named PromptKit profiles; Scriptorium also inspects prompts. | Definition inspection is another demonstrated shared capability. |
+| Narratio compares resolved overlays, rather than YAML file text. | Include semantic comparison of effective configuration. |
+| Help, flag placement, validation success output, and error statuses differ. | Specify those behaviors centrally. |
+| Narratio invokes the other applications and interprets Scriptorium's status `2` as output validation failure. | Breaking adoption requires coordinated consumer updates. |
+
+Evidence sources, relative to this roadmap in the sibling workspace checkouts:
+
+- [Audita CLI contract](../../../audita/docs/cli.md) and
+  [configuration parsing](../../../audita/internal/cli/config_input.go).
+- [Narratio CLI contract](../../../narratio/docs/cli.md),
+  [configuration inspection](../../../narratio/internal/app/config_commands.go),
+  and [comparison](../../../narratio/internal/app/config_diff.go).
+- [Notarius CLI contract](../../../notarius/docs/cli.md) and
+  [configuration commands](../../../notarius/internal/cli/configkit_commands.go).
+- [Scriptorium CLI contract](../../../scriptorium/docs/cli.md),
+  [application inspection](../../../scriptorium/internal/adapter/cli/config.go),
+  and [framework inspection](../../../scriptorium/internal/adapter/cli/framework_config.go).
+- [ConfigKit inspection API](../../../ConfigKit/inspection.go),
+  [source records](../../../ConfigKit/records.go), and
+  [configuration contract](../../../ConfigKit/docs/config.md).
+- [PromptKit configuration inspection](../../../promptkit/configuration_inspection.go)
+  and [consumer guide](../../../promptkit/docs/consumers/pkg-promptkit.md).
+
+These links document review evidence; they are not build dependencies. When the
+standard becomes implemented behavior, its durable reference should be owned by
+CommandKit rather than relying on sibling checkout links.
+
+## 3. Recommended command inventory
+
+### Required core suite
+
+| Command | Operator question or task |
+| --- | --- |
+| `app help [COMMAND ...]` | How do I use this command? |
+| `app version` | Which application build am I running? |
+| `app config scopes` | Which configuration scopes can I inspect? |
+| `app config validate` | Is the selected configuration valid? |
+| `app config show [--scope app\|promptkit\|all]` | What effective configuration will the application use? |
+| `app config sources` | Which inputs contributed to this configuration? |
+| `app config explain --path POINTER` | Why does this path have this value, or why was it removed? |
+| `app config diff --against-config PATH` or `--against-overlay NAME` | How do two effective configurations differ? |
+
+`app` is a placeholder for the application's executable name. Section 4 defines
+scope defaults; section 5 defines selectors shared by configuration operations.
+
+### Optional PromptKit suite
+
+| Command | Operator question or task |
+| --- | --- |
+| `app promptkit list prompts` | Which prompt IDs and versions are available? |
+| `app promptkit list profiles` | Which execution profiles are available? |
+| `app promptkit show prompt ID [--prompt-version VERSION]` | What is the selected prompt's definition metadata? |
+| `app promptkit show profile ID` | What execution target does this named profile resolve to? |
+
+**Accepted:** put this suite under `promptkit`, using the same namespace/resource
+first pattern as `config`. The root names `prompt` and `profile` remain available
+to applications.
+
+**Recommendation:** use explicit resource operands after `list` and `show`.
+Plural collection names select catalogs; singular names select one definition.
+This keeps prompt IDs and execution profile IDs unambiguous even when they overlap.
+Registering the suite reserves the complete `promptkit` family, supplies all four
+operations, and registers the `promptkit` configuration scope.
+Configuration inspection remains `config show --scope promptkit`; the definition
+commands report metadata and resolved execution targets, not a second configuration
+display path.
+
+Definition catalogs require upstream API work; their absence today is an
+implementation dependency, not evidence against a useful command standard.
+
+**Alternatives:**
+
+- **Bare `promptkit list`.** Could display a combined catalog with resource type,
+  ID, and prompt version. Useful for discovery, but potentially noisy. An explicit
+  resource gives each catalog a clear report shape; a combined listing can be
+  considered as an additional operation later.
+- **`promptkit show ID --type profile`.** Explicit and compact, but places the
+  resource identity partly in a flag. Prefer the resource operand.
+- **`promptkit show ID`.** Requires cross-collection lookup and ambiguity rules.
+  Do not make inspection depend on prompt and profile IDs being globally unique.
+- **`promptkit profiles list/show`.** Retains the accepted namespace boundary and
+  is viable, but adds another resource grouping before the operation. The proposed
+  `promptkit list/show RESOURCE` layout puts the operation immediately after its
+  owning namespace, as in `config show`.
+- **Put definitions under `config`, such as `config profile`.** Mixes source
+  configuration with backend-completed execution settings and gives `config` an
+  unrelated resource vocabulary.
+- **Include only the core suite initially.** A reasonable delivery phase. Keep
+  the PromptKit suite explicitly pending until its public APIs are available;
+  avoid independent replacement inspection commands in the applications.
+
+`run`, `execute`, `render`, `serve`, `session`, and artifact catalogs are not
+CommandKit-owned commands in this proposal. Recommend `run` for a new application's
+principal execution operation, but retain application ownership of that choice.
+
+## 4. Configuration scopes
+
+**Recommendation:** use `--scope NAME` on configuration operations, with these
+standard identifiers:
+
+- `app`: the application's effective configuration, including defaults,
+  imports, the selected overlay, explicit overrides, and recorded domain
+  resolution. Each application's configuration schema remains its own.
+- `promptkit`: the captured configuration of the PromptKit engine assembled
+  from that application's selected inputs and registered assets, when integrated.
+- `all`: a selector available to `config validate` and `config show`, meaning every
+  registered scope. It is not itself a configuration scope or a merged document.
+
+`show`, `sources`, `explain`, and `diff` default to `app`. `validate` defaults to
+`all`: a bare validation command should establish that the configured application
+and its integrated framework definitions are valid. `--scope app` provides the
+explicit narrower check without constructing PromptKit. A non-PromptKit
+application's `all` selection consists only of `app`. `show --scope all` is an
+explicit request for a YAML stream of all selected scopes. `sources`, `explain`,
+and `diff` continue to select one scope and reject `all` in this proposal.
+
+The differing default for validation is intentional: routine inspection starts
+with the application configuration, while general validation performs a complete
+configuration check. An operator can request the combined inspection explicitly.
+Help must state these defaults prominently.
+
+`config scopes` lists scope ID, description, and whether it is the default for
+inspection. It uses registration metadata, so it works when files are missing or
+configuration is invalid. List `app` first, `promptkit` second when registered,
+then additional scopes sorted by ID; use this same order for `show --scope all`.
+It accepts `--format text|yaml` and no loading selectors. Unsupported scope names
+are usage errors, with the
+available names in the diagnostic; there is no fallback to `app`.
+
+Scopes use stable semantic names rather than executable names such as `notarius`.
+Applications may register additional independently meaningful configuration scopes
+through the same complete contract. A scope must supply an effective snapshot,
+sources, explanations, and comparison support; a custom formatted report does not
+qualify as a scope. Scope dependencies must be explicit, and one invocation must
+reuse already loaded dependencies rather than reread them unnecessarily.
+
+**Alternatives:**
+
+- **Default every operation to `app`, requiring `validate --scope all`.** Very
+  uniform syntax, but easy to mistake application-only validation for validation
+  of all definitions needed by the application.
+- **Separate paths, such as `config promptkit show`.** Makes the scope visible in
+  the command path; produces duplicated operation trees and complicates adding
+  scopes. This remains a viable alternative if scope flags feel too indirect.
+- **A scope-keyed wrapper for `show --scope all`.** Scope identity survives parsing
+  in one document, but requires additional presentation work and indentation of
+  the native reports. The accepted initial approach keeps separate native YAML
+  documents; its output and ordering contract are defined below.
+- **Permit partial scopes with different operations.** Accommodates legacy
+  implementations, but makes `config` behave differently across applications.
+  Adapt or improve the inspection provider instead.
+
+## 5. Shared inputs and command syntax
+
+### Configuration selection and overrides
+
+**Recommendation:** every loading configuration operation accepts `--config PATH`,
+`--overlay NAME`, and `--scope NAME`. These have the same meanings for validation,
+display, source inventory, explanation, and comparison.
+
+`--config` selects the application root configuration even for `promptkit` scope;
+the application constructs the selected framework inputs from that root and its
+other explicit selectors. A supplied empty path is a usage error. A supplied
+missing or invalid file is a load failure and never triggers discovery fallback.
+Relative CLI paths use the invocation working directory. File-relative resources
+retain the owning library's source-context semantics.
+
+When `--config` is omitted, use the application's registered discovery policy
+identically across these commands and ordinary execution. CommandKit must not
+hard-code a second search policy. Discovery order, environment-variable support,
+default-only operation, and packaging paths must be visible in help. This proposes
+a uniform selection interface; a universal filesystem discovery convention is a
+separate decision because the applications have different deployment layouts.
+
+`--overlay` always selects a configuration overlay, never a PromptKit execution
+profile. Follow ConfigKit's naming and resolution semantics: omission, an empty
+name, and the exact name `default` select the base; other names select one overlay.
+An overlay name is not a file path. Replace `--config-overlay` with this standard
+spelling rather than silently maintaining two conventions.
+
+Applications register domain context selectors, such as Narratio's `--campaign`
+and `--campaign-file`, and typed configuration overrides. CommandKit owns their
+registration, parsing, help exposure, and propagation; applications own their
+field mappings and domain checks. A selector must be offered on each operation
+where it is meaningful, with the same meaning. Invalid combinations fail before
+loading. Selectors that do not affect a chosen scope must be rejected rather than
+silently ignored. Registration cannot shadow a standard flag.
+
+Preserve explicit flag presence. Omission, an empty string, false, zero, and null
+are not interchangeable. Send configuration changes through ConfigKit's override
+records and resolution mechanisms so effective output and provenance agree.
+Execution-only controls such as resume, output directories for generated artifacts,
+or lane execution do not belong on generic configuration commands.
+
+**Alternatives:**
+
+- **Require `--config` on every operation.** Simple and explicit, but makes
+  inspection use a different entry path from normal execution and limits
+  defaults-only applications.
+- **Prescribe one global discovery sequence now.** Could improve consistency,
+  but expands this command proposal into deployment and configuration discovery
+  policy. Evaluate that separately rather than preserving current differences
+  by assumption or inventing paths without deployment evidence.
+- **Only expose root, overlay, and scope flags.** Keeps the surface small but
+  cannot inspect Narratio's resolved campaign contributions or explicit settings
+  used by execution. A controlled registration mechanism is more effective.
+- **Offer a generic `--set path=value`.** Convenient for advanced operators, but
+  requires a new value syntax and typing contract and makes overrides harder to
+  discover. Defer until typed, documented flags prove insufficient.
+
+### Flag placement and repeated flags
+
+**Recommendation:** put the complete command path before its options; allow flags
+and operands to be interspersed within the selected leaf command. For example:
+
+```sh
+app config show --config ./config.yml --scope promptkit
+app promptkit show profile team.summary --config ./config.yml
+app promptkit show profile --config ./config.yml team.summary
+```
+
+Standard flags use `--long-name`; `-h` is the standard help shorthand. Accept
+`--name value` and `--name=value`; boolean false uses `--name=false`. `--` ends
+option parsing and makes subsequent tokens operands. Standard configuration
+operations reject positional operands; `promptkit list` accepts a collection name,
+and `promptkit show` accepts a resource name and its one documented ID. Flags may
+appear before or after these operands. `help` accepts command-path operands.
+
+Singleton flags reject repeated occurrences, including mixed `--name value` and
+`--name=value` spellings. Repeatable source or domain flags combine in documented
+order. Do not infer singleton presence from its parsed value. Unknown flags are
+usage errors. New names use hyphens rather than underscores.
+
+This is the contract for CommandKit-owned commands. Recommend the same grammar
+for application commands and supply reusable parsing machinery, while leaving
+their operand counts and domain rules application-owned.
+
+**Alternatives:**
+
+- **Verb first, such as `app show config`.** Considered and not selected. It groups
+  operations by action but spreads one namespace across root verb families and
+  requires ownership at individual routes. Namespace/resource first gives each
+  standard family a clear ownership boundary.
+- **Require flags before all operands.** Fits Go's `flag` parser directly but
+  retains the ordering burden the user wants to remove.
+- **Allow common flags before or between command-path components.** Familiar
+  in some command frameworks; increases command routing complexity. A single
+  documented position after the complete path is sufficient initially.
+- **Let the last singleton occurrence win.** Convenient for argument assembly,
+  but conceals conflicting operator instructions. Applications already have
+  useful repeatable inputs; declare those explicitly instead.
+
+Go's [standard flag parser](https://pkg.go.dev/flag#hdr-Command_line_flag_syntax)
+stops at the first operand; [pflag](https://github.com/spf13/pflag#command-line-flag-syntax)
+supports interspersed options. The accepted [backend decision](03-backend.md)
+selects Cobra with pflag for the initial implementation. Any required adaptation must use
+registered flag metadata, honor `--`, and correctly handle values beginning with
+`-`; do not replicate Notarius's hand-maintained flag-name lists in every consumer.
+
+## 6. Configuration command contracts
+
+### `config validate`
+
+**Recommendation:** validate all selected scopes completely through their owning
+loaders. Include acquisition, composition, defaults, typed decoding, recorded
+resolution, and domain configuration checks. PromptKit scope constructs the engine
+and validates all effective definitions, including unused ones. Application scope
+includes configured references and catalog relationships that can be checked
+without executing a request.
+
+Validation does not execute a pipeline, prepare request-specific prompts, read
+request inputs, contact a provider, or create runtime state. Do not add generic
+pipeline or lane selectors to this operation. An application's operational
+preflight, such as `session validate`, can perform additional context-dependent
+checks outside the standard suite.
+
+Default text output is one concise success line identifying the validated scopes.
+`--format yaml` returns a structured success report containing the scope IDs.
+Warnings go to stderr and do not alone make configuration invalid. Failure emits
+no success report and returns status `1`. Complete each scope's dependency loading
+once; stop on a fatal loading failure rather than promising a report of every
+possible defect across invalid inputs.
+
+Credential requirements follow the genuine configuration lifecycle: ConfigKit
+loads can resolve typed secret references and therefore require the referenced
+environment values, whereas PromptKit inspection does not itself resolve provider
+credentials. Describe these requirements in scope help. Offline means no provider
+or remote execution; it does not promise credential-independent loading. Existing
+explicit credential-file bootstrap may run as part of acquisition, with its safe
+report on stderr; it must not create durable application runtime state.
+
+**Alternatives:**
+
+- **Only check decoding/schema validity.** Useful as a distinct lower-level
+  operation, but too weak for an unqualified application validation command.
+- **Validate only definitions selected by a planned run.** Audita provides useful
+  evidence for selected-profile checks, but a generic configuration command should
+  find invalid configured definitions before a later selection reaches them.
+- **Silent success.** Scriptorium demonstrates this and scripts can use the exit
+  status. A short scope summary is clearer for interactive use; structured output
+  supports automation without parsing prose.
+- **Skip secret resolution by default.** Valuable for inspection without runtime
+  credentials, but requires an explicit upstream ConfigKit lifecycle design. Do
+  not simulate credentials or bypass native validation to deliver it.
+
+### `config show`
+
+**Recommendation:** show the complete final effective configuration for the selected
+scope, or each registered scope when `--scope all` is supplied.
+Use the captured inspection snapshot, including recorded resolution, rather than
+raw file text, an application-selected subset, or a fresh marshal of mutable
+runtime structs. Loading necessarily performs the validation required to obtain
+a usable snapshot. Single-scope display loads only that scope and its dependencies;
+`all` loads every registered scope and reuses their shared dependencies.
+
+Output is native redacted YAML without a status line. A single-scope report has no
+heading or document marker added by CommandKit. Preserve ConfigKit's distinction
+between null, empty containers, and absent values, its
+stable mapping order, and sequence order. This is an inspection document, not a
+guaranteed reloadable configuration file.
+
+**Accepted:** `--scope all` writes the application configuration followed by the
+PromptKit configuration when registered, then any additional scopes in the order
+reported by `config scopes`. Each scope is a separate document, introduced by
+`---` and a `# scope: NAME` comment. CommandKit adds those separators and labels
+around the native writer output without merging mappings or serializing runtime
+structs. Even a one-scope `all` report uses this labeled document form.
+
+```yaml
+---
+# scope: app
+server:
+  addr: localhost:8080
+---
+# scope: promptkit
+profiles: {}
+```
+
+The stream provides a complete inspection in one invocation, preserves native
+rendering and redaction, and avoids collisions between scopes' mapping keys.
+Its tradeoffs are larger output and the need for automated consumers to decode
+multiple documents. Comments are human labels, not parsed metadata; scope identity
+for automated consumers follows the documented order. This is suitable YAML for
+automation, but it is not one configuration document or a reloadable combined file.
+
+Load and validate all selected scopes before starting output. A scope load failure
+returns `1` without a partial successful report. Writer failures can still leave
+partial output. A broken PromptKit configuration can therefore prevent `--scope all`
+from displaying otherwise usable application settings; `--scope app` remains
+available for that narrower inspection.
+
+`config show` has one initial report format, YAML, and does not need a `--format`
+selector. JSON is deferred without a delivery commitment. The combined display
+uses existing native writers and does not require a new structured effective
+snapshot API solely for formatting.
+
+**Alternatives:**
+
+- **A scope-keyed single YAML document.** Scope names become machine-readable keys,
+  but the renderer must wrap and indent each native document. This could replace
+  comment/order identification if consumers need scope identity in parsed data.
+- **Emit each scope as soon as it loads.** Reduces waiting before output, but a
+  later load failure would leave an incomplete combined report. Prefer loading
+  all scopes first.
+- **Raw composed input.** Shows directives and authored values, but omits defaults
+  and resolution and therefore answers a different question.
+- **Application-defined compact views.** Audita's selected-profile summary is
+  useful domain reporting, but does not replace a complete effective snapshot.
+- **A reloadable export command.** Potential future feature with a different
+  contract; do not imply that inspection output supports round trips.
+
+### `config sources`
+
+**Recommendation:** list the acquired and synthetic input sources for the selected
+scope in the owning library's recorded order. Preserve every source's ID, label,
+path when available, layer, kind, underlay index, and import parent location.
+Do not sort sources alphabetically or flatten them into one winning file per
+field. Composite and inheritance provenance belongs to explanation records.
+
+Default text output is a readable table; `--format yaml` returns the common source
+report with an ordered `sources` sequence. Defaults-only loading may legitimately
+produce an empty sequence. Defaults and domain derivations are not fabricated file
+sources. Both application and PromptKit scopes use the same complete record
+shape, replacing Scriptorium's differing source projections.
+
+**Alternatives:**
+
+- **Field ownership under `sources`.** Narratio's report is useful but answers
+  why a field has its value. Use `config explain` for that task.
+- **Only list filenames.** Short, but loses underlays, non-file sources, import
+  relationships, and CLI contributions that help diagnose configuration.
+- **YAML by default.** Suitable for automation and consistent with native
+  configuration reports. Prefer a table for interactive discovery and an explicit
+  YAML format for structured consumption. Scriptorium's current JSON default is
+  evidence to evaluate, not a format requirement for CommandKit.
+
+### `config explain`
+
+**Recommendation:** require `--path POINTER`; an explicitly supplied empty string
+selects the root. Use ConfigKit JSON Pointer semantics, including `~0` and `~1`
+escaping, mapping keys containing dots, and effective or historical paths. Omitted
+path and malformed pointer are usage errors; a well-formed unknown path is a
+command failure. Do not impose additional canonical-spelling restrictions beyond
+the owning library's supported path contract without a demonstrated need.
+
+Default text output delegates to the native safe explanation writer. It includes
+the effective value and presence, effective origin, composite source locations,
+inheritance, chronological before/after values, resolution reasons and dependencies,
+and safe secret-reference metadata when available. Historical deleted paths remain
+explainable. Values receive native historical redaction.
+
+`--format yaml` projects the native structured explanation into CommandKit's
+structured report. Keep value snapshots as records with `present`, `redacted`, and
+`yaml` fields, matching the upstream representation rather than inventing a typed
+value model for historical values. The `yaml` field holds native snapshot text
+as a string rather than decoding it into a new value. History remains chronological.
+
+```sh
+app config explain --path /server/addr
+app config explain --scope promptkit --path '/profiles/team~1summary/model'
+app config explain --path ''
+```
+
+**Alternatives:**
+
+- **One positional pointer.** Notarius demonstrates this and it is concise, but
+  a named flag makes the required empty root explicit and allows a future distinct
+  operand without ambiguity. Either convention could work if used everywhere.
+- **Value-free provenance only.** Audita and Narratio demonstrate useful compact
+  reports; native redacted history gives a more complete explanation. A future
+  summary format could omit values without changing this command's meaning.
+- **`explain --all` listing every field.** Useful for audits but potentially very
+  large and expensive. Root explanation provides a starting point; defer exhaustive
+  field-origin reporting until its traversal and summary contract are designed.
+
+### `config diff`
+
+**Recommendation:** compare two independently resolved effective configurations in
+the same scope. The ordinary selectors define the left side. At least one of
+`--against-config PATH` or `--against-overlay NAME` explicitly defines the right
+side; together they can change both root and overlay. Unspecified selectors are
+copied from the resolved left selection, rather than running discovery again.
+An omitted right overlay inherits the left overlay; `--against-overlay default`
+explicitly selects the base. Domain context selectors and typed overrides apply
+identically to both sides in this version.
+
+```sh
+app config diff --config ./config.yml --overlay staging --against-overlay production
+app config diff --config ./old.yml --against-config ./new.yml --against-overlay default
+```
+
+Both sides must load and validate. Compare semantic effective values, including
+defaults and recorded domain resolution, rather than YAML formatting, source IDs,
+file order, or overlay names. Recursively compare mappings; keep sequences atomic,
+preserving their order. Distinguish absence, null, empty mappings, and empty
+sequences. Sort differences by JSON Pointer and report `added`, `removed`, and
+`changed` with safe before/after snapshots. Root or container replacement must not
+produce redundant descendant differences.
+
+Default text output is a readable change report, or `no differences` when
+appropriate. `--format yaml` supplies a structured report with selection metadata,
+an ordered differences sequence, and explicit information about redacted comparison
+gaps. Successful comparison returns `0` whether differences exist or not.
+
+Compare only values that the owning library makes available for inspection.
+Secret bytes must never be fetched to improve a comparison. A masked value is
+not an ordinary literal string and identical masks do not prove secret equality.
+Apply the union of both sides' sensitivity classifications to before/after
+values so a value classified on either side cannot leak from the other report.
+When sensitivity prevents comparison, identify the path as not comparable; do
+not print `no differences` as an unqualified equality claim. This needs upstream
+structured sensitivity metadata, not string matching on `[REDACTED]`.
+
+**Alternatives:**
+
+- **Two positional overlay names.** Narratio demonstrates a simple interface,
+  but it cannot also compare different root files without another syntax.
+- **Fully separate left/right domain selector sets.** More flexible for campaign
+  comparisons; adds substantial flag duplication. Shared context covers the
+  existing overlay use case. Add independent contexts later if needed.
+- **Diff rendered YAML lines.** Easy to implement, but formatting changes obscure
+  meaningful changes and identical masks conceal comparison gaps.
+- **Return a special nonzero status for differences.** Useful for CI assertions,
+  but makes a successful inspection look like a failed command. Consider an
+  explicit future check mode; keep ordinary comparison successful.
+
+## 7. PromptKit definition inspection
+
+**Recommendation:** optional definition commands use the same application root,
+overlay, and registered framework source selectors as `config --scope promptkit`.
+They always target PromptKit, so they do not accept `--scope`. They load the engine
+once and use its captured definitions without provider calls, capacity admission,
+request preparation, artifact loading, or credential lookup by PromptKit.
+
+`promptkit list prompts` reports available `(ID, version)` pairs sorted by ID then
+version; `promptkit list profiles` reports exact profile IDs sorted lexically.
+IDs are identifiers, not filesystem paths, and prompt versions need not be semantic
+versions.
+
+`promptkit show prompt ID` uses PromptKit's existing version-selection rules:
+omission of `--prompt-version` works only when that ID has one available version.
+Show the definition ID, selected
+version, opaque equality hash, declared default profile, declared inputs, and
+output contract. It does not resolve the declared default profile or render
+request-specific message templates. A command to show fully rendered requests
+would need inputs and belongs to application preparation such as `render`.
+
+`promptkit show profile ID` reports the backend-completed named execution target:
+profile ID, backend, endpoint, model, configured provider controls, credential
+reference name,
+and whether a direct credential will be required. Do not suggest that a named
+profile is the profile selected by every request, that zero indicates a provider
+default, or that credential references establish credential availability.
+
+All four commands default to readable text and accept `--format yaml`. Report
+fields and their structured YAML shapes are defined by CommandKit; arbitrary
+public Go structs are not an output contract. Unknown IDs or unavailable versions
+return `1`; missing
+or empty required IDs and invalid argument counts return `2`.
+
+Provider parameter redaction belongs upstream in PromptKit. Notarius's curated
+profile report is useful evidence, while Scriptorium's profile output does not
+share configuration inspection's redaction contract. Establish a supported safe
+profile reporting API before adding arbitrary provider parameters to the standard
+report. Do not duplicate credential-name heuristics in CommandKit or assume that
+raw `InspectProfile` results have native configuration redaction.
+
+**Alternatives:**
+
+- **Inspect definitions only through `config show/explain`.** Adequate for source
+  presence and history, but does not clearly expose backend-completed targets or
+  catalog discovery.
+- **Show raw prompt message content by default.** Can help authors, but the current
+  public prompt inspection reports metadata, and request rendering is a different
+  operation. Add content inspection deliberately upstream if needed.
+- **List definitions by parsing effective YAML in CommandKit.** Avoids new APIs,
+  but takes ownership of PromptKit's schema and version model. Public catalog
+  methods are the better boundary.
+
+## 8. Help and version
+
+### Help
+
+**Recommendation:** `app`, `app help`, `app --help`, and `app -h` print root help
+and succeed. A family invoked without an operation, such as `app config`, prints
+family help and succeeds. `app help config explain` and
+`app config explain --help` print the same leaf help with status `0`.
+
+Help never acquires configuration, constructs PromptKit, resolves credentials,
+or allocates runtime state. Generate it from registered commands and flags,
+including application-owned commands, available scopes, selector applicability,
+format choices, and examples. An unknown command path is a usage error. A help
+request bypasses missing required operands; it does not make an otherwise unknown
+command or unknown flag valid.
+
+**Alternatives:**
+
+- **Only root help.** Notarius's current leaf help errors demonstrate why this is
+  insufficient for an operator trying to discover arguments.
+- **Error on a bare root or family.** Narratio and Scriptorium do this in some
+  cases. Printing help successfully makes exploration consistent; an explicitly
+  malformed leaf invocation still fails.
+- **Maintain separate help strings.** Straightforward, but they drift from
+  parsing definitions. Registration should be the shared source.
+
+### Version
+
+**Recommendation:** `app version` prints `app VERSION` and a newline. Standardize
+`app --version` as a root-only shortcut, rather than retaining it merely as a
+Notarius compatibility alias. Neither form loads configuration. Recommend
+`version --format yaml` with application name/version, optional revision and build
+time, and the CommandKit standard revision implemented by the binary.
+
+Applications supply build identity, with tagged Go build information usable when
+available. An unversioned development build reports `dev`; unknown revision or
+build time stays absent rather than being invented. The CLI standard revision is
+distinct from application version and from the CommandKit module version. It
+identifies observable command/report contracts, not application artifact formats.
+
+**Alternatives:**
+
+- **Only the command or only the flag.** Either could be consistent; supporting
+  both familiar discovery paths costs little and gives them one implementation.
+- **Emit all build and dependency information by default.** Helpful for debugging,
+  but unnecessarily verbose and unstable for a simple identity check. Structured
+  output should expose the selected fields.
+- **Use the application version as the sole compatibility signal.** Insufficient
+  to distinguish independent CLI-standard and application-artifact changes.
+
+## 9. Output, diagnostics, and failures
+
+**Recommendation:** successful reports go to stdout; warnings, loading diagnostics,
+bootstrap reports, and errors go to stderr. Emit each diagnostic once, retain
+library source coordinates and source-ID legends, and use library-safe messages.
+No progress messages or banners may enter report output.
+
+| Operation | Default | Other initial format |
+| --- | --- | --- |
+| `help` | text | none |
+| `version` | text | YAML |
+| `config scopes`, `validate`, `sources`, `explain`, `diff` | text | YAML |
+| `config show` (one scope or `all`) | YAML | none |
+| `promptkit list/show` | text | YAML |
+
+Format names are lowercase. Unsupported formats are usage errors. Use `--format`
+consistently for commands that offer text and YAML; do not add a selector to
+YAML-only `config show`. Structured reports other than the native `config show`
+documents use a defined operation-specific schema and the applicable scope or
+selection metadata. Define their exact YAML field shapes before implementation;
+do not make native explanation prose or Go struct field spelling a machine
+contract. Structured YAML reports contain one document with a trailing newline;
+`config show --scope all` deliberately uses a multi-document stream.
+
+**Accepted:** defer JSON output for the initial implementation across the suite.
+YAML is suitable for automated consumption, and the native inspection writers
+already preserve its value semantics. There are no initial JSON format flags,
+JSON-specific report schemas, or JSON-driven upstream API requirements. Adding
+JSON is optional future work only if a concrete need emerges; it may never be
+needed. JSON Pointer paths remain supported independently of output format.
+
+Inspection formats use upstream secret classification; there is no unredacted
+output option in this standard. Redaction does not classify every sensitive prompt
+or arbitrary application value. The proposal preserves library confidentiality
+semantics rather than promising that every report is safe for public disclosure.
+
+Default to stdout and shell redirection; do not initially add `--out` or `--output`
+to standard reports. Ordinary writer failures may leave partial output and return
+`1`; consumers must check status before decoding. This avoids adding filesystem
+creation, replacement, and retention behavior to inspection.
+
+| Status | CommandKit-owned command meaning |
+| --- | --- |
+| `0` | Successful operation, including help, valid configuration, or comparison that found differences. |
+| `1` | Loading, validation, lookup, explanation, comparison, cancellation, diagnostics delivery, or output failed after valid syntax. |
+| `2` | Unknown command/flag/scope, invalid format, missing or malformed argument, repeated singleton, or invalid flag combination. |
+
+Applications retain domain result statuses for their own commands. CommandKit must
+not globally reinterpret Scriptorium's execution validation status or Notarius's
+artifact rejection semantics. Common usage errors can use the shared status `2`,
+but business outcomes remain explicit application mappings.
+
+**Alternatives:**
+
+- **Structured YAML everywhere by default.** Works for automation, but text help,
+  tables, and native explanations are useful for interactive inspection. Offer
+  YAML explicitly where the default is text.
+- **JSON as an additional output format.** Deferred by the accepted decision.
+  It would add serializers, report contracts, and possible representation issues
+  without a demonstrated benefit over the initial YAML reports.
+- **An output-file flag on every command.** Convenient but duplicates shell
+  redirection and introduces file semantics. Add it later if concrete consumers
+  need behavior beyond redirection.
+- **One nonzero status for every failure.** Narratio and Scriptorium demonstrate
+  simplicity, but distinguishing malformed invocation from a failed valid command
+  is useful and already demonstrated by Notarius.
+- **One exit policy for all application execution outcomes.** Would exceed the
+  ownership boundary. Coordinate changes to owned commands without claiming domain
+  statuses for unrelated commands.
+
+## 10. Implementation dependencies and delivery
+
+**Recommendation:** implement the common command behavior against narrow inspection
+providers, with ConfigKit and PromptKit retaining ownership of configuration
+semantics. Publish upstream API improvements before adopting them in CommandKit
+and the applications. Do not import sibling `internal` packages or turn source
+checkout proximity into an architectural dependency.
+
+Existing public APIs already support native YAML, native explanation text,
+structured explanation records, source records, and named definition inspection.
+They do not yet provide everything recommended here:
+
+| Needed capability | Implementation work before the complete standard can ship |
+| --- | --- |
+| Semantic diff | A safe structured effective snapshot from ConfigKit, preserving value semantics and per-path sensitivity; expose it through PromptKit inspection. This serves comparison rather than JSON output. |
+| Combined configuration display | Compose native writers as labeled separate YAML documents after all selected scopes load; no new snapshot API is needed just to concatenate these reports. |
+| Prompt/profile catalogs | Public PromptKit methods enumerating captured IDs and prompt versions without reparsing source YAML. |
+| Safe rich profile reports | PromptKit-owned redacted inspection data for provider parameters. |
+| Narratio's final application snapshot | Adapt its configuration boundary so campaign-derived effective values and provenance are recorded in the inspected result; avoid an unrelated typed-struct dump. |
+| Full cross-scope validation | Application integration registering dependencies and offline configuration checks, with clear credential requirements. |
+
+Suggested sequence:
+
+1. Resolve the remaining proposed command contracts and alternatives, preserving
+   the accepted planning decisions above.
+2. Define the structured YAML report schemas and minimal upstream inspection
+   additions. Record accepted ownership decisions in durable architecture
+   documentation.
+3. Implement core dispatch, syntax, help, version, scopes, validation, native
+   display (including `show --scope all`), source inventory, and explanation using
+   existing APIs.
+4. Integrate Scriptorium and Notarius to exercise both scopes and remove duplicated
+   handlers. Partial adoption remains development work, not conformance to the
+   complete proposed standard.
+5. Add safe semantic comparison and the optional complete PromptKit definition
+   suite once the upstream APIs are released.
+6. Integrate Audita and Narratio, moving domain reports outside reserved families
+   and aligning their standard operations. Update consumer adapters and docs for
+   the intentional breaking releases.
+
+A complete core adopter exposes every required core command for every registered
+scope. A complete PromptKit-suite adopter additionally exposes all four definition
+commands. Do not ship placeholder commands, claim unsupported formats, or silently
+omit required operations.
+
+Later implementation validation should exercise genuine contract risks: help with
+invalid configuration, leaf flag placement and `--`, explicit empty/false/zero
+overrides, source order, historical paths, independent diff selections, sensitivity
+changes between sides, multi-document scope order, all-scope load failures before
+output, warning delivery and failed writers, and Narratio's subprocess consumers.
+
+Breaking adoption replaces divergent spellings and behavior. Compatibility aliases
+are not required; introduce one only for a concrete transition need with an explicit
+retirement decision. Application execution commands outside the reserved suite
+remain independently owned, even when their implementations use CommandKit helpers.
+
+**Alternatives:**
+
+- **Extract one existing application's command family unchanged.** Fast, but
+  carries its omissions and incidental decisions into the standard. Use existing
+  implementations to inform and exercise the selected contract instead.
+- **Build one universal runtime/application framework.** Could absorb more code,
+  but would expand ownership into lifecycle and domain execution without improving
+  the demonstrated inspection boundary.
+- **Implement missing upstream semantics inside CommandKit.** Avoids release
+  coordination, but duplicates configuration projection, redaction, and definition
+  knowledge. Those responsibilities should remain with the libraries that own them.
+
+## 11. Explicitly deferred commands
+
+**Recommendation:** defer configuration mutation (`set`, `edit`, `init`, `migrate`),
+reloadable export, credential diagnostics, live provider probes, completion
+installation, exhaustive field-origin inventories, request preparation, and domain
+artifact catalogs from this standard. Their semantics are not established by the
+repeated inspection code under review. Add a shared command when its operator
+purpose and ownership can be specified as clearly as the suite above.
+
+JSON output is also deferred, with no assumption that it will eventually be added.
+
+**Alternatives:**
+
+- **Add a generic `doctor` command now.** Attractive for troubleshooting, but
+  mixes offline configuration, credentials, network health, and domain resources.
+  Specify those checks before choosing a shared name and success meaning.
+- **Standardize `run` in this first suite.** Could further improve vocabulary,
+  but requires comparing execution semantics and their consumer contracts. A
+  recommended verb is useful now; reserving its complete contract is separate work.

docs/roadmap/02-dispatch.md

@@ -0,0 +1,98 @@
+# CommandKit dispatcher implementation
+
+Status: accepted architecture; implementation pending.
+
+Date: 2026-10-06.
+
+[ADR 0001](../adr/0001-command-dispatch-and-inputs.md) owns the accepted dispatcher,
+registry, and handler-input decisions, their alternatives, and rationale. The
+[architecture policy](../policy/architecture.md) owns normative boundaries.
+This roadmap owns pending API design, implementation status, and sequencing.
+The [CLI plan](01-cli-plan.md) retains operator-contract proposals and their
+individual approval status.
+
+## 1. Current status
+
+The registry and typed-input model are selected but have no Go implementation.
+Exact constructors, registration/group APIs, bindings, factories, handler
+signatures, and application outcome/error interfaces remain open. No illustrative
+API declaration is a supported contract.
+
+The [backend roadmap](03-backend.md) tracks Cobra/pflag integration, and the
+[facade roadmap](04-facade.md) tracks the accepted public/internal boundary.
+
+## 2. Public API design
+
+1. Design explicit instance construction, individual command registration,
+   composable groups, and invocation using application context and streams.
+2. Express nested paths, descriptions, typed flags and defaults, repeatable
+   inputs, presence, operands, and typed handlers in one definition.
+3. Define capability-provider registration that installs complete standard
+   families without executing providers. Design wiring diagnostics separately
+   from invocation-time loading failures.
+4. Specify the outcome/error interface so common usage errors, standard-command
+   failures, and application-specific domain outcomes remain distinguishable.
+5. Demonstrate bindings against the proposed `config show`, `promptkit show
+   profile`, and Narratio's application-owned `session restore`. These examples
+   exercise standard selectors, resource operands, and application flags without
+   approving unresolved command details.
+6. Evaluate simple and complex consumers against consistency and removed
+   infrastructure. Constructor options or initial command collections can be
+   conveniences over the same registry if they reduce assembly work.
+
+### Illustrative presence and inputs
+
+The selected model keeps presence alongside values where omission matters. One
+possible shape remains:
+
+```go
+// Illustration only; these are not established public API declarations.
+type Supplied[T any] struct {
+    Value T
+    Set   bool
+}
+
+type RestoreInput struct {
+    SessionID string
+    DryRun    bool
+    Force     bool
+    Overlay   Supplied[string]
+}
+```
+
+Select exact public types, binding functions, and input factories during API
+work. Keep context, streams, and execution dependencies separate from CLI fields.
+Design domain value parsing within shared bindings without returning the complete
+argv to handlers.
+
+## 3. Implementation sequence
+
+1. Implement the root facade and internal command definitions under
+   [ADR 0003](../adr/0003-public-facade.md). Add the per-instance registry and
+   conflict checks without global or import-time registration.
+2. Translate definitions through the internal Cobra/pflag adapter. Allocate fresh
+   input and backend state per invocation; do not bind registrations permanently
+   to shared mutable inputs.
+3. Implement help/version and capability installation without configuration or
+   runtime construction. Providers load only when the selected operation needs
+   their results.
+4. Resolve remaining grammar and outcome proposals in the CLI plan before
+   implementing them. Do not adopt parser defaults as accidental contracts.
+5. Implement the selected standard handlers through owning-library inspection
+   APIs, following the upstream dependencies and delivery sequence in the CLI plan.
+6. Replace application routers and parser plumbing with registration and handlers.
+   Coordinate the intentional breaking changes with application docs and
+   subprocess consumers. Partial integrations remain development work rather
+   than conformance to an unsupported complete suite.
+
+## 4. Implementation evidence
+
+As behavior lands, select meaningful checks under the testing policy for nested
+routing and collisions, help without configuration, flag placement and `--`,
+explicit empty/false/zero input, repetition, fresh values and presence across
+invocations, cancellation, output errors, and preserved application outcomes.
+Fresh state alone does not promise concurrent dispatch.
+
+Update exact API GoDoc, consumer guidance, implemented CLI reference, and internal
+inventory with their corresponding implementation. Keep rationale in the ADR;
+retire completed implementation tasks without losing pending proposals.

docs/roadmap/03-backend.md

@@ -0,0 +1,88 @@
+# CommandKit CLI backend implementation
+
+Status: accepted backend; implementation pending.
+
+Date: 2026-10-06.
+
+[ADR 0002](../adr/0002-cobra-backend.md) owns the Cobra/pflag selection, alternatives,
+and rationale. [ADR 0003](../adr/0003-public-facade.md) owns the root facade and
+internal adapter boundary. This roadmap tracks dependency selection, adaptation,
+and implementation evidence. The [CLI plan](01-cli-plan.md) retains command and
+grammar proposals; [dispatcher work](02-dispatch.md) tracks the public input and
+invocation API.
+
+## 1. Current status
+
+Cobra with pflag is selected as the sole initial backend. No module dependency,
+adapter, or executable behavior is implemented. Select versions and attribution
+when dependencies are incorporated. There is no initial public backend selection
+or plugin facility.
+
+## 2. Adapter work
+
+### Typed inputs and fresh state
+
+Translate CommandKit's explicit bindings into backend flag bindings and operand
+assignments. Create a fresh backend command tree and fresh input storage for each
+invocation from registered definitions. Construction must not load configuration,
+resolve credentials, or create execution dependencies.
+
+### Presence and repetition
+
+Record CLI presence independently of parsed defaults, preserving explicit empty,
+false, and zero values. Transfer presence into the typed fields selected by each
+command; handlers must not need backend flag lookups.
+
+Resolve repetition and grammar choices before enforcing them. The CLI plan's
+singleton-repetition rejection is still a proposal. If selected, enforce it
+explicitly using registered metadata while preserving ordered accumulation for
+repeatable inputs. Exercise interspersed flags, values beginning with `-`, and
+`--` against the selected contract; avoid application-maintained flag-name lists.
+
+### Help and command discovery
+
+Generate help from one registry's metadata for standard and application commands,
+using backend machinery with the selected CommandKit presentation. Keep help and
+version usable without configuration or runtime construction.
+
+Configure automatic backend behavior to match the chosen inventory. Backend
+completion support does not itself add a standard completion command. Parent and
+family help, unknown-command handling, operands, and leaf help need explicit
+contract choices rather than incidental defaults.
+
+### Diagnostics and outcomes
+
+Use backend context and stream support. Translate backend-owned syntax failures
+into CommandKit diagnostics/outcomes and avoid duplicate emission. Preserve the
+selected distinctions among usage errors, valid-invocation failures, and custom
+application outcomes. Do not match domain error strings or print usage for every
+runtime failure. Return control to the application for process termination.
+
+### Provider integration and native reports
+
+Install selected standard families from supplied providers and acquire their data
+lazily. Scope dependencies and native YAML rendering remain CommandKit integration
+work through ConfigKit/PromptKit public inspection APIs.
+
+Implement accepted `config show --scope all` using native writers and the YAML
+stream contract in the CLI plan. Preserve the initial JSON deferral. A parser
+backend creates no need for another configuration loader or public backend-specific
+provider types.
+
+## 3. Delivery sequence and evidence
+
+1. Select and pin Cobra/pflag versions and record their actual licensing/notices.
+2. Design the neutral internal definitions required by the public registry and
+   typed-binding API, then implement translation within the adapter boundary.
+3. Exercise representative standard and application command definitions, including
+   the examples in the dispatcher roadmap, against selected semantics.
+4. Introduce meaningful integration evidence for conflicts, nested routing, help
+   with invalid configuration, repetition, presence, `--`, fresh state, context
+   and streams, failed writers, and application outcomes. Adapt defaults as needed
+   without treating that work as grounds to reopen the accepted selection.
+5. Integrate standard handlers and coordinate breaking application adoption under
+   the CLI delivery plan. Update consumer docs and subprocess adapters.
+
+The testing policy owns check selection; the architecture policy owns boundaries.
+The ADR owns the backend-selection rationale and reviewed primary references.
+No second backend or generalized backend framework is a prerequisite.

docs/roadmap/04-facade.md

@@ -0,0 +1,77 @@
+# CommandKit public facade implementation
+
+Status: accepted facade and adapter boundary; implementation pending.
+
+Date: 2026-10-06.
+
+[ADR 0003](../adr/0003-public-facade.md) owns the root facade, internal adapter,
+alternatives, and rationale. The [architecture policy](../policy/architecture.md)
+owns normative dependency and public-surface rules. This roadmap tracks exact API
+work, illustrative package organization, and implementation evidence.
+
+The [dispatcher roadmap](02-dispatch.md) tracks registry and typed inputs; the
+[backend roadmap](03-backend.md) tracks Cobra/pflag translation. The CLI plan
+retains command and operator-contract proposals and their approval status.
+
+## 1. Current status
+
+The root `commandkit` facade and internal Cobra/pflag isolation are accepted.
+No public declarations, implementation packages, adapter, dependency versions,
+or boundary checker exist yet. There is no public backend selection facility.
+
+## 2. API and internal representation design
+
+1. Design root-owned registration, binding, provider, invocation, and outcome
+   contracts around demonstrated consumer needs. Application input types remain
+   application-owned.
+2. Identify internal definitions and private callbacks that let implementation
+   invoke typed handlers without importing the root facade or exposing backend
+   structures. Separate fresh input lifetime from registration and dependencies.
+3. Use private state and explicit forwarding/conversions, preserving ownership,
+   callback lifetime, presence, supported error identity, and cancellation.
+4. Translate backend-owned failures without returning backend objects, including
+   through errors or loosely typed values. Preserve useful application error
+   identity according to the selected invocation contract.
+5. Select any public dependency types deliberately. Standard context/stream
+   contracts are appropriate; ConfigKit/PromptKit types require an API choice.
+
+### Illustrative package layout
+
+| Package | Possible responsibility |
+| --- | --- |
+| Root `commandkit` | Consumer facade, selected contracts, and conversions. |
+| `internal/engine` | Registry, ownership checks, capability installation, and invocation coordination. |
+| `internal/command`, if needed | Shared definitions and contracts independent of the backend. |
+| `internal/cobra` | Cobra/pflag integration, bindings, and diagnostic translation. |
+
+These names and splits are illustrative, not an implemented inventory or required
+package-per-concern layout. Select cohesive packages during implementation. A
+narrow internal engine/adapter interface may be useful where actual interaction
+justifies it. Do not require a public backend interface or a second implementation.
+
+## 3. Boundary protection and consumer evidence
+
+With implementation, introduce proportionate checks for:
+
+- Compiled public exports, including aliases, fields, signatures, constraints,
+  callbacks, and promoted methods exposing internal or backend types.
+- Import direction: internal production code must not import root, and Cobra/pflag
+  types and operations belong in the adapter.
+- Consumer behavior through the actual adapter, including conversions, fresh
+  state, public error identity, and selected invocation semantics.
+
+ConfigKit and ReleaseKit provide precedents for compiled API and import checks;
+reuse the approach where it protects this boundary without copying their entire
+validation suites or domain restrictions.
+
+## 4. Completion and later replacement
+
+Introduce GoDoc, consumer guidance, implemented CLI reference, and internal
+inventory with their corresponding code. Those become canonical owners of exact
+API and current behavior; ADRs retain decision rationale.
+
+A later backend replacement should preserve the public Go API and selected CLI
+behavior, or follow the release policy for deliberate incompatible behavior.
+Protecting signatures alone is insufficient evidence for parsing, help,
+diagnostics, report, and status compatibility. This is future maintenance scope,
+not an instruction to implement or exercise a replacement now.

docs/roadmap/policy.md

@@ -0,0 +1,106 @@
+# CommandKit policy adoption and follow-up
+
+Status: initial adoption and decision alignment complete; implementation-specific
+follow-up pending.
+
+Date: 2026-10-06.
+
+This document records completion of the initial adoption and retains work tied to
+future library implementation. Local policies are authoritative. Architectural
+rationale now belongs in ADRs, and the implementation roadmaps retain pending
+work. The CLI proposal keeps its accepted choices and remaining recommendations.
+
+## 1. Adopted baseline
+
+The seven policies were adapted from Standard Repository Policies at:
+
+`d84a38ebab26f048cafbe59a2246700c35d29843`
+
+The selected commit is available in the local upstream checkout and is the
+baseline used by PromptKit, ConfigKit, and ReleaseKit. Adoption used that fixed
+revision rather than relying on remote freshness. Each local policy preserves its
+base version, records the actual adoption date, and links to its source file at
+that commit. Updates require deliberate review under
+[policy provenance](../policy/meta.md) and the upstream adoption guide.
+
+| Adopted policy | Base version | Adaptation |
+| --- | --- | --- |
+| [Meta](../policy/meta.md) | 1.0 | Local authority, provenance, and upstream navigation. |
+| [Agents](../policy/agents.md) | 1.3 | Proportionate implementation, explicit contract authority, and local commits. |
+| [Architecture](../policy/architecture.md) | 1.3 | Dispatcher, registry, typed inputs, root facade, adapter, and ownership constraints. |
+| [Testing](../policy/testing.md) | 1.3 | Offline behavioral evidence and CommandKit-specific risk priorities. |
+| [Documentation](../policy/documentation.md) | 1.11 | Go API and CLI owners, ADR rationale, and roadmap implementation status. |
+| [Release](../policy/release.md) | 1.4 | Source-only module publication and Go/CLI compatibility. |
+| [OSS](../policy/oss.md) | 1.8 | Library grant, policy-document license scope, and factual attribution. |
+
+Template adoption sections were removed. Reference examples remain upstream;
+source and example links are pinned, while discovery links may track upstream
+main. No automatic synchronization, recurring synchronization gate, or separate
+license approval flow was added.
+
+## 2. Initial adoption outcomes
+
+- Root [AGENTS.md](../../AGENTS.md) preserves the supplied knowledge-graph
+  instructions and adds adopted contributor orientation.
+- The [developer guide](../development.md) routes tasks to relevant policies and
+  gives proportionate current documentation validation guidance.
+- [COPYRIGHT](../../COPYRIGHT) records the `LGPL-3.0-or-later` library grant and
+  separate CC-BY-SA-4.0 scope for adopted policies and copied orientation/reading
+  guidance. Existing independently supplied instructions remain outside that
+  copied-material scope.
+- Root [LICENSE](../../LICENSE) retains the existing complete LGPL/GPL texts.
+- [Attribution](../oss/attribution.md) identifies the exact adapted material and
+  commit-specific source/notices, with the standard CC-BY-SA text copied locally.
+- The [README](../../README.md) gives truthful current status, navigation, and
+  grant/attribution links. No public API, executable, or release tooling is claimed.
+
+The adopted agents policy authorizes local commits for completed units by default,
+subject to explicit user instructions. It does not authorize pushing, publishing,
+or history rewriting. Review and preserve unrelated work before committing.
+
+## 3. Decision alignment
+
+| Accepted decision | Durable owner | Pending implementation |
+| --- | --- | --- |
+| Dispatcher ownership, explicit per-instance registry, namespace boundary, and typed inputs | [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) | [Dispatcher roadmap](02-dispatch.md) |
+| Cobra/pflag as the sole initial backend | [ADR 0002](../adr/0002-cobra-backend.md) | [Backend roadmap](03-backend.md) |
+| Root-owned public contracts and an internal Cobra adapter | [ADR 0003](../adr/0003-public-facade.md) | [Facade roadmap](04-facade.md) |
+
+The architecture policy owns normative boundaries. Accepted ADRs preserve context,
+choices, alternatives, and consequences without asserting that implementation
+exists. The three implementation roadmaps now link to those records instead of
+maintaining duplicate architectural rationale.
+
+The [CLI proposal](01-cli-plan.md) remains the owner of future operator-contract
+proposals and their individual approval status. Adoption did not approve the
+remaining command inventory, grammar, exit statuses, or illustrative APIs.
+
+## 4. Follow-up with implementation
+
+| Work | Introduce when |
+| --- | --- |
+| Exact API declarations and GoDoc | Public registration, binding, provider, and invocation operations are implemented. |
+| Task-oriented consumer guides and maintained examples | There are substantive supported consumer workflows. |
+| `docs/cli.md` | Standard commands and operator contracts are implemented. |
+| Internal inventory and subsystem documentation | Actual packages and mechanisms exist. |
+| Cobra/pflag versions, notices, and license texts | Dependencies are incorporated; selection alone is not incorporation. |
+| Proportionate boundary and consumer checks | Code introduces the public facade and backend adapter. |
+| `docs/release.md`, publication tooling, and release notes | A releasable source module and working publication workflow exist. |
+
+ConfigKit and PromptKit keep ownership of configuration and prompt semantics.
+CommandKit documents their CLI exposure and links to their canonical contracts.
+Select meaningful checks for actual CommandKit risks; do not inherit another
+library's platform matrix, scanners, or validation gates automatically.
+
+ReleaseKit remains a candidate for publication mechanics, not a selected
+integration. Source-only releases are sufficient. Compatibility covers published
+Go and CLI contracts, including parser behavior and YAML reports, even when Go
+signatures are unchanged.
+
+## 5. Completion boundary
+
+Initial adoption comprises the customized policy set, supporting notices,
+contributor navigation, and alignment of already accepted decisions. That work is
+complete. The follow-up above remains future implementation scope; empty CLI/API
+references, checker code, release scripts, and speculative dependency entries are
+not prerequisites to policy adoption.