Document Promptkit development and releases

LICENSE

@@ -208,7 +208,7 @@ If you develop a new program, and you want it to be of the greatest possible use
 
 To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
 
-     go-application-template
+     Promptkit
      Copyright (C) 2026  eric
 
      This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
@@ -221,7 +221,7 @@ Also add information on how to contact you by electronic and paper mail.
 
 If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:
 
-     go-application-template  Copyright (C) 2026  eric
+     Promptkit  Copyright (C) 2026  eric
      This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
      This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
 

README.md

@@ -1,3 +1,18 @@
-# PromptKit
+# Promptkit
 
-TODO
+Promptkit is the reusable Go prompt-execution framework being separated from
+Scriptorium. Its module path is:
+
+```text
+gitea.maximumdirect.net/eric/promptkit
+```
+
+The repository currently provides the independent Go module and its root public
+package boundary. Framework behavior and consumer APIs have not yet been
+extracted, so there is no installation or usage example at this time.
+
+Contributors should start with the [development guide](docs/development.md).
+The [architecture policy](docs/policy/architecture.md) defines the library
+boundary and constraints that future framework work must preserve.
+
+Promptkit is licensed under the [GNU General Public License version 3](LICENSE).

doc.go

@@ -0,0 +1,2 @@
+// Package promptkit defines the public package boundary for the Promptkit Go module.
+package promptkit

docs/development.md

@@ -1,54 +1,137 @@
 # Development
 
-This is the contributor entry point for thsi application. Use the task-specific
+This is the contributor entry point for Promptkit, a reusable Go library. All
-reading guide below before making changes. Canonical architecture, contracts,
+contributors must read the
-component behavior, and policies remain in their owning documents.
+[architecture policy](policy/architecture.md) before making changes.
 
 ## Initial Orientation
 
 Before starting work:
 
 1. inspect the working tree and preserve unrelated changes;
-2. read the architecture policy for code or design work;
+2. read the policy, contract, and internal documents listed for the task;
-3. read the policy, contract, and internal documents listed for the task;
+3. inspect the relevant implementation and tests before deciding how to change
-4. inspect the relevant implementation and tests before deciding how to change
+   them; and
-   them.
+4. keep documentation limited to implemented behavior unless an accepted
+   decision or temporary roadmap explicitly owns future work.
 
 Start with:
 
-- [Architecture policy](policy/architecture.md) for system boundaries,
+- the [architecture policy](policy/architecture.md) for library boundaries,
-  invariants, and non-goals;
+  dependency direction, invariants, and non-goals;
-- [Internal component overview](internal/overview.md) for the current package
+- the [internal component overview](internal/overview.md) for the current
-  and component map;
+  package and component inventory;
-- [Documentation policy](policy/documentation.md) before changing
+- the [documentation policy](policy/documentation.md) before changing
   documentation;
-- [Testing policy](policy/testing.md) before adding, rewriting, or deleting
+- the [testing policy](policy/testing.md) before adding, rewriting, or deleting
-  tests.
+  tests; and
+- the [release procedure](release.md) for version and publication work.
 
 ## Task-Specific Reading Guide
 
 | Task | Read before changing |
 | --- | --- |
-| Repository orientation or component responsibility | [Internal component overview](internal/overview.md) and [architecture policy](policy/architecture.md) |
+| Documentation or examples | The [documentation policy](policy/documentation.md) and the canonical owner of the affected contract. |
-| Examples or copyable assets | The owning contract for the demonstrated behavior and the related files under `examples/` |
+| Tests or test fixtures | The [testing policy](policy/testing.md), the owning package, and any focused internal document listed by the component overview. |
-| Architecture decisions or future work | The [documentation policy](policy/documentation.md) and relevant accepted ADRs |
+| Root public API, once implemented | The [architecture policy](policy/architecture.md), [root package declaration](../doc.go), [testing policy](policy/testing.md), and existing GoDoc. |
+| Internal package implementation, once introduced | The [architecture policy](policy/architecture.md), [internal component overview](internal/overview.md), and any focused internal document that the overview lists for that package. |
+| Integration behavior, once introduced | The [architecture policy](policy/architecture.md), [documentation policy](policy/documentation.md), and the integration's owning contract under `docs/integrations/`. |
+| Release preparation or publication | The [release procedure](release.md). |
 
