scriptorium/docs/roadmap/documentation.md

# Documentation Compliance Roadmap

## Status

Completed on 2026-07-26. This document records the findings of the
documentation audit performed after adoption of the canonical-ownership policy
and the completed refresh that addressed them.

## Objective

Bring the current Scriptorium documentation into compliance with
`docs/policy/documentation.md` before beginning the Promptkit migration.

The refresh should:

- give every topic one canonical owner;
- remove parallel definitions of volatile contracts;
- correct current factual discrepancies;
- preserve useful contributor and operational guidance in the appropriate
  documents;
- establish the missing internal overview and ADR history;
- leave Promptkit and other future behavior in roadmap and ADR documents until
  implemented.

This roadmap covers documentation organization and current-behavior accuracy.
A substantive review of `docs/policy/testing.md` remains separate.

## Audit Baseline

The audit covered:

- `README.md`;
- all Markdown files under `docs/`;
- all maintained files under `examples/`;
- the CLI parser and output behavior;
- app-config shapes and defaults;
- HTTP DTOs, limits, and error mappings;
- the public Go facade;
- prompt, profile, schema, artifact, renderer, runner, and LLM behavior;
- the embedded built-in profile assets.

At the time of the audit:

- all local Markdown link targets existed;
- `go test ./...` passed;
- the README/CLI render command completed successfully;
- `examples/render-markdown-summary.sh` completed successfully;
- `go run ./examples/go-library/prepare` completed successfully.

The dominant problem is duplicated ownership rather than broad factual
staleness. CLI, configuration, HTTP, validation, state, and security behavior
are repeated across contracts, operations, troubleshooting, integrations,
consumer guides, architecture, and internal documents.

## Required Accuracy Corrections

Make these corrections while revising the owning documents:

1. `docs/policy/architecture.md` says Scriptorium has three entry paths but
   lists four. Distinguish the three executable entry paths from the public Go
   package, or describe four total entry paths.
2. The built-in profile catalog in `docs/config.md` omits
   `deepseek-4-flash`. Reconcile the complete catalog with
   `internal/profile/builtin/assets/`.
3. `docs/config.md` marks prompt `output.repair_attempts` as required. The
   loader permits omission and resolves it to zero; document it as optional
   with an effective default of zero.
4. `docs/consumers/pkg-scriptorium.md` says every input map key must match a
   declared prompt input. The renderer enforces required declared inputs and
   resolves names actually referenced by templates, but it does not reject
   every undeclared extra input. Describe the implemented boundary.
5. `docs/troubleshooting.md` says validation errors can be inspected in CLI
   stderr. The CLI success summary reports the number of validation errors, not
   their detailed messages. Correct the diagnostic guidance or separately
   change the product before documenting richer output.
6. `docs/integrations/openai-compatible-chat.md` describes the `session_id`
   limit as characters. The implementation counts Unicode code points; use the
   canonical terminology consistently.
7. The same integration document makes a time-sensitive statement about
   provider-supported service-tier values even though Scriptorium accepts and
   forwards any non-empty value. Remove the provider catalog claim or cite and
   version an intentionally maintained external contract.
8. The `render` and `serve` flag sections in `docs/cli.md` list
   `--prompt-dir` both as an effective requirement and again as an optional
   flag. Keep one complete flag entry and separately explain how the
   requirement may be satisfied.
9. Troubleshooting command examples containing placeholders such as
   `<prompt-id>` are not directly copyable shell commands. Use clearly defined
   shell variables, concrete maintained examples, or prose diagnostic steps.

## Canonical Structure Changes

### Create `docs/internal/overview.md`

Create the canonical implemented-component inventory and move the concrete
package map out of architecture.

The overview should:

- list current public, command, adapter, domain, use-case, source, format,
  validation, and LLM components;
- give each component a short implemented responsibility;
- link to focused internal documents and relevant external contracts;
- avoid restating global architecture rules or user-facing behavior.

