diff --git a/docs/api.md b/docs/api.md index 60b2c93..a79b1a4 100644 --- a/docs/api.md +++ b/docs/api.md @@ -68,11 +68,11 @@ The optional `model` object accepts `endpoint`, `model`, `temperature`, `max_tokens`, `top_p`, `timeout_seconds`, `service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and framework credential semantics are defined by the -[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md). +[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md). Explicit zero values for the numeric fields are overrides; zero `timeout_seconds` disables the per-attempt generation deadline only, retaining the request context and configured transport cap. The timeout layers are defined in -the [Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation). +the [Promptkit v0.12.0 outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation). Each built-in transient retry gets a fresh generation timeout; the caller's request context remains the outer cancellation boundary. diff --git a/docs/consumers/api.md b/docs/consumers/api.md index 62788ab..5a251ae 100644 --- a/docs/consumers/api.md +++ b/docs/consumers/api.md @@ -14,7 +14,7 @@ and the HTTP service according to the boundary your application needs. Go applications that need an in-process prompt framework should import Promptkit directly. The tagged -[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) +[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md) owns that interface; Scriptorium does not provide a Go library package. Consumers arriving from the former Scriptorium Go API should follow the [migration guide](migrating-to-promptkit.md). @@ -35,4 +35,4 @@ Scriptorium does not persist run state. A retry can produce different output and can incur another provider request. CLI exits belong to the [CLI reference](../cli.md), HTTP status behavior belongs to the [HTTP API reference](../api.md), and framework semantics belong to -[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md). +[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md). diff --git a/docs/development.md b/docs/development.md index 7c997a5..312d75a 100644 --- a/docs/development.md +++ b/docs/development.md @@ -2,9 +2,11 @@ This is the contributor entry point for Scriptorium. Scriptorium is an application that consumes the public -[Promptkit v0.11.2 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md); +[Promptkit v0.12.0 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md); framework implementation work belongs in Promptkit. Application configuration uses ConfigKit v0.5.0; keep Scriptorium's schema and source selection local. +Promptkit also uses ConfigKit to load framework sources under Promptkit's own +schema and format contract. ## Initial Orientation @@ -45,13 +47,14 @@ Before recommending, planning, or implementing work: | HTTP routes, DTOs, limits, status mapping, or artifact policy | [HTTP API contract](api.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) | | Application configuration or precedence | [Configuration contract](config.md), [adapter internals](internal/adapters.md), [source internals](internal/sources.md), and `internal/config` definition/load tests | | Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and `internal/format` | -| Prompt, profile, schema, generation, or validation semantics | [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) | -| OpenAI-compatible outbound behavior or timeout layering | [Promptkit integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md) | +| Promptkit source selection or captured framework inspection | [Configuration contract](config.md#promptkit-source-selectors), [framework configuration CLI contract](cli.md#framework-configuration-inspection), and [source internals](internal/sources.md) | +| Prompt, profile, schema, generation, or validation semantics | [Promptkit v0.12.0 framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md) | +| OpenAI-compatible outbound behavior or timeout layering | [Promptkit v0.12.0 integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md) | | Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) | | Runtime operation or recovery | [Operations](operations.md) | | Dependencies, copied assets, or attribution | The [OSS policy](policy/oss.md), [component attributions](oss/attribution.md), and [architecture policy](policy/architecture.md) | | Release documentation, packaging, or publication | The [release policy](policy/release.md), [OSS policy](policy/oss.md), [release procedure](release.md), [hosted release workflow](../.woodpecker/release.yml), and [architecture policy](policy/architecture.md) | -| Examples or copyable assets | The owning Scriptorium contract, the relevant [Promptkit format contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md), and the related files under `examples/` | +| Examples or copyable assets | The owning Scriptorium contract, the relevant [Promptkit v0.12.0 format contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md), and the related files under `examples/` | | Architecture decisions or future work | The [documentation policy](policy/documentation.md), relevant accepted ADRs, and relevant roadmap documents | Cross-project changes land and release in Promptkit before Scriptorium adopts diff --git a/docs/internal/adapters.md b/docs/internal/adapters.md index bda2ab3..910a6ee 100644 --- a/docs/internal/adapters.md +++ b/docs/internal/adapters.md @@ -9,7 +9,7 @@ own IO and presentation mechanics, not framework decisions. External contracts are canonical in the [CLI reference](../cli.md) and [HTTP API reference](../api.md). Promptkit's public engine contract is described by its tagged -[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md). +[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md). ## Components And Collaborators @@ -17,11 +17,13 @@ described by its tagged `internal/adapter/cli`. - `internal/adapter/cli` resolves settings through `internal/config`, constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`, - and owns output files, summaries, and exit codes. + exposes application and captured framework configuration inspection, and + owns output files, summaries, and exit codes. - `internal/config` delegates application YAML decoding, default resolution, overrides, and validation ordering to ConfigKit. The CLI supplies only explicitly visited application flags as overrides and renders safe structured - load diagnostics on stderr. + load diagnostics on stderr. Promptkit uses ConfigKit to load framework + sources under its own definition and format contract. - `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit public values, calls its adapter-owned `Runner` interface, and maps results and errors to HTTP DTOs. @@ -53,6 +55,15 @@ preparation or generation. formats a safe application-owned effective profile view. It intentionally does not require prompt, schema, or artifact sources. +`inspect configuration` builds the same engine from the selected native +Promptkit source sequence, reads its captured configuration view, and delegates +effective output and explanation to Promptkit's native writers. The adapter +projects captured source records into its small JSON DTO. Its validation +operation constructs the engine without preparing a request. Framework source +semantics and report redaction are owned by Promptkit; the [CLI +contract](../cli.md#framework-configuration-inspection) documents the exposed +operations and their deliberately limited redaction scope. + The `config` family loads the same application ConfigKit result once and uses its validation, effective-output, source, and explanation views directly. It does not construct a Promptkit engine. The CLI maps source records into a small @@ -62,11 +73,14 @@ JSON DTO for `sources`; `show` and `explain` use ConfigKit's own writers. with `promptkit.WithArtifactReader`, passes the engine through the HTTP adapter's consumer-owned `Runner` interface, and starts the server. -The command paths assemble the engine from the same resolved prompt, profile, -and schema directories plus configured custom backends. Each backend is mapped -to Promptkit's public `Backend` value and registered during engine construction, -so one constructed server engine retains one immutable backend registry and its -associated capacity state. +The command paths assemble the engine from application-selected framework +source files and directories plus the schema directory and retry setting. +Individual files become import-enabled ConfigKit inputs; directory selections +are expanded through Promptkit's directory-input helper. Scriptorium supplies +those ordered underlays through Promptkit's public configuration API rather +than parsing or mapping framework definitions itself. The server constructs +one engine, which retains the framework's backend registry and associated +capacity state across requests. ### HTTP diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 35acbea..fd6826c 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -7,13 +7,13 @@ public behavior belongs in the linked contracts. | Component | Implemented responsibility | References | | --- | --- | --- | | `cmd/scriptorium` | Process entrypoint that delegates arguments and streams to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) | -| `internal/adapter/cli` | Parses execution and application-configuration inspection commands, resolves settings, constructs Promptkit engines only for execution/definition inspection, maps requests, and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md) | +| `internal/adapter/cli` | Parses execution, application-configuration, and captured framework-configuration inspection commands; resolves settings; constructs Promptkit engines for execution, definition inspection, and framework inspection; maps requests; and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md), [source internals](sources.md) | | `internal/adapter/http` | Owns routes, DTOs, strict decoding, limits, Promptkit request/result mapping, public error mapping, and restricted HTTP artifact reading. | [HTTP API](../api.md), [adapter internals](adapters.md), [source internals](sources.md) | -| `internal/config` | Selects application sources, supplies the ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md) | +| `internal/config` | Selects application sources, supplies the application ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md), [source internals](sources.md) | | `internal/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../config.md) | -| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output. | [CLI contract](../cli.md), [adapter internals](adapters.md) | +| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output; framework-configuration output uses Promptkit's native captured view and writers. | [CLI contract](../cli.md), [adapter internals](adapters.md) | | `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) | Framework implementation packages are provided by -[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) +[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md) and are not part of this repository. diff --git a/docs/internal/sources.md b/docs/internal/sources.md index a8a87e4..ca291f1 100644 --- a/docs/internal/sources.md +++ b/docs/internal/sources.md @@ -5,20 +5,24 @@ This document covers Scriptorium-owned source locations and the restricted HTTP artifact reader. Prompt, profile, schema, and ordinary artifact semantics are owned by the tagged -[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md). +[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md). ## Application Source Locations -`internal/config` resolves `prompt_dir`, `profile_dir`, and `schema_dir` from -Scriptorium defaults, configuration files, and CLI overrides. It also resolves -the application-owned `backends` mapping into sorted engine settings. -`internal/adapter/cli` passes the directories into `promptkit.Config` and maps -each configured backend to Promptkit's public engine registration when -constructing an engine shared by the command path. +`internal/config` resolves the ordered `promptkit_sources` sequence and +`schema_dir` from application configuration and explicit CLI overrides. It +owns selector-shape validation, not framework file parsing. During engine +construction, `internal/adapter/cli` turns file selections into import-enabled +ConfigKit inputs and expands directory selections with +`promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit +configuration underlays. The shared Promptkit engine receives the selected +schema directory and retry setting as well. -Scriptorium does not search, parse, validate, or overlay framework source files -itself. Promptkit owns prompt selection, profile built-ins and overlays, schema -resolution, ordinary file artifacts, and the related error identities. +Promptkit uses ConfigKit to load and compose those framework inputs according +to Promptkit's own schema and format. Scriptorium does not parse or validate +Promptkit definitions. Promptkit owns definition selection and validation, +profile built-ins and overlays, schema resolution, ordinary file artifacts, +captured framework configuration inspection, and related error identities. The [configuration reference](../config.md) owns Scriptorium's source-location fields and precedence. Maintained files under `examples/` are application @@ -26,13 +30,15 @@ inputs that use Promptkit's tagged formats. ## Application Configuration Boundary -`internal/config` contains a ConfigKit-native `Document` definition. Its -fresh defaults come from Scriptorium's existing default constants; its resolver -records only actual trimming, path cleaning, and render-format normalization. -The validator reports application retry, size-limit, and format errors without -mutating the document or exposing rejected values. Application path values keep -working-directory-relative meaning. ConfigKit owns strict YAML decoding and -presence semantics, including dynamic integer values in backend parameters. +`internal/config` contains the application-owned ConfigKit-native `Document` +definition. Its fresh defaults come from Scriptorium's existing default +constants; its resolver records only actual trimming, path cleaning, and +render-format normalization. The validator reports selector-shape, retry, +size-limit, and format errors without mutating the document or exposing +rejected values. Application path values keep working-directory-relative +meaning. ConfigKit owns strict application YAML decoding and presence +semantics. Framework configuration is separately loaded by Promptkit through +ConfigKit under Promptkit's own schema and source contract. The `Load` boundary selects an explicit file, the first existing implicit configuration file, or ConfigKit's defaults-only source. Only absence advances @@ -45,11 +51,10 @@ select one named overlay when requested. ConfigKit uses the selected file's canonical directory as the source root; the application does not widen it. Application path values retain process-working-directory-relative meaning. -ConfigKit resolves effective sibling inheritance after source assembly and -overrides, before typed decoding. Runtime conversion and Promptkit registration -consume those resolved values through the existing `Settings` path. The -[configuration reference](../config.md#application-mapping-inheritance) owns -the application-visible inheritance behavior. +Runtime conversion consumes the resolved application values through the +existing `Settings` path. Promptkit receives selected framework sources only +after application configuration has loaded and validated; its source merge, +definition validation, and captured inspection view remain framework-owned. Every configuration-loading command uses this boundary. The CLI maps only explicitly visited application flags to ConfigKit overrides and prints @@ -57,8 +62,11 @@ structured load diagnostics before engine construction. The old application YAML decoder and merge path have been removed. Application `config` inspection reuses the result's frozen effective, provenance, and history views without constructing an engine or reloading -sources. It does not resolve API-key environment values; ordinary backend -parameters remain visible by the selected inspection policy. +sources. It does not resolve credentials. `inspect configuration` separately +constructs an engine and exposes Promptkit's captured framework view; only its +framework `show` and `explain` reports receive Promptkit's native, +credential-shaped redaction. Neither inspection family is a general-purpose +filter for arbitrary sensitive values. ## Restricted HTTP Artifact Reader diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 89f6e31..cd14d4f 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-10-03 +**Last Updated**: 2026-10-04 **Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md @@ -50,23 +50,32 @@ inventory; [adapter internals](../internal/adapters.md) and ## Framework And Application Boundaries Scriptorium consumes -[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) +[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md) through its supported public root package. Promptkit owns prompt execution, preparation, prompt and profile formats, built-in profiles, model-client behavior, validation, and framework defaults. Scriptorium owns application configuration, executable CLI and HTTP adapters, prepared-run and -definition-inspection presentation, process behavior, and HTTP deployment -policy. The [format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) -and [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md) +definition-inspection presentation, captured-configuration inspection +exposure, process behavior, and HTTP deployment policy. The [format +reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) +and [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md) remain Promptkit's contracts. Scriptorium uses ConfigKit v0.5.0 for strict application YAML decoding, resolution, and validation flow. Scriptorium retains its application schema, defaults, normalization, validation rules, source selection, and CLI override -mapping. ConfigKit also resolves sibling inheritance in application input -mappings. ConfigKit does not own Promptkit framework sources or HTTP artifact +mapping. Promptkit also uses ConfigKit to decode and assemble framework +sources under Promptkit's own schema and format contract; Scriptorium selects +the inputs but does not parse Promptkit definitions. ConfigKit is the shared +loading mechanism, not the owner of either domain schema or HTTP artifact containment. The [configuration contract](../config.md) owns externally -observable configuration behavior. +observable application behavior, while Promptkit owns framework formats. + +The CLI exposes Promptkit's captured framework configuration inspection. Its +`show` and `explain` reports use Promptkit's native redaction for classified +credential-shaped fields, including historical values. This scoped behavior is +not a general-purpose filter for arbitrary sensitive content and does not +extend to application configuration or existing prompt/profile inspection. Application code may import Promptkit's public root package, but not its `internal` packages or catalog modules. It must not recreate the removed diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index e18bead..2cef5a4 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -3,8 +3,8 @@ ## Status, Baseline, And Authority Planned on 2026-10-04 against Scriptorium -`82b0f231b6ba71328f65f9a501143b2eedbe5d9c`. Stages 1–11 are complete; stages -12–13 are pending. +`82b0f231b6ba71328f65f9a501143b2eedbe5d9c`. Stages 1–12 are complete; stage +13 is pending. This plan is for a Luna coding agent: implement the stages in sequential order, normally one stage per implementation prompt. The [feature roadmap](promptkit.md) owns the target state, scope, and confirmed @@ -670,7 +670,22 @@ framework inspection for application validation or expecting automatic reload. ## Stage 12: Align Developer, Internal, And Architecture Documentation -Status: Pending. Depends on Stage 11. +Status: Complete. Current Promptkit references in the developer guide, internal +component/source/adapter docs, architecture policy, and affected HTTP API and +consumer guidance now target v0.12.0; historical migration and roadmap records +remain pinned to the versions they describe. The developer reading guide now +routes native source selection and captured framework inspection to their +owners without changing its selective policy-reading guidance. Internal docs +describe the application selector sequence, ConfigKit's separate application +and framework schema owners, shared CLI engine assembly, Promptkit-native +configuration reports, and existing server capacity ownership; stale backend +registration, old directory, and application-inheritance claims were removed. +Architecture ownership and the approved show/explain-only native redaction +scope were aligned, with Base Policy Version, Upstream Source, ADR decisions, +shared engine capacity, request independence, and HTTP lexical artifact +containment unchanged. The full-config application validator and all four +framework configuration inspection operations ran offline; the HTTP wire +contract was unchanged and `git diff --check` passes. Files: `docs/development.md`, `docs/internal/overview.md`, `adapters.md`, `sources.md`, `docs/policy/architecture.md`, and affected current consumer/API