-For cross-cutting changes, follow every applicable row. Internal component
+For cross-cutting changes, follow every applicable row. Do not create
-documents own detailed subsystem change recipes.
+placeholder documents for packages, APIs, or integrations that do not yet
+exist.
 
-## Baseline Validation
+## Maintainer-Run Validation
 
-Use focused checks while iterating, then run validation proportionate to the
+Promptkit does not currently use hosted CI. Maintainers are responsible for
-change and the risks described by the testing policy.
+running the documented checks before accepting changes. Run the default Go
+validation from the Promptkit repository root:
 
-The repository-level baseline for code changes is:
+```sh
-
-```bash
 go test ./...
 go vet ./...
-go build ./cmd/scriptorium
+go build ./...
 ```
 
-Documentation-only work does not require the full Go suite unless it changes
+Check formatting across every tracked Go file:
-commands, examples, generated output, or another behavior that the suite
+
-validates. Always check changed links, paths, examples, and canonical ownership.
+```sh
+gofmt -l $(git ls-files '*.go')
+```
+
+The formatting command must produce no paths. Follow every added or changed
+Markdown link and confirm its target exists. Finally, check whitespace:
+
+```sh
+git diff --check
+```
+
+Documentation-only work does not require unrelated new tests, but it still
+requires link validation and `git diff --check`. Run the Go validation whenever
+documentation changes commands, examples, generated output, or another
+behavior checked by the module.
+
+## Focused Validation
+
+Use focused checks while iterating, then run the complete validation sequence
+before accepting the change. The root package currently supports:
+
+```sh
+go test .
+go vet .
+go build .
+```
+
+Filter tests by name without assuming a future package layout:
+
+```sh
+go test ./... -run 'TestName'
+```
+
+Replace `TestName` with a useful regular expression. When internal packages are
+introduced, target only paths that actually exist, such as
+`go test ./path/to/package`, and consult the internal component overview for
+their owning documentation. A filtered or package-specific run does not replace
+the complete repository validation.
+
+## Coordinated Work With Scriptorium
+
+Promptkit and Scriptorium must remain independently valid. For temporary local
+integration, use either a Go workspace outside both repositories or an
+uncommitted replacement in the consuming module.
+
+If the repositories are sibling directories, run the workspace commands from
+their parent directory:
+
+```sh
+go work init ./promptkit ./scriptorium
+go work sync
+```
+
+Use the workspace only for coordinated local checks. From the same parent
+directory, remove it when finished:
+
+```sh
+rm -f go.work go.work.sum
+```
+
+Alternatively, from the Scriptorium repository root, temporarily point its
+Promptkit dependency at the sibling checkout:
+
+```sh
+go mod edit -replace gitea.maximumdirect.net/eric/promptkit=../promptkit
+```
+
+After coordinated checks, remove the replacement and reconcile module
+metadata:
+
+```sh
+go mod edit -dropreplace gitea.maximumdirect.net/eric/promptkit
+go mod tidy
+```
+
+Never commit `go.work`, `go.work.sum`, or a local filesystem `replace`
+directive. Before committing in either repository, inspect its module files and
+working tree independently. Published consumer versions must depend on a tagged
+Promptkit version, not a workspace, local replacement, or unpublished commit.

docs/internal/overview.md

@@ -2,12 +2,23 @@
 
 ## Purpose
 
-This is the inventory of this application's implemented components for contributors.
+This document inventories Promptkit's implemented components for contributors.
-The [architecture policy](../policy/architecture.md) owns normative boundaries
+The [architecture policy](../policy/architecture.md) owns durable boundary and
-and invariants; public behavior belongs in the linked contracts.
+dependency rules. See the [development guide](../development.md) for
+contributor workflow and validation.
 
-TODO: Add tables below, using the following format:
+## Implemented Components
 
 | Component | Implemented responsibility | References |
 | --- | --- | --- |
-| | | |
+| Root `promptkit` package | Establishes the public package boundary for the Go module. It does not yet provide migrated framework behavior or exported APIs. | [Package declaration](../../doc.go) |
+
+The root `promptkit` package is the sole implemented Go package. No internal
+framework packages exist yet.
+
+## Maintenance
+
+Update this inventory as framework extraction introduces packages or changes
+component responsibilities. List only implemented components; proposed package
+boundaries belong in temporary planning documents until their implementation
+lands.

docs/policy/architecture.md

@@ -1,13 +1,118 @@
-# Architecture
+# Architecture Policy
 
-This document defines the intended high-level architecture of this application and the
+## Purpose
-invariants that changes must preserve. Implemented component details belong in
+
-[Internal Overview](../internal/overview.md) and its linked documents. The
+This document defines Promptkit's current high-level architecture and the
-reasoning behind significant architectural choices belongs in
+durable boundaries that implementation changes must preserve. The
-[ADRs](../adr/).
+[internal component overview](../internal/overview.md) inventories concrete
+implemented packages without redefining these rules.
 
 ## System Shape
 
-This application is a small, dependency-light Go application for ...
+Promptkit is an importable Go library. It does not provide a runnable command,
+an HTTP service, or another application process.
 
-TODO: Complete this document.
+The module root contains package `promptkit`, which is the public facade and the
+only implemented Go package in the current repository foundation. It declares
+the module's public package boundary but does not yet provide migrated framework
+behavior or exported APIs. No internal framework packages currently exist.
+
+Future framework extraction must follow this dependency direction:
+
+```text
+downstream consumers, including Scriptorium
+                    |
+                    v
+       root promptkit public facade
+                    |
+                    v
+       internal framework components
+                    |
+                    v
+        narrow injected abstractions
+```
+
+The facade may coordinate internal components. Internal components must depend
+on narrow abstractions for behavior supplied from outside the library; they
+must not depend on consumers or on Scriptorium. This diagram constrains future
+work and does not assert that the internal components already exist.
+
+## Repository And Consumer Boundary
+
+Scriptorium is a downstream application that will consume Promptkit through
+the supported public facade. It is not a Promptkit package and must not become
+an internal dependency.
+
+Promptkit owns reusable, application-neutral library behavior. It does not own:
+
+- binaries or executable packaging;
+- CLI commands, parsing, streams, or exit codes;
+- HTTP routes, servers, request DTOs, status mapping, or deployment policy;
+- application configuration discovery or precedence;
+- process lifecycle, operational state, or application logging; or
+- consumer-specific filesystem or security policy.
+
+Those concerns remain with Scriptorium or another consuming application.
+
+## Package Ownership
+
+The module root is the supported public facade. Framework implementation
+packages belong under Go's `internal/` boundary unless a demonstrated, stable
+consumer contract requires a public package.
+
+Each package must have one cohesive responsibility and a clear dependency
+direction. Internal packages must not expose their types merely to simplify
+wiring, and the public facade must not leak internal representations through
+exported signatures. New public packages require a durable consumer need that
+cannot be served cleanly by the root facade.
+
+The [internal component overview](../internal/overview.md) must be updated as
+packages are implemented or their responsibilities change.
+
+## Exported API Discipline
+
+Export the smallest contract required by real consumers. Exported declarations
+must have accurate GoDoc, stable semantics, and tests proportionate to their
+compatibility risk. Avoid speculative extension points, aliases for internal
+types, and public constructors that expose assembly details.
+
+Once an exported API exists, its Go declaration and GoDoc own its exact public
+contract. Architecture documentation owns boundary rules, not a duplicate API
+reference.
+
+## Error Boundaries
+
+Internal failures must cross the public facade as errors meaningful to a Go
+consumer without exposing private package types or transport-specific policy.
+Wrapping should add useful context while preserving any public error identity
+needed with `errors.Is` or `errors.As`.
+
+Promptkit must not assign CLI exit codes or HTTP status codes. Consumers map
+public library outcomes into their own transport behavior.
+
+## Dependency Injection
+
+External effects and consumer-selected policy must enter through narrow
+interfaces or functions at the boundary that uses them. Dependencies should be
+explicitly supplied during construction or invocation rather than read from
+consumer configuration or hidden process-global state.
+
+Interfaces should be owned by the code that consumes the behavior and should
+contain only the operations that code requires. Provide defaults only for
+application-neutral behavior; consumer-specific restrictions and adapters
+remain injected from the consuming project.
+
+## Repository Independence
+
+Promptkit must build, test, and validate independently of Scriptorium. Do not
+commit `go.work`, `go.work.sum`, or a local filesystem `replace` directive.
+Temporary workspace or replacement configuration may support coordinated local
+development, but it is not part of either repository's architecture or release
+state.
+
+## Current-State Maintenance
+
+This policy distinguishes present implementation from constraints on future
+framework extraction. Do not list planned packages as implemented components.
+When extraction introduces a package, update the internal inventory and the
+owning contract or subsystem document in the same change.

docs/policy/documentation.md

@@ -2,112 +2,115 @@
 
 ## Purpose
 
-This policy assigns each documentation topic to one canonical owner. Its goal is
+This policy assigns each Promptkit documentation topic to one canonical owner.
-to keep this application's documentation accurate, concise, discoverable, and resistant
+Its goal is to keep documentation for this reusable Go library accurate,
-to drift for users, operators, developers, integrators, and LLM coding agents.
+concise, discoverable, and resistant to drift for consumers, contributors,
+maintainers, integrators, and coding agents.
 
 ## Core Rules
 
 ### One Canonical Owner
 
-Each authoritative fact belongs in one document. A non-owning document may give
+Each authoritative fact belongs in one document or source form. A non-owning
-a short, stable summary for orientation, but it must link to the canonical owner
+document may give a short, stable summary for orientation, but it must link to
-instead of repeating volatile details.
+the canonical owner instead of repeating exact contracts.
 
-Volatile details include commands, flags, configuration fields and defaults,
+Volatile details include exported declarations, accepted inputs, defaults,
-module keys, schemas, file names, paths, status codes, retry behavior, and
+schemas, file names, paths, error identities, retry behavior, and runtime
-runtime guarantees. If readers could reasonably treat a statement as a
+guarantees. If readers could reasonably treat a statement as a contract,
-contract, maintain it only in the owning document.
+maintain its exact definition only in the owning source.
 
-### Current And Future Behavior
+### Current State, Decisions, And Future Work
 
 Outside `docs/roadmap/`, documentation describes implemented behavior only.
 Partial features may be described only to their implemented boundary.
 
-ADRs are the narrow exception: an ADR may record an accepted architectural
+An accepted architecture decision may describe an approved direction before it
-decision before implementation, but acceptance must not be presented as proof
+is implemented, but acceptance is not evidence that the behavior exists.
-that the behavior exists. The roadmap owns implementation status and sequencing
+Current-state documents change when the implementation lands. Temporary
-until the decision is implemented. Current architecture, user, operator,
+roadmaps own future work, sequencing, and implementation status; they do not
-integration, and internal documentation are updated when the behavior lands.
+replace durable policies or current contracts.
 
 ### Audience And Detail
 
 Write for the document's stated audience and include only the detail needed for
-its owned topic. User and operator docs should not expose implementation detail.
+its owned topic. Consumer guidance should not expose incidental implementation
-Developer docs should link to user-facing and external contracts rather than
+detail. Contributor documentation should link to public contracts and durable
-restate them.
+policies instead of restating them.
 
-### Examples
+### Links
 
-Complete copyable files belong in `examples/`. Documentation may use the
+Use descriptive link text and repository-relative links for repository
-smallest illustrative snippet needed to explain its owned topic, but should link
+documents. Link to the canonical owner rather than to a duplicate summary.
-to maintained examples instead of embedding a second complete copy.
+Check every added or changed link and repair or remove links when their target
+moves or is retired.
 
-Examples must be valid, secret-free, and tested where practical. Commands and
+### Examples And Code Fences
-configuration used in documentation should match the application.
+
+Complete copyable files belong in `examples/` when maintained examples exist.
+Documentation may use the smallest illustrative snippet needed for its owned
+topic, but should link to a maintained example instead of embedding a second
+complete copy.
+
+Examples must be valid, secret-free, and tested where practical. Commands,
+imports, and Go snippets must match the implemented library. Use a language tag
+on fenced code blocks and make clear when a fragment is illustrative rather
+than directly runnable.
 
 ### Security And Privacy
 
 Documentation and examples must not contain real credentials, private keys,
-private environment dumps, sensitive source material, or private infrastructure
+private environment dumps, sensitive source material, or private
-details unless intentionally public. Document secret-handling mechanisms, not
+infrastructure details unless intentionally public. Document secret-handling
-secret values.
+mechanisms, not secret values.
 
 ## Canonical Ownership
 
 | Topic | Canonical owner | Owned content | Content owned elsewhere |
 | --- | --- | --- | --- |
-| Product orientation and minimal end-to-end quickstart | `README.md` | What this application is, why it is useful, one shortest successful invocation, and links onward. | Complete command reference, configuration reference, operational procedures, implementation detail. |
+| Project orientation | `README.md` | What Promptkit is, its current usability, module identity, license summary, and links onward. | Exact API contracts, contributor procedures, architecture detail, and release steps. |
-| Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. |
+| Contributor workflow | `docs/development.md` | Task-oriented reading guide, local workflow, validation commands, and repository hygiene. | Architecture rules, API semantics, subsystem behavior, and release procedure. |
-| Current application architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
+| Current architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, package boundaries, invariants, and non-goals. | Concrete component inventory, implementation mechanics, contributor procedures, decision history, and future work. |
-| Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
+| Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and document lifecycle. | Library architecture or runtime behavior. |
-| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
+| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression policy, and test maintenance. | Subsystem behavior, exact public contracts, subsystem-specific test inventories, and implementation plans. |
-| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
+| Release procedure | `docs/release.md`, when present | Required release validation, version and tag procedure, release ordering, and post-publication checks. | General contributor workflow, public API semantics, and decision history. |
-| Configuration contract | `docs/config.md` | Discovery and precedence, file schema, fields, defaults, environment overrides, validation rules, and user-selectable module or validator keys. | Complete example files, CLI syntax, runtime state lifecycle, module implementation details. |
+| Exact exported Go API | Go declarations and GoDoc, as APIs are implemented | Exported names, signatures, types, values, errors, and exact behavioral contracts. | Task-oriented consumer walkthroughs, implementation details, and future API proposals. |
-| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache, and debug handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
+| Consumer guidance | `docs/consumers/`, when consumer workflows require dedicated guidance | Task-oriented use of implemented public APIs, minimal examples, and consumer responsibilities. | Exact exported declarations and internal mechanics. |
-| Public HTTP contract, if introduced | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
+| Durable integration contracts | `docs/integrations/`, when integrations exist | External formats and protocols, compatibility behavior, and upstream or downstream responsibilities. | Internal transformations and public Go declarations. |
-| Consumer guidance, if a public package or API is introduced | `docs/consumers/` | Task-oriented use of the public interface, minimal client examples, and consumer responsibilities. | HTTP wire semantics, external protocol contracts, internal implementation detail. |
+| Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal documents. | Normative architecture, contributor workflow, external contracts, and proposed components. |
-| External and durable integration contracts | `docs/integrations/` | External file formats and protocols, upstream and downstream contracts, logical output bundle paths and schemas, media types, and compatibility behavior. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
+| Internal subsystem behavior | Other files under `docs/internal/`, when a subsystem needs durable detail | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, public API definitions, and future package plans. |
-| Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
+| Architectural decision history | `docs/adr/`, when repository-local decisions require records | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, and task sequencing. |
-| Internal component behavior | Other files under `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
+| Temporary feature roadmaps | `docs/roadmap/`, while planned work needs coordination | Proposed or accepted scope, sequencing, gates, and implementation status. | Implemented behavior reference and durable decision rationale. |
-| Architectural decision history | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
+| Complete copyable artifacts | `examples/`, when maintained examples exist | Valid inputs, Go programs, and other files intended to be copied or run. | Field-by-field reference, exact API declarations, and prose explanation. |
-| 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. |
-| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. |
 