Update `docs/development.md` to route general repository-orientation work
through the overview once it exists.

### Establish `docs/adr/`

Create the ADR directory under the policy already defined in
`docs/policy/documentation.md`.

Record the significant accepted documentation-ownership decision in an initial
ADR if historical rationale is useful. The Promptkit split ADR remains part of
Step 2 in `docs/roadmap/migration.md` and should not be pulled ahead of its
gate merely to populate the directory.

ADRs must own decision context, alternatives, rationale, and consequences.
Roadmaps must continue to own implementation status and sequencing.

### Consolidate Troubleshooting Into Operations

The ownership table assigns recovery to `docs/operations.md` and does not give
troubleshooting a separate canonical owner. Fold the useful
symptom/diagnosis/safe-recovery material from `docs/troubleshooting.md` into a
concise operations section, then remove `docs/troubleshooting.md`.

The consolidated material should:

- organize failures by operational task rather than duplicate every contract
  field and status;
- link exact CLI syntax and exit codes to `docs/cli.md`;
- link config fields and defaults to `docs/config.md`;
- link HTTP codes and schemas to `docs/api.md`;
- describe only diagnostic and recovery actions locally.

Update README, development, integration, and other links after the removal.

## File-By-File Revision Catalog

### `README.md`

- Retain the product description and one tested end-to-end quickstart.
- Keep the quickstart linked to the complete CLI contract.
- Replace the repeated example inventory with a short link to the maintained
  examples section in the appropriate canonical contract, or make each retained
  path a direct link.
- Keep the documentation list navigational; do not summarize contracts there.
- Remove the troubleshooting link if troubleshooting is consolidated into
  operations.

### `docs/development.md`

- Retain only contributor orientation, task-specific routing, and baseline
  validation.
- Add `docs/internal/overview.md` to the appropriate reading paths once it
  exists.
- Update the operations/troubleshooting row after consolidation.
- Link to actual ADRs when created; do not duplicate their decisions.
- Confirm that all detailed recipes removed from the former development guide
  have an internal owner before declaring the refresh complete.

### `docs/policy/architecture.md`

- Fix the entry-path count.
- Replace the concrete package inventory with a link to
  `docs/internal/overview.md`.
- Remove config precedence, field-level behavior, exact routes, and exact
  import-path contracts except for the smallest orientation summary and links
  to their owners.
- Remove the local testing checklist and link to
  `docs/policy/testing.md`. Component-specific test inventories remain in
  internal docs.
- Remove the local documentation checklist and link to
  `docs/policy/documentation.md`.
- Keep normative system shape, ownership, dependency direction, state
  philosophy, security properties, error-handling principles, invariants, and
  non-goals.
- Review the coding and dependency rules removed from the former development
  guide. Preserve still-valid normative rules here without listing the current
  dependency inventory, which is concrete implementation information.
- Move implementation facts such as current repairer wiring to the relevant
  internal component document unless they are intentionally elevated to
  architecture invariants.

### `docs/policy/documentation.md`

- No structural rewrite is currently required.
- Recheck its ownership table after the troubleshooting consolidation and ADR
  creation.
- Keep future policy refinements in this document rather than distributing
  documentation rules across architecture or development.

### `docs/policy/testing.md`

- It is the sole owner of global testing philosophy and sufficiency rules.
- Remove competing global testing guidance from architecture and other docs.
- Leave the planned substantive testing-policy review for its separate work
  cycle.

### `docs/cli.md`

- Keep the complete command, argument, flag, output, and exit-code contract.
- Remove the repeated definition of config precedence and link to
  `docs/config.md`.
- Move profile source and override semantics that are not CLI invocation
  semantics to `docs/config.md`.
- Resolve duplicate `--prompt-dir` entries in the `render` and `serve`
  sections.
- Verify every registered flag, deprecated alias, requirement, zero-value
  behavior, and output destination against `internal/adapter/cli/run.go`.
