Document Scriptorium as a Promptkit application

docs/policy/architecture.md

@@ -1,83 +1,102 @@
 # Architecture
 
-This document is the development architecture policy for Scriptorium.
-
-It is for developers and LLM coding agents. User-facing behavior belongs in `README.md` and the docs under `docs/` that target operators/users.
+This document defines Scriptorium's current application architecture and
+durable development boundaries.
 
 ## System Shape
 
-Scriptorium is a narrow prompt-execution application with three executable
-entry paths: CLI `run`, CLI `render`, and the HTTP service started by `serve`.
-It also provides a public Go package for in-process use. Executable adapters
-consume framework behavior through that public facade; the facade continues to
-compose the framework implementation inside this single repository. Its current
-component inventory is maintained in the [internal overview](../internal/overview.md).
+Scriptorium is an executable application with three entry paths: CLI `run`, CLI
+`render`, and the HTTP service started by `serve`. It does not expose a reusable
+root Go package.
 
-Domain behavior is centralized in `internal/usecase` and `internal/domain`.
+The application consumes
+[Promptkit v0.1.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md)
+through its supported root package. Promptkit owns prompt execution,
+preparation, source formats, built-in profiles, model-client behavior, and
+validation. Scriptorium owns application configuration, executable adapters,
+prepared-run presentation, process behavior, and HTTP deployment policy.
 
-## Core Principles
-
-- Keep orchestration narrow: Scriptorium executes one prompt request; it is not a multi-step workflow engine.
-- Keep adapter logic thin: adapters map external shapes to public engine
-  requests/results and should not hold framework decisions.
-- Keep boundaries explicit: repositories/loaders/renderers/validators/LLM client stay behind package interfaces.
-- Keep external decoding strict: configuration, prompt, and profile YAML and
-  HTTP JSON should reject unknown fields.
-- Keep secrets out of payloads: raw API key values must not be accepted or emitted.
+The concrete package inventory is maintained in the
+[internal overview](../internal/overview.md).
 
 ## Dependency Direction
 
-- Adapters translate external shapes and IO concerns; they do not make
-  use-case decisions.
-- Executable adapters and prepared-run formatting use the public facade for
-  framework behavior rather than importing framework implementation packages
-  directly.
-- Use-case and domain code depend on explicit repository, renderer, validator,
-  and LLM interfaces rather than adapter implementations.
-- Source, rendering, validation, and LLM implementations remain behind their
-  package boundaries.
-- Dependency-specific types must not leak across unrelated package boundaries.
-- Prefer the standard library; add an external dependency only when it
-  materially reduces risk or complexity.
+```text
+cmd/scriptorium
+        |
+        v
+CLI and HTTP adapters, configuration, defaults, and formatting
+        |
+        v
+gitea.maximumdirect.net/eric/promptkit
+```
 
-## State And Persistence Policy
+- Retained application packages may import Promptkit's root package.
+- They must not import Promptkit `internal` packages.
+- They must not import the removed Scriptorium root facade or recreate former
+  framework package families.
+- Adapter-owned interfaces use Promptkit public values when a consumer-side
+  substitution boundary is needed.
+- Scriptorium passes omitted framework settings as zero values so Promptkit
+  applies its own defaults.
 
-Scriptorium has no durable run-state store.
+The repository architecture guard enforces these import and removal
+invariants.
 
-- No built-in resume/checkpoint/archive behavior.
-- Recovery model is rerun after correcting inputs/config/environment.
+## Retained Boundaries
 
-## Contract Ownership
+- `internal/adapter/cli` owns commands, flags, configuration precedence,
+  process streams, output files, summaries, and exit codes.
+- `internal/adapter/http` owns routes, strict JSON DTOs, size limits, response
+  mapping, status mapping, and the restricted artifact reader.
+- `internal/config` owns discovery and strict decoding of Scriptorium
+  application configuration.
+- `internal/defaults` owns Scriptorium application and HTTP defaults only.
+- `internal/format` owns deterministic prepared-run text and JSON presentation.
+- Promptkit owns framework orchestration and contracts. Its
+  [format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/formats.md)
+  and
+  [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/integrations/openai-compatible-chat.md)
+  are canonical.
 