-Documents that do not exist are required only when the corresponding interface
+Conditional owners do not require placeholder files or directories. Create a
-or responsibility exists. Do not create placeholder API, consumer, integration,
+consumer, integration, subsystem, ADR, roadmap, or example document only when
-or operations documents for behavior the application does not have.
+the corresponding implemented interface, decision, planned effort, or
+maintained artifact exists.
 
 ## Boundary Rules
 
 ### Orientation
 
-The README owns product orientation. The developer guide routes contributors.
+The README owns project orientation. The development guide routes
-Architecture owns normative structure. Internal overview owns the current
+contributors. Architecture owns normative structure. The internal overview
-concrete component map. These documents may link to one another but should not
+owns the current concrete component map. These documents may link to one
-maintain parallel package or behavior descriptions.
+another but must not maintain parallel package or behavior descriptions.
 
-### Commands, Configuration, And Operations
+### Public Contracts And Implementation
 
-CLI documentation answers how to invoke the application. Configuration
+Go declarations and GoDoc own exact exported API contracts once those APIs
-documentation answers what settings mean. Operations answers what happens to
+exist. Consumer and integration documents explain how to use those contracts
-runtime state and how to operate or recover the application. When a workflow
+for a task. Internal documents explain how Promptkit implements them. Internal
-crosses these topics, choose the document that owns the task and link to the
+documentation may identify a public type or external format as a dependency,
-other contracts.
+but must link to its canonical definition rather than restate it.
-
-### Contracts And Implementation
-
-Integration and API documents define externally observable shapes and
-semantics. Internal documents explain how thos application 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
-application security invariants. Configuration owns credential-supply
+library security boundaries and invariants. Public declarations and integration
-mechanisms. Operations owns permissions and handling of sensitive runtime
+documents own consumer-visible security contracts. Internal documents own
-artifacts. Internal docs own implementation mechanisms only.
+implementation mechanisms only.
 
 ## Architecture Decision Records
 