- Clarify timeout conversion for subsecond Go durations if that behavior is
  intended to remain public.
- Keep only compact workflow examples and link to maintained scripts under
  `examples/`.

### `docs/config.md`

- Keep app-config discovery, precedence, fields, defaults, validation,
  credential-supply mechanisms, prompt/profile formats, and selectable profile
  catalog as the canonical contract.
- Replace complete inline config, prompt, and profile files with the smallest
  useful snippets and links to copyable files under `examples/`.
- If a production-oriented complete config remains useful, move it into
  `examples/` and link it rather than maintaining a second complete copy.
- Correct `repair_attempts` optionality.
- Add `deepseek-4-flash` and reconcile every built-in profile ID, model, and
  credential-variable name with embedded assets.
- Establish a low-friction way to prevent catalog drift, such as a generated
  catalog section or a focused consistency check, if its maintenance value
  justifies the cost.
- Keep schema configuration and prompt/profile file-format rules here; move
  implementation mechanics to internal source docs.
- Reduce the HTTP artifact-reference section to configuration meaning and link
  request shapes/statuses to `docs/api.md` and runtime security handling to
  `docs/operations.md`.
- Keep the secret-supply mechanism here; move deployment permissions and
  sensitive-runtime handling to operations.

### `docs/api.md`

- Keep routes, media types, request/response schemas, strict JSON behavior,
  status codes, HTTP retry semantics, and HTTP artifact-access outcomes.
- Replace repeated app-config defaults and CLI flag syntax with links to
  `docs/config.md` and `docs/cli.md`.
- Retain HTTP limit effects but let configuration own field defaults and
  precedence.
- Keep the lexical containment and symlink behavior as externally observable
  API/security behavior; operations may summarize its deployment consequence
  and link back.
- Reduce request and response examples to compact contract-bearing shapes and
  link to `examples/http-run.json`.
- Reverify all DTO fields, omission behavior, limit responses, and error mappings
  against `internal/adapter/http/`.

### `docs/operations.md`

- Rewrite as a task-oriented runbook rather than a secondary CLI, config, and
  API reference.
- Keep deployment layout, process permissions, sensitive runtime artifact
  handling, normal workflow, service exposure, capacity planning, recovery,
  and the stateless rerun model.
- Link exact commands and exit codes to `docs/cli.md`.
- Link config fields, defaults, validation modes, and credential-supply
  mechanics to `docs/config.md`.
- Link HTTP route, status, schema, and limit semantics to `docs/api.md`.
- Remove the repeated maintained-example inventory and link to the owning
  examples section.
- Incorporate the useful troubleshooting material and then delete
  `docs/troubleshooting.md`.

### `docs/troubleshooting.md`

- Correct the CLI validation-error diagnostic during migration.
- Move useful symptom, diagnostic, and safe-fix material into
  `docs/operations.md`.
- Remove repeated definitions of flags, fields, defaults, HTTP codes, routes,
  and validation semantics; link to their canonical contracts.
- Delete this file after all useful recovery guidance and inbound links have
  been handled.

### `docs/consumers/api.md`

- Keep integration-surface selection, minimal consumer workflow, and consumer
  responsibilities.
- Retain one minimal Go example as permitted instructional content and link to
  the complete package contract and maintained example.
- Replace repeated CLI exit and HTTP status definitions with links to their
  canonical contracts.
- Replace repeated deployment input and credential definitions with links to
  configuration and operations.
- Keep retry and artifact-retention decisions as consumer responsibilities
  without restating wire semantics.

### `docs/consumers/pkg-scriptorium.md`

- Keep the import path, public constructors, options, types, errors, workflows,
  and public security boundary as the canonical Go package contract.
- Correct the input-name validation statement.
- Reverify public fields, JSON behavior, option precedence, nil behavior,
  source containment, direct-key handling, and sentinel errors against the root
  package.
