scriptorium/docs/policy/documentation.md

# Documentation Policy

**Base Policy Version:** 1.4

**Last Updated:** 2026-09-26

## Purpose

This policy assigns each documentation topic to one canonical owner. Its goal is
to keep this repository's documentation accurate, concise, discoverable, and
resistant to drift for users, operators, developers, integrators, and LLM
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
instead of repeating 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.

Minimal tested usage examples are allowed outside the owning contract when this
policy assigns them an orientation or instructional purpose. They must link to
the canonical contract and must not redefine complete syntax, defaults, or
semantics.

### 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 without implying that the
components or capabilities they would govern already exist. This does not
permit describing a proposed system structure as implemented.

ADRs may record an accepted architectural decision before implementation, but
acceptance must not be presented as proof that the behavior exists. 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. User and operator docs should not expose implementation detail.
Developer docs should link to user-facing and external contracts rather than
restate them.

### 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 instead of embedding a second complete copy.

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 end-to-end quickstart | `README.md` | What this project is, why it is useful, one shortest successful invocation, and links onward, including license and attribution navigation. | Complete command reference, configuration reference, operational procedures, implementation detail. |
| 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, and detailed change recipes, which belong in the relevant internal component document. |
| Application architecture policy | `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. |
| Agent policy | `docs/policy/agents.md` | Agent implementation discipline, proportionality, idiomatic simplicity, local commit rules, and rules against inventing requirements, restrictions, guarantees, or repository policy. | Application contracts, architecture, testing policy, and contributor procedures. |
| Documentation organization | `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-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. |
| 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. |
| Configuration contract | `docs/config.md` | Application discovery and precedence, source locations, server fields, render default, HTTP limits, and credential mapping. | Promptkit framework formats and defaults, complete example files, CLI syntax, runtime lifecycle, and implementation detail. |
| 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. |
| Release policy | `docs/policy/release.md` | Versioning and compatibility, release integrity and immutability, documentation requirements, proportionate gates, publication controls, source completion, and optional verification boundaries. | Repository-specific commands, installation guidance, historical summaries, and CI implementation details. |
| Release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, publication command and guards, asynchronous delivery, optional diagnostics, and failure recovery. | General release requirements, runtime operations, historical announcements, and current application contracts. |
| Version-specific release notes | `docs/releases/` | Immutable release summaries, compatibility notices, and migration announcements for one published version. | Complete CLI, HTTP, configuration, operations, or dependency contracts. |
| Open source licensing and attribution policy | `docs/policy/oss.md` | House attribution format, license-text and notice-link conventions, discoverability, maintenance, and handling of concrete exceptions. | Component entries, license texts, release commands, and dependency security review. |
| Project license | `LICENSE` | The project's own license terms. | Upstream component attribution and dependency license texts. |
| Upstream component attribution | `docs/oss/attribution.md` | Component names, copyright statements, license identification, and license, notice, and source links. | General attribution policy and complete standard license texts. |
| Standard dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by attribution entries where applicable. | Project-specific upstream notices, attribution prose, and policy interpretation. |
| Public HTTP contract | `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. |
| Consumer guidance | `docs/consumers/` | Choosing between Scriptorium's executable interfaces and understanding consumer responsibilities. | HTTP wire semantics, CLI syntax, Promptkit's Go package, and internal implementation detail. |
| External and durable integration contracts | `docs/integrations/` | Scriptorium-owned process and executable integration contracts. | Promptkit framework formats and outbound provider protocols, physical runtime placement, internal transformations, CLI syntax, and configuration defaults. |
| 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. |
| 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. |
| Architectural decision history | `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. |
| 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
or responsibility exists. Do not create placeholder API, consumer, integration,
or operations documents for behavior the application does not have.

## Boundary Rules

### Orientation

The README owns product orientation. The developer guide routes contributors.
Architecture owns normative structure. Internal overview owns the current
concrete component map. These documents may link to one another but should not
maintain parallel package or behavior descriptions.

### Commands, Configuration, And Operations

CLI documentation answers how to invoke the application. Configuration
documentation answers what settings mean. Operations answers what happens to
runtime state and how to operate or recover the application. When a workflow
crosses these topics, choose the document that owns the task and link to the
other contracts.

### Releases

The release policy owns release requirements; the release procedure supplies
the commands that satisfy them. Release notes are historical summaries, not
current-state contract owners. The checked-in note at an immutable tag records
that release; current documentation changes with the behavior it describes.
Neither a procedure nor a note may weaken policy or defer required updates to
canonical contracts.

### Open Source Attribution

The [OSS policy](oss.md) defines the House Format and README and release-link
conventions. Attribution entries own component-specific information. README
and release documents provide navigation to those canonical materials; the
release procedure owns URL construction and publication mechanics.

### Contracts And Implementation

Integration and API documents define externally observable shapes and
semantics. Internal documents explain how this project 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
mechanisms. Operations owns permissions and handling of sensitive runtime
artifacts. 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.

Use one of these statuses:

- **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 ADR replaces the accepted decision.

A proposed ADR transitions to accepted or rejected. An accepted ADR transitions
to superseded only when a later accepted ADR replaces it. An ADR may be created
as accepted when the decision has already been made.

Treat the decision content of an accepted ADR as immutable. Its status and
supersession metadata may be updated, but a changed decision requires a new ADR.
A superseded ADR must link to its replacement, and the replacement must link
back to the superseded ADR. Rejected architectural alternatives belong in the
ADR; rejected product ideas belong in the roadmap.

## Maintenance

Every policy document records its underlying template version and local
last-updated date immediately below the title. Update the date when revising
local policy; change the base version only when adopting a newer template.
Do not retain template adoption instructions in the local policy.

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.