@@ -122,23 +125,44 @@ Use sequentially numbered ADR filenames such as
 6. alternatives considered;
 7. consequences.
 
-Treat the decision content of an accepted ADR as immutable. When a decision
+Use one of these statuses:
-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
+- **Proposed:** the decision is under consideration and may change;
+- **Accepted:** the decision is approved, whether or not implementation is
+  complete;
+- **Rejected:** the proposed decision was considered and not adopted;
+- **Superseded:** a later accepted ADR replaces the accepted decision.
 
-When behavior changes, update its canonical owner in the same change. If
+A proposed ADR transitions to Accepted or Rejected. An Accepted ADR transitions
-ownership moves, remove the old definition and replace it with a link where
+to Superseded only when a later Accepted ADR replaces it. An ADR may be created
-navigation remains useful.
+as Accepted when the decision has already been made.
+
+Treat the decision content of an Accepted ADR as immutable. A changed decision
+requires a later ADR rather than a rewrite of the accepted record. A Superseded
+ADR must link to its replacement, and the replacement must link back. Rejected
+architectural alternatives belong in the ADR; rejected feature ideas belong in
+a roadmap when they need to be retained.
+
+## Document Lifecycle
+
+Create durable current-state documentation with the implementation it
+describes. Update its canonical owner in the same change when behavior changes.
+If ownership moves, remove the old definition and leave a link where navigation
+remains useful.
+
+Roadmaps are temporary coordination documents. When their work is complete,
+record completion, move any still-useful decisions or contracts to their
+durable owners, update incoming links, and archive or remove the roadmap
+according to repository practice. Do not preserve completed roadmaps as a
+second current-state reference.
 
 Before completing documentation work:
 
 - verify affected behavior and examples;