- Keep a minimal package example and link to
  `examples/go-library/prepare`; avoid duplicating complete maintained source.
- Link prompt/profile/schema file formats to `docs/config.md` rather than
  redefining them.

### `docs/integrations/subprocess.md`

- Narrow this document to subprocess-specific compatibility and process
  integration concerns.
- Link command syntax, flags, stdout/stderr behavior, and exit codes to
  `docs/cli.md` rather than maintaining parallel definitions.
- Link config search and field semantics to `docs/config.md`.
- Retain process isolation, environment propagation, stream capture, output
  ownership, cancellation/termination expectations, and security guidance when
  these are specific to subprocess consumers.
- Move task-oriented surface-selection advice to `docs/consumers/api.md` if it
  is currently duplicated.

### `docs/integrations/openai-compatible-chat.md`

- Keep only the outbound HTTP wire contract: endpoint construction, request
  payload, authentication header, timeouts, response subset, and unsupported
  protocol behavior.
- Remove the concrete implementation-file introduction and internal error
  sentinel catalog.
- Correct the `session_id` unit to Unicode code points.
- Remove or deliberately source/version the provider service-tier claim.
- Reverify reserved `extra_params` keys, structured-output envelope,
  cache-control encoding, usage mapping, and response requirements against
  `internal/llm/openai_compatible_client.go`.
- Link runner schema preparation to internal runner documentation rather than
  explaining orchestration locally.

### `docs/internal/overview.md` (new)

- Own the complete current component and package inventory.
- Link each component to focused internal docs and external contracts.
- Include the command entry point and public facade without redefining their
  external behavior.
- Absorb the still-useful concrete repository-layout material removed from the
  old development guide and architecture policy.

### `docs/internal/adapters.md`

- Keep implementation flow, collaborators, translation boundaries, wiring,
  error-mapping mechanisms, and relevant tests.
- Remove exact flag lists, config field definitions, route schemas, response
  codes, and exit-code definitions; link their canonical owners.
- Keep only package-local invariants rather than repeating global architecture.
- Incorporate the former contributor recipes for adding app-config fields, CLI
  flags, and adapter capabilities.
- Describe how to verify affected adapter contracts without duplicating the
  global testing policy.

### `docs/internal/runner.md`

- Keep prepare/run flow, dependency boundaries, state transitions, failure
  categories, repair mechanics, hashing/validation coordination, and relevant
  tests.
- Remove the app-config field list and link to adapter/config documentation.
- Keep internal sentinel and collaborator information, but link public error
  behavior to the package/API contracts.
- Distinguish package-local guarantees from global architectural invariants.
- Add a focused change recipe for runner orchestration when useful.

### `docs/internal/sources.md`

- Keep loader implementations, source precedence mechanics, containment
  implementation, failure categories, collaborators, and relevant tests.
- Link YAML/JSON field definitions and defaults to `docs/config.md`.
- Link HTTP-visible artifact outcomes to `docs/api.md` and deployment handling
  to operations.
- Incorporate the former recipe for updating prompt, profile, schema, and
  built-in-profile assets.
- Distinguish implementation mechanics from external source contracts.

### `docs/internal/llm.md` (new)

Create a focused internal document if the implementation material removed from
the outbound integration contract remains useful.

It should own:

- client construction and internal collaborator boundaries;
- internal request mapping and timeout selection;
- internal error categories;
- relevant tests and package-local change guidance.

It must link to `docs/integrations/openai-compatible-chat.md` for the wire
contract rather than repeat payload definitions.

### `docs/roadmap/migration.md`

- Retain migration status, gates, sequencing, and task breakdowns.
- Mark the documentation-refresh gate complete only after this roadmap's
  completion criteria are satisfied.
- After the Promptkit split ADR is accepted, replace duplicated decision
  rationale and architectural ownership detail with a concise summary and ADR
  link where practical.
- Update paths and document ownership affected by this refresh.

### `examples/`