-The [CLI](../cli.md), [configuration](../config.md), [HTTP API](../api.md),
-[public Go package](../consumers/pkg-scriptorium.md), and
-[integration](../integrations/) documents own their respective external
-contracts. This policy keeps only the architectural boundaries that govern
-their implementation.
+## HTTP Artifact Security Boundary
 
-## Error Handling And Logging
+Ordinary CLI file loading is provided by Promptkit. Scriptorium's HTTP adapter
+injects a restricted `promptkit.ArtifactReader` for inbound HTTP requests.
+That reader denies file references without an artifact root, enforces the
+configured byte limit, and applies Scriptorium's lexical root-containment rule.
+The operating system still follows symlinks after the lexical check.
 
-- Wrap errors with domain/operation context.
-- Map public error identities to adapter-appropriate statuses/codes without
-  leaking sensitive internals.
-- Never emit raw secret values.
+The [HTTP API](../api.md) owns observable request outcomes, and
+[operations](../operations.md) owns deployment permissions and root selection.
 
-## Testing And Documentation
+## State, Errors, And Secrets
 
-Testing philosophy and change-validation expectations are defined by the
-[testing policy](testing.md). Documentation ownership and maintenance rules are
-defined by the [documentation policy](documentation.md).
+Scriptorium has no durable run-state store, checkpoint, cache, or resume
+mechanism. Recovery is a new request after correcting inputs, configuration, or
+environment.
+
+Adapters map Promptkit public error identities into CLI exits or HTTP statuses
+without classifying by message text. Raw API keys are not accepted in
+Scriptorium configuration, CLI arguments, or HTTP payloads, and resolved
+secrets must not be emitted.
 
 ## Architectural Invariants
 
-- `Runner.Run` reuses `Runner.Prepare` flow.
-- Raw API key values must not be accepted through external configuration or
-  request payloads, and resolved secret values must not be emitted.
+- External YAML and JSON decoding remains strict.
+- CLI and HTTP behavior remains presentation and transport logic rather than
+  framework orchestration.
+- Explicit numeric request overrides preserve presence, including zero.
+- HTTP artifact containment and byte limits remain Scriptorium policy.
+- No application package depends on Promptkit implementation packages.
 
 ## Non-Goals
 
-- Do not move orchestration responsibilities from external callers into Scriptorium.
-- Do not add adapter-specific business logic in `internal/adapter/*` packages.
-- Do not bypass repository/renderer/validator/LLM boundaries by introducing cross-package coupling.
+- Do not recreate an in-process Scriptorium framework API or compatibility
+  facade.
+- Do not copy Promptkit types, defaults, built-in profiles, or implementation
+  into Scriptorium.
+- Do not move CLI, inbound HTTP, process, or deployment policy into Promptkit.
+- Do not add durable workflow, archive, or resume behavior.
 
 Work that is not implemented belongs in `docs/roadmap/`.

docs/policy/documentation.md

@@ -69,11 +69,11 @@ secret values.
 | 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` | 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. |
+| 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. |
 | 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/` | Task-oriented use of the public interface, minimal client examples, and consumer responsibilities. | HTTP wire semantics, external protocol contracts, internal implementation detail. |
-| 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. |
+| 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. |

docs/policy/testing.md

@@ -77,7 +77,7 @@ Test through the narrowest stable boundary that expresses the behavior clearly.
 
 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 smaller pure function when dense application 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.
 
@@ -162,13 +162,16 @@ Use a test-controlled limit and measure the behavior relative to that limit. Do
 
 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.
-- Orchestrator tests own coordination and failure propagation.
-- CLI tests own argument and configuration mapping.
-- End-to-end tests prove that representative assembled workflows work.
+- Configuration tests own application YAML, discovery, precedence, and
+  application defaults.
+- CLI tests own argument mapping, streams, summaries, exit behavior, and
+  representative command workflows.
+- HTTP tests own DTOs, strict decoding, limits, status mapping, and restricted
+  artifact policy.
+- Formatter tests own prepared-run text and JSON presentation.
+- Architecture tests own dependency direction and removal invariants.
+- Promptkit owns framework parsing, orchestration, validation, profiles, and
+  model-client behavior.
 
 Higher-level tests should not repeat every lower-level case. A single intentional policy change should not require unrelated edits across many test files.
 
@@ -221,7 +224,9 @@ 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.
+Security-sensitive HTTP containment and external mappings may warrant denser
+coverage than straightforward process wiring. 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.