-- check commands, flags, fields, defaults, schemas, and paths against their
+- check commands, imports, declarations, defaults, schemas, and paths against
-  implementation;
+  their implementation;
-- keep unimplemented behavior in the roadmap, subject to the ADR exception;
+- keep unimplemented behavior in a roadmap, subject to the ADR exception;
-- remove stale references and validate links;
+- validate links and fenced examples;
-- confirm that non-owning documents summarize and link rather than redefine;
+- confirm non-owning documents summarize and link rather than redefine;
+- remove stale or unsupported claims; and
 - confirm that no secrets or sensitive private data were added.

docs/policy/testing.md

@@ -14,7 +14,7 @@ A test must be:
 
 - written and reviewed;
 - understood by future maintainers and coding agents;
-- executed in local and CI workflows;
+- executed in maintainer-run validation;
 - diagnosed when it fails;
 - updated when legitimate behavior changes;
 - maintained as fixtures, APIs, and dependencies evolve; and
@@ -49,9 +49,40 @@ Examples of appropriate seams include clocks, randomness, subprocesses, remote A
 
 ## Test execution requirements
 
-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.
+Promptkit currently uses maintainer-run validation rather than hosted CI.
+Maintainers run the repository-documented test, vet, build, formatting,
+documentation-link, and repository-hygiene checks before accepting changes.
+Introducing hosted CI later would supplement, not silently redefine, this
+documented validation model.
 