- Keep complete copyable artifacts here rather than in reference documents.
- Verify `config.yml` and `config.full.yml` through the real config loader.
- Keep prompt/profile/schema examples covered by representative repository and
  engine tests.
- Keep the render script and Go package example runnable from the repository
  root.
- Validate `http-run.json` structurally against the HTTP DTO contract without
  requiring a live model endpoint.
- Add a separate production-oriented config example only if that maintained
  artifact has clear value; otherwise remove the duplicate production block
  from config documentation.
- Preserve the fixtures as non-sensitive synthetic data.

## Implementation Sequence

### Stage 1: Establish Canonical Developer Structure

1. Create the initial documentation ADR if retained.
2. Create `docs/internal/overview.md`.
3. Rewrite architecture around normative ownership and invariants.
4. Update `docs/development.md` routing.
5. Rescue still-valid development rules and assign every removed recipe.

**Gate:** Contributor orientation, architecture, component inventory, policies,
and decision history have distinct owners and no stale links.

### Stage 2: Correct And Consolidate External Contracts

1. Revise `docs/config.md` and correct its known factual issues.
2. Revise `docs/cli.md`.
3. Revise `docs/api.md`.
4. Revise both consumer guides.
5. Revise both integration contracts.
6. Verify each volatile contract against code and maintained assets.

**Gate:** Each externally observable field, default, flag, route, status, import
path, and wire behavior has one authoritative definition.

### Stage 3: Refocus Internal Documentation

1. Revise adapter, runner, and source docs.
2. Add the internal LLM document if warranted.
3. Incorporate the former subsystem change recipes.
4. Remove global policy and external-contract duplication.

**Gate:** Internal docs explain implementation and package-local guarantees,
link external contracts, and contain the detailed contributor recipes needed
for safe changes.

### Stage 4: Rewrite Operations And Consolidate Recovery Guidance

1. Rewrite operations as a runbook.
2. Migrate useful troubleshooting content.
3. Delete `docs/troubleshooting.md`.
4. Update all inbound links and the development reading guide.

**Gate:** Operations owns deployment and recovery without serving as a second
CLI, config, or API reference.

### Stage 5: Normalize Examples And Orientation

1. Move any remaining complete copyable artifacts into `examples/`.
2. Update README navigation and example links.
3. Run maintained smoke examples.
4. Add only high-value automated checks justified by the testing policy.

**Gate:** Examples are canonical, runnable, secret-free, linked from their
owning references, and not duplicated as complete files in prose docs.

### Stage 6: Final Compliance Pass

1. Validate all local links and paths.
2. Search for duplicated volatile values across non-owning documents.
3. Reconcile flags, config fields/defaults, API DTOs/codes, public types/errors,
   and built-in profiles with implementation.
4. Run `go test ./...`, `go vet ./...`, and the documented build command.
5. Run the maintained render script and Go package example.
6. Confirm that non-roadmap current docs contain implemented behavior only.
7. Record completion in this roadmap and update the documentation gate in
   `docs/roadmap/migration.md`.

**Gate:** Code, tests, examples, contracts, internal documentation, operations,
policies, and roadmap status agree. Completed on 2026-07-26.

## Completion Criteria

The documentation refresh is complete when:

- every topic in the ownership table has one canonical owner;
- `docs/internal/overview.md` exists and architecture no longer owns the package
  inventory;
- significant accepted decisions have an ADR owner;
- all known factual discrepancies in this audit are corrected;
- subsystem recipes from the former development guide have been preserved in
  relevant internal docs;
- operations contains the retained recovery guidance and the standalone
  troubleshooting document is removed;
- contracts and internal docs link to one another instead of maintaining
  parallel volatile definitions;
- maintained examples are runnable and not duplicated as complete prose
  examples;
- local links, validation commands, tests, and smoke checks pass;
- the documentation-refresh gate in the Promptkit migration roadmap is marked
  complete.