-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.
+Tests in the default suite must be deterministic, offline, and independent of
+real credentials. They must not invoke paid APIs, use live network
+dependencies, 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 must be parallel-safe:
+they should run repeatedly and alongside other tests without depending on
+execution order, shared mutable state, fixed ports, or state left by an earlier
+test.
+
+## Test types and assets
+
+Use each test type where it protects a distinct risk:
+
+- Unit and package tests protect focused behavior and invariants through the
+  narrowest stable boundary.
+- Contract tests protect exported behavior, compatibility, and error identity
+  relied upon by consumers.
+- Integration tests use real collaborators when correctness depends on their
+  interaction, while replacing live or nondeterministic external boundaries.
+- Fixtures should be minimal, synthetic, versioned with the behavior they
+  exercise, and free of credentials or private data.
+- Golden files are appropriate only when the complete output is intentionally
+  stable and semantic review of updates is practical.
+- Failure-path tests should cover consequential malformed input, dependency
+  failure, cancellation, partial results, and recovery behavior.
 
 ## What deserves tests
 
@@ -63,7 +94,7 @@ Prioritize tests for:
 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.
+7. Representative integration and consumer workflows.
 
 A package-level contract is behavior relied upon by another package or major collaborator, not every observable detail of a package implementation.
 
@@ -81,7 +112,9 @@ This is often the package API, but it may instead be:
 - 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.
 
-Do not force all behavior through oversized end-to-end tests. Do not test every private helper merely because it exists. Choose the boundary that gives durable confidence with the least incidental coupling.
+Do not force all behavior through oversized consumer-workflow tests. Do not
+test every private helper merely because it exists. Choose the boundary that
+gives durable confidence with the least incidental coupling.
 
 ## Test behavior, not implementation
 
@@ -165,10 +198,10 @@ Each behavior should have a clear test owner.
 - Parser tests own parsing cases.
 - Validator tests own validation rules.
 - Domain tests own transformations and invariants.
-- Adapter tests own external integration behavior.
+- Boundary tests own external integration behavior.
 - Orchestrator tests own coordination and failure propagation.
-- CLI tests own argument and configuration mapping.
+- Consumer-workflow tests prove that representative assembled library use
-- End-to-end tests prove that representative assembled workflows work.
+  works.
 
 Higher-level tests should not repeat every lower-level case. A single intentional policy change should not require unrelated edits across many test files.
 
@@ -205,13 +238,17 @@ Use:
 - fuzz tests for parsers, normalization, path handling, and broad input spaces;
 - 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.
+- a small number of representative consumer-workflow tests.
 
 Avoid exact error-string assertions unless the wording is itself contractual. Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields.
 
-At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Do not snapshot complete diagnostic wording unless it is contractual.
+At public API boundaries, prefer stable error identity, structured values, and
+the smallest semantic fragment needed to identify the failure. Do not snapshot
+complete diagnostic wording unless it 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.
+Golden-file updates must require an explicit local flag. Ordinary validation
+runs must never update golden files automatically, and maintainers must inspect
+the semantic diff before accepting an update.
 
 Keep tests readable and direct. Test helpers and fixture frameworks must earn their own maintenance cost; do not build elaborate test infrastructure for small or isolated needs.
 
@@ -221,7 +258,8 @@ Coverage is a diagnostic, not a target.
 
 Use it to find untested critical branches and unexpectedly weak packages. Do not write low-value tests solely to increase a percentage, and do not infer test quality from coverage alone.
 
-Pure domain logic will often warrant higher coverage than CLI wiring or external adapters. Uneven coverage is acceptable when it reflects risk.
+Pure domain logic will often warrant higher coverage than facade wiring or
+external adapters. Uneven coverage is acceptable when it reflects risk.
 
 Increasing coverage is valuable only when the newly covered behavior protects a meaningful risk at an acceptable cost.
 
@@ -289,7 +327,9 @@ A test suite is sufficient when:
 - legitimate internal changes usually do not require test edits; and
 - additional tests would mostly repeat existing protection or preserve inconsequential implementation details.
 
-Sufficiency is a risk judgment, not a coverage percentage or test count. Reassess it as the application, its users, and the consequences of failure evolve.
+Sufficiency is a risk judgment, not a coverage percentage or test count.
+Reassess it as the library, its consumers, and the consequences of failure
+evolve.
 
 The governing rule is:
 

docs/release.md

@@ -0,0 +1,137 @@
+# Release Procedure
+
+## Release Model
+
+Promptkit publishes a Go library through source commits and semantic Go module
+tags. It does not publish runnable binaries or binary packages and does not
+currently use hosted CI. The release maintainer performs and records the
+required validation.
+
+The first planned release is `v0.1.0`. Do not create that tag until the
+framework has been extracted and the resulting public library has passed this
+procedure. Later tags use the `vMAJOR.MINOR.PATCH` form. While Promptkit remains
+pre-`v1`, release notes must identify intentional public API changes and any
+consumer migration required by them.
+
+## Prepare The Release
+
+Work from a clean checkout of the intended release commit, outside any Go
+workspace and without a local module replacement. Confirm the source commit is
+already published through the normal branch workflow.
+
+From the Promptkit repository root, verify the checkout:
+
+```sh
+test -z "$(go env GOWORK)"
+test -z "$(git status --short)"
+git fetch --tags origin
+```
+
+Confirm the module and root package metadata:
+
+```sh
+go list -m -f '{{.Path}} {{.GoVersion}}'
+go list -f '{{.Name}} {{.ImportPath}}' .
+```
+
+The output must be:
+
+```text
+gitea.maximumdirect.net/eric/promptkit 1.25.5
+promptkit gitea.maximumdirect.net/eric/promptkit
+```
+
+Run the same default Go validation required by the
+[development guide](development.md):
+
+```sh
+go test ./...
+go vet ./...
+go build ./...
+```
+
+Check every tracked Go file and repository whitespace:
+
+```sh
+gofmt -l $(git ls-files '*.go')
+git diff --check
+```
+
+The formatting command must produce no paths. Follow every maintained Markdown
+link and confirm its target exists. Review the repository for generated
+binaries, test or coverage output, credentials, template residue, and other
+files that do not belong in source control.
+
+Confirm that no workspace override is tracked and that `go.mod` contains no
+`replace` directive:
+
+```sh
+git ls-files go.work go.work.sum
+rg -n '^replace\b' go.mod
+```
+
+Both commands must produce no output. Re-run `git status --short` and require a
+clean result after every validation and review check.
+
+## Create And Publish The Tag
+
+Choose the semantic version from the intended compatibility change. Record the
+release commit before tagging:
+
+```sh
+release_version=v0.1.0
+release_commit=$(git rev-parse HEAD)
+```
+
+Replace the example version for later releases and keep both values in the same
+shell for the remaining commands. Confirm the tag does not already exist
+locally or remotely:
+
+```sh
+test -z "$(git tag --list "$release_version")"
+test -z "$(git ls-remote --tags origin "refs/tags/$release_version")"
+```
+
+Create an annotated tag whose message identifies the release and records that
+the documented validation passed for the tagged commit:
+
+```sh
+git tag --annotate "$release_version" \
+  --message "Promptkit $release_version; documented validation passed for $release_commit"
+```
+
+Inspect the tag before publication:
+
+```sh
+git show --no-patch --decorate "$release_version"
+test "$(git rev-list -n 1 "$release_version")" = "$release_commit"
+```
+
+Publish the tag without relying on a hosting-provider-specific release
+interface:
+
+```sh
+git push origin "refs/tags/$release_version"
+```
+
+## Verify Publication
+
+Confirm that the remote tag object matches the local annotated tag and still
+resolves to the intended source commit:
+
+```sh
+remote_tag=$(git ls-remote --tags origin "refs/tags/$release_version" | awk '{print $1}')
+test "$remote_tag" = "$(git rev-parse "refs/tags/$release_version")"
+test "$(git rev-list -n 1 "refs/tags/$release_version")" = "$release_commit"
+```
+
+Promptkit must publish the required tag before Scriptorium or another consumer
+publishes a release that depends on that version. Released consumer modules
+must not use a local replacement or unpublished Promptkit revision.
+
+## Policy Changes
+
+Document and approve a durable policy change before introducing hosted
+automation, binary artifacts, or different release governance. Update this
+procedure in the same change so maintainers do not rely on hidden release
+requirements.

go.mod

@@ -0,0 +1,3 @@
+module gitea.maximumdirect.net/eric/promptkit
+
+go 1.25.5