Identify v0.12.0 as the first published application-only release

.gitignore

@@ -56,6 +56,8 @@ mono_crash.*
 [Dd]ebugPublic/
 [Rr]elease/
 [Rr]eleases/
+!docs/releases/
+!docs/releases/*.md
 x64/
 x86/
 [Ww][Ii][Nn]32/
@@ -433,4 +435,3 @@ FodyWeavers.xsd
 
 # JetBrains Rider
 *.sln.iml
-

.woodpecker/release.yml

@@ -11,9 +11,16 @@ steps:
         version="$CI_COMMIT_TAG"
         dist="dist"
         pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium"
+        notes="docs/releases/$version.md"
+
+        if [ ! -f "$notes" ]; then
+          printf 'release notes not found: %s\n' "$notes" >&2
+          exit 1
+        fi
 
         rm -rf "$dist"
         mkdir -p "$dist"
+        cp "$notes" "$dist/RELEASE_NOTES.md"
 
         build_binary() {
           goos="$1"
@@ -22,7 +29,7 @@ steps:
           output="$dist/scriptorium-$version-$goos-$goarch$suffix"
 
           CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \
-            go build -trimpath -ldflags "-s -w -X gitea.maximumdirect.net/eric/scriptorium/internal/buildinfo.Version=$version" \
+            go build -trimpath -ldflags "-s -w" \
             -o "$output" "$pkg"
         }
 
@@ -38,6 +45,7 @@ steps:
         from_secret: GITEA_RELEASE_TOKEN
       files:
         - dist/scriptorium-*
+      note: dist/RELEASE_NOTES.md
       checksum: sha256
       checksum-file: SHA256SUMS
       checksum-flatten: true

README.md

@@ -35,6 +35,7 @@ a model. For complete invocation and output behavior, see the
 - [HTTP API reference](docs/api.md)
 - [Operations guide](docs/operations.md)
 - [Consumer integration overview](docs/consumers/api.md)
+- [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md)
 - [Subprocess integration](docs/integrations/subprocess.md)
 - [Architecture policy](docs/policy/architecture.md)
 - [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/formats.md)

docs/consumers/api.md

@@ -16,6 +16,8 @@ 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.1.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).
 
 ## Consumer Responsibilities
 

docs/consumers/migrating-to-promptkit.md

@@ -0,0 +1,109 @@
+# Migrate From Scriptorium To Promptkit
+
+## Supported Migration Boundary
+
+Scriptorium `v0.11.1` at
+`gitea.maximumdirect.net/eric/scriptorium` is the final release that provides
+the former in-process Go framework. Promptkit `v0.1.0` at
+`gitea.maximumdirect.net/eric/promptkit` is the destination for that framework
+API. Scriptorium `v0.12.0` and later provide the CLI and HTTP application only.
+
+There is no Scriptorium compatibility facade, alias package, forwarding
+package, or deprecated wrapper. A consumer that cannot migrate may remain
+pinned to Scriptorium `v0.11.1`, but that framework-bearing line does not
+provide the slim application release.
+
+## Update A Go Consumer
+
+Start from a clean consumer checkout and review the pending diff before
+committing it. Add the published Promptkit module:
+
+```sh
+go get gitea.maximumdirect.net/eric/promptkit@v0.1.0
+```
+
+For an ordinary consumer that imports the former root package under its
+default name, replace the exact import and package qualifier, then format the
+changed Go files:
+
+```sh
+git grep -l \
+  '"gitea.maximumdirect.net/eric/scriptorium"' \
+  -- '*.go' |
+  while IFS= read -r go_file
+  do
+    perl -pi -e \
+      's{"gitea.maximumdirect.net/eric/scriptorium"}{"gitea.maximumdirect.net/eric/promptkit"}g; s{\bscriptorium\.}{promptkit.}g' \
+      "$go_file"
+    gofmt -w "$go_file"
+  done
+```
+
+Inspect the resulting diff. Consumers that used an import alias should retain
+or deliberately rename that alias instead of applying the qualifier
+replacement mechanically.
+
+Remove the now-unused Scriptorium requirement through module tidiness and run
+the consumer's complete tests:
+
+```sh
+go mod tidy
+go test ./...
+```
+
+Confirm that `go.mod` selects Promptkit `v0.1.0` and that no Go file imports
+the former Scriptorium package:
+
+```sh
+test "$(
+  go list -m -f '{{.Path}}@{{.Version}}' \
+    gitea.maximumdirect.net/eric/promptkit
+)" = 'gitea.maximumdirect.net/eric/promptkit@v0.1.0'
+if git grep -n \
+  'gitea.maximumdirect.net/eric/scriptorium' \
+  -- '*.go'
+then
+  printf '%s\n' 'a former Scriptorium Go import remains' >&2
+  exit 1
+fi
+```
+
+## Compatibility And Additions
+
+Promptkit preserves the established engine, request, result, profile,
+source-option, model-client, artifact, validation-value, and public-error
+shapes where practical. Exact declarations and current behavior belong to the
+tagged [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md)
+and Go source.
+
+Promptkit also includes migration-relevant public contracts that were not in
+Scriptorium `v0.11.1`:
+
+- [`WithArtifactReader`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/engine.go#L96-L105)
+  and the
+  [`ArtifactReader` declaration](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/types.go#L129-L135)
+  provide the artifact-reading extension described by the tagged
+  [extension-interface guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md#extension-interfaces).
+- [`ErrProfileRequired` and `ErrAPIKeyEnvMissing`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/engine.go#L28-L40)
+  provide the specific identities described by the tagged
+  [error guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md#errors).
+
+Use those tagged owners for exact signatures, wrapping guarantees, and
+extension behavior.
+
+## Verify Consumer Behavior
+
+Source compatibility is only the first check. Exercise the behavior the
+consumer actually relies upon, especially:
+
+- prompt, profile, and schema source selection;
+- direct and environment-based credentials;
+- caller, generation, and transport timeout layering;
+- output validation and validation-failure handling;
+- injected model-client and artifact-reader extensions; and
+- every `errors.Is` branch used for recovery or classification.
+
+Also verify any serialized values, redaction expectations, filesystem policy,
+and provider integration behavior that crosses the consumer's own boundary.
+Promptkit owns the in-process framework contract; Scriptorium owns only its
+executable CLI and HTTP application interfaces.

docs/development.md

@@ -31,7 +31,7 @@ tests.
 | OpenAI-compatible outbound behavior or timeout layering | [Promptkit integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.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) |
-| Release packaging | `.woodpecker/release.yml`, [operations](operations.md), and the architecture policy |
+| Release packaging or publication | The [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.1.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 |
 

docs/policy/documentation.md

@@ -71,6 +71,8 @@ secret values.
 | 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 procedure | `docs/release.md` | Candidate validation, version and tag operations, hosted-workflow observation, and published-artifact verification. | Runtime operations, version-specific announcements, and complete application-interface 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. |
 | 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. |

docs/release.md

@@ -0,0 +1,376 @@
+# Release Procedure
+
+## Release Model And Status
+
+Scriptorium publishes annotated semantic tags and tag-triggered Linux binary
+releases. The hosted
+[release workflow](../.woodpecker/release.yml) builds `amd64` and `arm64`
+executables, publishes their SHA-256 checksums, and uses the matching file
+under `docs/releases/` as the hosted release body.
+
+`v0.12.0` is the first published application-only release. For each later
+release, select a new `vMAJOR.MINOR.PATCH` version according to the intended
+compatibility change. A selected version remains an unreleased candidate until
+its annotated tag is published, the hosted workflow succeeds, and every
+published artifact is verified.
+
+Run this procedure from the Scriptorium repository root. A release must not
+depend on a Go workspace, module replacement, vendor tree, sibling checkout,
+unpublished dependency, or unpushed source commit.
+
+## Establish The Candidate
+
+Start a POSIX shell, choose a semantic version that has not been published, and
+export it as `RELEASE_VERSION`. For example, if `v0.12.1` is the intended next
+version and remains unpublished, select:
+
+```sh
+export RELEASE_VERSION=v0.12.1
+```
+
+Use the version appropriate to the actual compatibility change rather than
+assuming that the example is the next release. Then run the following guard in
+that same shell:
+
+```sh
+set -eu
+
+: "${RELEASE_VERSION:?export an unpublished vMAJOR.MINOR.PATCH version}"
+if ! printf '%s\n' "$RELEASE_VERSION" |
+    grep -Eq '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'
+then
+    printf '%s\n' "invalid release version: $RELEASE_VERSION" >&2
+    exit 1
+fi
+
+RELEASE_COMMIT=$(git rev-parse --verify 'HEAD^{commit}')
+export RELEASE_COMMIT
+
+check_release_candidate() {
+    test "$(git branch --show-current)" = main
+    test -z "$(git status --porcelain)"
+
+    gowork_value=$(go env GOWORK)
+    case "$gowork_value" in
+        ''|off) ;;
+        *)
+            printf '%s\n' "active Go workspace: $gowork_value" >&2
+            return 1
+            ;;
+    esac
+
+    test -z "$(git ls-files go.work go.work.sum)"
+    test ! -e vendor
+    if grep -Eq '^[[:space:]]*replace([[:space:]]|\()' go.mod
+    then
+        printf '%s\n' 'go.mod contains a replacement' >&2
+        return 1
+    fi
+
+    git fetch origin main --tags
+    test "$RELEASE_COMMIT" = \
+        "$(git rev-parse --verify 'refs/remotes/origin/main^{commit}')"
+
+    if git show-ref --verify --quiet "refs/tags/$RELEASE_VERSION"
+    then
+        printf '%s\n' "local tag already exists: $RELEASE_VERSION" >&2
+        return 1
+    fi
+    if test -n "$(
+        git ls-remote --tags origin \
+            "refs/tags/$RELEASE_VERSION" \
+            "refs/tags/$RELEASE_VERSION^{}"
+    )"
+    then
+        printf '%s\n' "remote tag already exists: $RELEASE_VERSION" >&2
+        return 1
+    fi
+}
+
+check_release_candidate
+```
+
+Do not continue unless this guard succeeds. It deliberately requires the
+candidate to be the exact clean commit already published at `origin/main`.
+
+## Verify Modules And Repository Boundaries
+
+Confirm the module path and declared Go version:
+
+```sh
+test "$(
+    GOWORK=off go list -m -f '{{.Path}} {{.GoVersion}}'
+)" = 'gitea.maximumdirect.net/eric/scriptorium 1.25.5'
+```
+
+Require Promptkit `v0.1.0` as both the direct module-graph edge and the selected
+module version:
+
+```sh
+direct_promptkit=$(
+    GOWORK=off go mod graph |
+        awk '
+            $1 == "gitea.maximumdirect.net/eric/scriptorium" &&
+            $2 ~ /^gitea\.maximumdirect\.net\/eric\/promptkit@/ {
+                print $2
+            }
+        '
+)
+test "$direct_promptkit" = \
+    'gitea.maximumdirect.net/eric/promptkit@v0.1.0'
+test "$(
+    GOWORK=off go list -m -f '{{.Path}}@{{.Version}}' \
+        gitea.maximumdirect.net/eric/promptkit
+)" = 'gitea.maximumdirect.net/eric/promptkit@v0.1.0'
+GOWORK=off go list -m all
+```
+
+Require tidy module metadata and recheck the repository exclusions:
+
+```sh
+GOWORK=off go mod tidy -diff
+test -z "$(git ls-files go.work go.work.sum)"
+test ! -e vendor
+if grep -Eq '^[[:space:]]*replace([[:space:]]|\()' go.mod
+then
+    printf '%s\n' 'go.mod contains a replacement' >&2
+    exit 1
+fi
+test -z "$(git status --porcelain)"
+```
+
+## Validate The Application
+
+Run the complete application validation:
+
+```sh
+GOWORK=off go test ./...
+GOWORK=off go test -race ./...
+GOWORK=off go vet ./...
+validation_build_dir=$(mktemp -d)
+GOWORK=off go build \
+    -o "$validation_build_dir/scriptorium" \
+    ./cmd/scriptorium
+```
+
+The ordinary test run includes the architecture guard that rejects a root Go
+package, former framework package families, and imports of Promptkit internal
+packages. Inspect the repository for generated binaries, credentials,
+temporary output, sibling paths, and other files that do not belong in the
+tracked release source.
+
+Check every tracked Go file. This command must produce no output:
+
+```sh
+unformatted=$(
+    git ls-files '*.go' |
+        while IFS= read -r go_file
+        do
+            gofmt -l "$go_file"
+        done
+)
+test -z "$unformatted"
+```
+
+Run the maintained render script and smoke-test both maintained configuration
+examples without a model call:
+
+```sh
+GOWORK=off ./examples/render-markdown-summary.sh
+for config_file in examples/config.yml examples/config.full.yml
+do
+    GOWORK=off go run ./cmd/scriptorium render \
+        --config "$config_file" \
+        --prompt generic.markdown_summary \
+        --input transcript=./examples/fixtures/transcript.md \
+        --input glossary=./examples/fixtures/glossary.yml \
+        --format json >/dev/null
+done
+```
+
+Exercise usage output and offline rendering with the temporary native
+executable:
+
+```sh
+usage_output="$validation_build_dir/usage.txt"
+if "$validation_build_dir/scriptorium" >"$usage_output" 2>&1
+then
+    printf '%s\n' 'expected an invocation without a command to fail' >&2
+    exit 1
+fi
+grep -F 'usage: scriptorium' "$usage_output"
+"$validation_build_dir/scriptorium" render \
+    --config ./examples/config.yml \
+    --prompt generic.markdown_summary \
+    --input transcript=./examples/fixtures/transcript.md \
+    --input glossary=./examples/fixtures/glossary.yml \
+    --format text >/dev/null
+```
+
+Follow every maintained local, Promptkit-tagged, and other external Markdown
+link. Confirm that all repository-relative link targets exist. Finish the
+application checks with:
+
+```sh
+git diff --check
+test -z "$(git status --porcelain)"
+```
+
+## Require Release Notes And Reproduce Packaging
+
+The immutable release note must exist before tagging:
+
+```sh
+release_notes="docs/releases/$RELEASE_VERSION.md"
+test -f "$release_notes"
+test -s "$release_notes"
+```
+
+Validate every local and currently published link in the note. For links
+pinned to the candidate Scriptorium tag, confirm that the corresponding
+repository-relative path exists even though its tag URL is not live yet.
+
+Reproduce the hosted build flags, targets, and filenames in a temporary
+directory:
+
+```sh
+release_dist=$(mktemp -d)
+release_package='gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium'
+
+build_release_binary() {
+    target_os="$1"
+    target_arch="$2"
+    output="$release_dist/scriptorium-$RELEASE_VERSION-$target_os-$target_arch"
+
+    CGO_ENABLED=0 GOOS="$target_os" GOARCH="$target_arch" GOWORK=off \
+        go build -trimpath -ldflags '-s -w' \
+        -o "$output" "$release_package"
+}
+
+build_release_binary linux amd64
+build_release_binary linux arm64
+
+test -s "$release_dist/scriptorium-$RELEASE_VERSION-linux-amd64"
+test -s "$release_dist/scriptorium-$RELEASE_VERSION-linux-arm64"
+file "$release_dist/scriptorium-$RELEASE_VERSION-linux-amd64"
+file "$release_dist/scriptorium-$RELEASE_VERSION-linux-arm64"
+```
+
+Require `file` to identify Linux executables for `x86-64` and `ARM aarch64`,
+respectively. Inspect the
+[hosted workflow](../.woodpecker/release.yml) and confirm that it uses the
+same build flags and names, copies the selected release note to
+`dist/RELEASE_NOTES.md`, publishes only `dist/scriptorium-*`, and keeps
+checksum generation enabled.
+
+## Create And Publish The Tag
+
+Run the candidate guard again immediately before creating the tag:
+
+```sh
+check_release_candidate
+test -f "$release_notes"
+test -s "$release_notes"
+```
+
+Create an annotated tag explicitly bound to the validated commit, using the
+version-specific release note as its message:
+
+```sh
+git tag --annotate "$RELEASE_VERSION" \
+    --file "$release_notes" \
+    "$RELEASE_COMMIT"
+```
+
+Inspect the tag and require it to resolve to the validated source:
+
+```sh
+test "$(git cat-file -t "refs/tags/$RELEASE_VERSION")" = tag
+git show --no-patch --decorate "refs/tags/$RELEASE_VERSION"
+test "$(
+    git rev-parse --verify "refs/tags/$RELEASE_VERSION^{commit}"
+)" = "$RELEASE_COMMIT"
+```
+
+If inspection finds an error, delete only the unpublished local tag, correct
+the candidate, and repeat the complete validation. Never move or recreate a
+published tag.
+
+Push only the selected tag ref:
+
+```sh
+git push origin \
+    "refs/tags/$RELEASE_VERSION:refs/tags/$RELEASE_VERSION"
+```
+
+## Observe And Verify Publication
+
+Open the hosted workflow run for the selected tag. Require
+`build-release-assets` to succeed before `publish-release`, then require the
+publication step and hosted release to succeed. A queued, running, failed, or
+partially published workflow is not a verified release.
+
+Compare the local and remote annotated-tag objects and their source commits:
+
+```sh
+remote_tag=$(
+    git ls-remote --tags origin "refs/tags/$RELEASE_VERSION" |
+        awk 'NR == 1 { print $1 }'
+)
+remote_commit=$(
+    git ls-remote --tags origin "refs/tags/$RELEASE_VERSION^{}" |
+        awk 'NR == 1 { print $1 }'
+)
+test -n "$remote_tag"
+test "$remote_tag" = \
+    "$(git rev-parse --verify "refs/tags/$RELEASE_VERSION")"
+test "$remote_commit" = "$RELEASE_COMMIT"
+```
+
+Download the hosted binaries and checksum file into a temporary directory:
+
+```sh
+release_base="https://gitea.maximumdirect.net/eric/scriptorium/releases/download/$RELEASE_VERSION"
+download_dir=$(mktemp -d)
+(
+    cd "$download_dir"
+    for asset in \
+        "scriptorium-$RELEASE_VERSION-linux-amd64" \
+        "scriptorium-$RELEASE_VERSION-linux-arm64" \
+        SHA256SUMS
+    do
+        curl --fail --location --remote-name "$release_base/$asset"
+    done
+
+    test -s "scriptorium-$RELEASE_VERSION-linux-amd64"
+    test -s "scriptorium-$RELEASE_VERSION-linux-arm64"
+    test -s SHA256SUMS
+    sha256sum --check SHA256SUMS
+    test "$(wc -l < SHA256SUMS | tr -d ' ')" = 2
+    file "scriptorium-$RELEASE_VERSION-linux-amd64"
+    file "scriptorium-$RELEASE_VERSION-linux-arm64"
+)
+```
+
+Require the same Linux architectures observed in the local packaging check and
+confirm that the hosted release contains no unexpected asset. On a compatible
+Linux host, make the matching downloaded binary executable and repeat the
+usage-output and offline-render smoke checks against it.
+
+Only after the tag, workflow, release body, binaries, architectures, and
+checksums all pass verification is the candidate a verified published release.
+
+## Handle Failures
+
+Before tag publication, correct the release commit or note and restart the
+complete procedure. After tag publication, never delete, move, overwrite, or
+recreate the tag. A transient hosted failure may be retried only against the
+same immutable tag and commit and only when doing so cannot overwrite or
+silently retain partial assets. A source, packaging, note, or artifact defect
+requires a new corrective semantic version from a new validated commit.
+
+Record the selected version, validated commit, tag object, workflow result,
+artifact names, checksum result, and smoke-check outcome in the release
+checkpoint. Keep temporary builds and downloaded assets outside the repository,
+and require a clean `main` synchronized with `origin/main` when verification
+is complete.

docs/releases/v0.12.0.md

@@ -0,0 +1,36 @@
+# Scriptorium v0.12.0
+
+## Breaking Project Boundary
+
+Scriptorium is now an executable-only CLI and HTTP application. This is a
+breaking change for Go consumers: the former root Go package is not included,
+and no compatibility facade is provided.
+
+Scriptorium `v0.11.1` was the final framework-bearing release. Former Go
+consumers should follow the
+[migration guide](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.12.0/docs/consumers/migrating-to-promptkit.md)
+and adopt
+[Promptkit `v0.1.0`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md)
+for in-process prompt preparation and execution.
+
+## Application Interfaces
+
+The Scriptorium command-line and HTTP application interfaces remain. Their
+canonical documentation defines the supported commands, configuration,
+requests, responses, operational behavior, and deployment responsibilities:
+
+- [CLI reference](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.12.0/docs/cli.md)
+- [HTTP API reference](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.12.0/docs/api.md)
+- [Configuration reference](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.12.0/docs/config.md)
+- [Operations guide](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.12.0/docs/operations.md)
+
+## Framework Dependency And Consumers
+
+The released Scriptorium binaries use Promptkit `v0.1.0` as their framework
+dependency. Promptkit owns the reusable engine, source formats, profiles,
+generation boundary, and validation contracts. See the
+[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md)
+for that supported API.
+
+All known downstream Go consumers were migrated to Promptkit before this
+release.

docs/roadmap/implementation.md

@@ -1,64 +0,0 @@
-# Step 7 Implementation Completion
-
-## Status
-
-Complete as of 2026-07-28.
-
-## Result
-
-Scriptorium now consumes
-`gitea.maximumdirect.net/eric/promptkit v0.1.0` as an ordinary direct module
-dependency. The published tag resolves to Promptkit commit
-`9e68a2bbf779545995270c47842048a3bc6c85dc`; no workspace, replacement,
-vendored dependency, or sibling-repository state is required.
-
-The Scriptorium module root no longer exposes a Go package. The remaining
-production boundary consists of:
-
-- `cmd/scriptorium`;
-- `internal/adapter/cli`;
-- `internal/adapter/http`;
-- `internal/config`;
-- `internal/defaults`; and
-- `internal/format`.
-
-The CLI constructs and invokes Promptkit engines, the HTTP adapter maps its
-transport contract to Promptkit public values, and the HTTP-specific restricted
-artifact reader is injected through Promptkit's public extension point.
-Scriptorium retains application configuration, presentation, transport,
-containment, process, packaging, and executable-example responsibilities.
-
-The former root facade, duplicated framework packages, built-in profile copy,
-framework tests and fixtures, Go-library example, and framework-owned
-documentation were removed. Permanent Scriptorium documentation now describes
-the CLI and HTTP application and links to the tagged Promptkit documentation
-for framework contracts.
-
-## Validation Evidence
-
-Scriptorium passed, outside a Go workspace and without a replacement:
-
-- module identity, graph, tagged dependency, and `go mod tidy -diff` checks;
-- ordinary and race-enabled tests, including retained HTTP decoding, limit,
-  restricted-file, error-mapping, and raw-output coverage;
-- vet, formatting, whitespace, architecture, and tracked-tree hygiene checks;
-- temporary native and release-equivalent Linux `amd64` and `arm64` builds;
-- the maintained render script and both configuration examples without model
-  credentials; and
-- all maintained local and tagged Promptkit documentation links.
-
-A fresh temporary module and build cache resolved Promptkit remotely, reported
-the expected `v0.1.0` origin commit, and passed the Scriptorium test suite and
-build without reading the sibling Promptkit checkout.
-
-Promptkit was reconfirmed independently at the exact published tag. Its local
-and remote tag targets agree, its working tree remains clean, and its
-documented test, race, vet, build, example, formatting, module, link,
-whitespace, and repository-hygiene checks pass.
-
-## Next Gate
-
-[Step 8](migration.md#step-8-migrate-downstream-consumers-to-promptkit) may
-now inventory and migrate downstream Go consumers. Step 7 did not migrate
-external consumers, publish a breaking Scriptorium release, or complete the
-release and documentation cutover assigned to Step 9.

docs/roadmap/migration.md

@@ -1,335 +0,0 @@
-# Promptkit Migration Roadmap
-
-## Status
-
-Accepted plan. Steps 1 through 7 are complete. Steps 8 and 9 remain proposed
-and are not yet implemented.
-
-## Objective
-
-Split the current repository into two projects:
-
-- **Promptkit**: the reusable Go framework, public Go facade, execution engine,
-  source and validation support, OpenAI-compatible client, extension
-  interfaces, and built-in execution-profile registry.
-- **Scriptorium**: a slim runnable application that imports Promptkit and
-  provides the CLI and HTTP interfaces.
-
-Scriptorium will become another downstream Promptkit consumer rather than the
-owner of the framework.
-
-## Compatibility And Migration Policy
-
-This is an intentionally breaking change.
-
-- New and migrated Go consumers must import Promptkit instead of Scriptorium.
-- Scriptorium will not retain type aliases, forwarding packages, deprecated
-  facade APIs, or other source-compatibility shims.
-- Existing consumers may continue using a previously tagged Scriptorium module
-  version until they are migrated.
-- The migration does not need to preserve compatibility between intermediate
-  development states. Each completed phase must instead leave the affected
-  repository internally consistent and tested.
-- Promptkit should initially preserve the useful shape and behavior of the
-  current public Go facade where doing so reduces extraction risk. Broader API
-  redesign should follow the split unless required to establish the new
-  boundary.
-
-## Target Ownership
-
-Promptkit should own application-neutral framework behavior:
-
-- public engine, request, result, option, extension, and error APIs;
-- prompt-definition loading and rendering;
-- execution profiles, overlays, and the built-in profile registry;
-- artifact-loading interfaces and general-purpose `file` and `inline` support;
-- schema loading and output validation;
-- LLM client boundaries and the OpenAI-compatible implementation;
-- preparation and execution orchestration;
-- framework and execution defaults.
-
-Scriptorium should own executable and transport concerns:
-
-- the `scriptorium` command and its `run`, `render`, and `serve` interfaces;
-- CLI parsing, output formatting, exit codes, and process behavior;
-- application-config discovery and CLI precedence;
-- HTTP routing, request and response DTOs, limits, and error/status mapping;
-- HTTP artifact-root and deployment security policy;
-- server and adapter defaults;
-- executable examples, operations guidance, and transport documentation.
-
-The intended dependency direction is:
-
-```text
-Scriptorium CLI and HTTP adapters
-                |
-                v
-             Promptkit
-                |
-                v
-     consumer-supplied sources and clients
-```
-
-Scriptorium must use Promptkit's public API. It must not depend on Promptkit
-implementation packages or reproduce framework orchestration.
-
-## Migration Steps
-
-### Step 1: Refresh And Synchronize Documentation
-
-Perform a repository-wide documentation refresh before migration development.
-
-At minimum:
-
-- reconcile all current-behavior documentation with the code, tests, examples,
-  defaults, and current public contracts;
-- introduce the planned documentation-policy updates;
-- establish an architecture decision record policy and canonical ADR location;
-- resolve stale, duplicated, or misplaced material;
-- validate documentation links and maintained examples;
-- leave future migration behavior in `docs/roadmap/` until implemented.
-
-**Gate:** Do not begin architectural migration work until the documentation
-refresh and policy updates are merged and the repository has an agreed,
-accurate baseline.
-
-**Gate status:** Complete as of 2026-07-26. The completed documentation
-refresh, follow-up verification, and layered-timeout correction remain recorded
-in repository history. Step 1 remains complete after that validation.
-
-### Step 2: Record The Architectural Decision And Detailed Boundary
-
-Create an ADR, under the policy established in Step 1, that records:
-
-- the decision to split Promptkit from Scriptorium;
-- the target ownership and dependency direction;
-- the selected Promptkit repository and Go module paths;
-- the breaking-change and versioning policy;
-- ownership of configuration fields and defaults;
-- artifact-reader and HTTP containment responsibilities;
-- local multi-repository development and release coordination;
-- documentation ownership after the split.
-
-Use the ADR to resolve any remaining public-boundary decisions before code is
-moved.
-
-**Gate:** The ADR is accepted, and every existing package, public contract,
-configuration category, and maintained asset has a target owner.
-
-**Gate status:** Complete as of 2026-07-26.
-[ADR 0002: Split Promptkit From Scriptorium](../adr/0002-split-promptkit-from-scriptorium.md)
-is accepted and records the required ownership and coordination decisions.
-
-### Step 3: Characterize Existing Framework Behavior
-
-Strengthen or add contract-focused tests where needed so extraction can be
-verified without relying on package placement.
-
-The completed Step 3 gate records the accepted implementation scope and
-intended completion state.
-
-Preserve coverage of:
-
-- `Prepare` and `Run` behavior;
-- prompt, profile, execution-default, and request-override precedence;
-- presence-aware numeric overrides;
-- built-in profile fallback and custom-profile overlays;
-- strict YAML and JSON decoding;
-- prompt, profile, schema, and artifact source behavior;
-- structured-output requests and output validation;
-- validation failures versus validation runtime errors;
-- secret handling and redaction;
-- public error classification;
-- HTTP artifact restrictions and transport mappings.
-
-**Gate:** Current framework and adapter contracts are represented by passing
-tests sufficient to detect behavioral regressions during the split.
-
-**Gate status:** Complete as of 2026-07-27. The framework contract corpus,
-public `Engine` characterization, ownership audit, full test and vet suites,
-temporary executable build, and maintained offline examples passed.
-
-### Step 4: Make Scriptorium Adapters Consume The Public Facade
-
-Within the current repository, refactor the CLI and HTTP adapters to use the
-public framework facade rather than constructing or importing internal runner
-components directly.
-
-Add only the minimum public capabilities needed to support this boundary. These
-may include:
-
-- a small `Run`/`Prepare` consumer interface;
-- injectable artifact-reading behavior for Scriptorium's restricted HTTP
-  policy;
-- source options currently available only through internal constructors;
-- prepared-run formatting based on public types;
-- stable public error classification required by CLI and HTTP mappings.
-
-Do not broadly export internal repositories, domain types, or use-case
-implementations.
-
-**Gate:** The CLI and HTTP adapters use only the public framework API for
-framework behavior, and all tests and documented smoke commands pass.
-
-**Gate status:** Complete as of 2026-07-28. CLI `run`, `render`, and `serve`,
-the HTTP handler, and prepared-run formatting use the public facade; the
-restricted HTTP reader is injected through the public extension point. The
-post-implementation public-error, deterministic MIME, and recursive
-dependency-guard corrections passed full tests, vet, build, race checks,
-maintained examples, and configuration smoke checks.
-
-### Step 5: Create The Promptkit Repository
-
-Promptkit was established as an independent repository and Go module through
-the completed out-of-band workflow recorded in repository history. Its
-foundation includes:
-
-- confirmed repository access, governance, origin, and default-branch tracking;
-- module `gitea.maximumdirect.net/eric/promptkit` at Go `1.25.5`;
-- a minimal root `promptkit` public package boundary with no placeholder
-  framework packages;
-- library-specific development, architecture, documentation, testing, and
-  release policies;
-- documented maintainer-run test, vet, build, formatting, documentation-link,
-  and repository-hygiene validation;
-- source-commit and semantic Go module tag releases without runnable binaries
-  or binary packaging; and
-- temporary workspace and uncommitted replacement workflows for coordinated
-  development without committed repository coupling.
-
-[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md)
-records the controlling Promptkit validation and release decision.
-
-**Gate status:** Complete as of 2026-07-28. Promptkit passed its documented
-validation independently, all maintained links and repository-hygiene checks
-passed, and no workspace, replacement, CI configuration, binary, tag, command,
-or placeholder package was added. The completed repository foundation
-supported the Step 6 extraction.
-
-### Step 6: Extract And Stabilize Promptkit
-
-Move the application-neutral framework and built-in profile assets into
-Promptkit. Preserve implementation packages as internal where practical.
-
-The initial public API should remain focused on the established engine workflow
-and the source and client extension points required by real consumers. Avoid
-combining the extraction with unrelated API redesign.
-
-Move or recreate the relevant:
-
-- framework implementation;
-- public package tests and framework contract tests;
-- built-in profile assets and registry tests;
-- Go consumer examples;
-- framework, consumer, configuration-format, and integration documentation.
-
-Verify that Promptkit can be built, tested, and consumed independently of the
-Scriptorium repository.
-
-**Gate:** Promptkit independently provides the agreed framework contract,
-passes its documented validation, and has published its first versioned tag
-before Scriptorium or another consumer adopts it, as required by
-[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md).
-
-**Gate status:** Complete as of 2026-07-28. Repository history records source
-Scriptorium commit `c7263ab2a8e58f7fb97280082d327a820c7cece7`,
-accepted Promptkit commit
-`9e68a2bbf779545995270c47842048a3bc6c85dc`, independently passing acceptance,
-published annotated tag `v0.1.0`, and successful remote-consumer validation.
-Scriptorium remains unchanged at its pre-cutover boundary. Step 7 adoption of
-the tagged module and removal of the duplicated framework is the next gate.
-
-### Step 7: Slim Scriptorium And Adopt Promptkit
-
-Update Scriptorium to import the tagged Promptkit module and remove the
-framework implementation and public Go facade that Promptkit replaces.
-
-Retain only Scriptorium-owned executable and transport behavior. In particular:
-
-- wire CLI and HTTP requests through Promptkit's public API;
-- keep application config and transport defaults in Scriptorium;
-- keep restricted HTTP artifact policy in Scriptorium while injecting it
-  through Promptkit's supported boundary;
-- remove obsolete framework packages, tests, and documentation;
-- update Scriptorium examples and docs to describe the CLI and HTTP application;
-- direct Go framework consumers to Promptkit without providing compatibility
-  aliases or forwarding APIs.
-
-**Gate:** Scriptorium builds and passes all tests using a tagged Promptkit
-dependency, contains no duplicate framework implementation, and its current
-documentation describes only the slimmed application.
-
-**Gate status:** Complete as of 2026-07-28. Scriptorium directly resolves
-Promptkit `v0.1.0`, no longer contains the framework copy or public Go facade,
-and retains only its application, adapter, configuration, presentation,
-transport, packaging, and executable-example responsibilities. Release-grade
-Scriptorium validation passed with a fresh remote dependency cache, and the
-published Promptkit tag passed its documented validation independently. The
-application is ready for the downstream-consumer migrations in Step 8.
-
-### Step 8: Migrate Downstream Consumers To Promptkit
-
-Inventory downstream Go consumers and migrate each from the Scriptorium package
-to Promptkit. This work may occur in external repositories and must be tracked
-explicitly.
-
-For each consumer:
-
-- update module imports and dependencies;
-- adapt to any intentionally changed public API;
-- run its tests and relevant integration or smoke checks;
-- confirm configuration, source, validation, and error behavior;
-- release or deploy the migrated consumer through its normal process.
-
-Consumers that cannot migrate immediately may remain pinned to the last
-framework-bearing Scriptorium tag. No compatibility work is required in the new
-Scriptorium project for those consumers.
-
-**Gate:** All in-scope downstream consumers are either migrated and verified or
-explicitly recorded as remaining on the previous Scriptorium version with an
-owner and follow-up plan. Do not declare the ecosystem migration complete until
-the required out-of-band consumer changes are confirmed.
-
-### Step 9: Complete Release And Documentation Cutover
-
-Complete the coordinated project transition:
-
-- publish Promptkit before dependent Scriptorium releases;
-- release the breaking Scriptorium version against the tagged Promptkit
-  dependency;
-- publish migration guidance that maps the former Scriptorium Go API to
-  Promptkit;
-- update cross-project links, examples, package documentation, and release
-  notes;
-- verify that no release artifact depends on local workspaces or replacements;
-- archive completed roadmap material according to the documentation policy in
-  effect at that time.
-
-**Gate:** Promptkit and Scriptorium are independently releasable, their
-documentation has distinct and accurate ownership, and the migration status of
-all identified downstream consumers is recorded.
-
-## Cross-Cutting Constraints
-
-- Preserve the invariant that execution orchestration remains narrow and
-  application-neutral.
-- Keep adapter-specific decisions out of Promptkit.
-- Keep Scriptorium dependent only on Promptkit's supported public API.
-- Preserve strict external decoding, error classification, validation
-  semantics, and secret redaction throughout the migration.
-- Keep each repository buildable and testable at merged phase boundaries.
-- Coordinate cross-repository changes through tagged dependencies and explicit
-  gates rather than assuming atomic commits across repositories.
-- Document only implemented behavior outside roadmap files.
-
-## Completion Criteria
-
-The migration is complete when:
-
-- Promptkit is the independent owner of the reusable framework and built-in
-  profiles;
-- Scriptorium is a slim CLI and HTTP consumer of Promptkit;
-- Scriptorium no longer exposes or maintains the former public Go framework;
-- all required downstream migrations and external repository work have been
-  completed or explicitly dispositioned;
-- both repositories build, test, document, version, and release independently.

docs/roadmap/step7.md

@@ -1,64 +0,0 @@
-# Migration Step 7: Slim Scriptorium And Adopt Promptkit
-
-## Status
-
-Complete as of 2026-07-28.
-
-## Result
-
-Scriptorium is now an application-only consumer of the published
-`gitea.maximumdirect.net/eric/promptkit v0.1.0` module. The command, CLI and
-HTTP adapters, restricted artifact reader, and prepared-run formatter use
-Promptkit's supported public API. The dependency resolves normally to
-Promptkit commit `9e68a2bbf779545995270c47842048a3bc6c85dc` without a workspace,
-replacement, vendored copy, or unpublished revision.
-
-The Scriptorium module root no longer provides an importable Go package or
-compatibility facade. The reusable framework packages, embedded built-in
-profiles, framework contract tests and fixtures, and Go-library example were
-removed. Architecture tests prevent production imports of the former root
-facade, removed framework package families, and Promptkit internals.
-
-## Retained Application Boundary
-
-Scriptorium owns only its runnable process and application concerns:
-
-- command and CLI parsing, assembly, streams, summaries, and exit behavior;
-- HTTP routes, DTOs, strict decoding, limits, public error mapping, and
-  restricted artifact access;
-- application configuration discovery, validation, precedence, and transport
-  defaults;
-- prepared-run text and JSON presentation;
-- executable examples, operations guidance, and binary packaging.
-
-Promptkit owns prompt execution, framework sources and formats, validation,
-model integration, built-in profiles, and ordinary artifact loading.
-Scriptorium's permanent documentation reflects that boundary and links to the
-tagged Promptkit contracts rather than duplicating them.
-
-## Acceptance
-
-The completed cutover passed:
-
-- module graph and tidiness checks selecting exactly Promptkit `v0.1.0`;
-- ordinary and race-enabled Scriptorium tests, vet, formatting, whitespace,
-  architecture, and repository-hygiene checks;
-- temporary native and release-equivalent cross-builds;
-- maintained offline render workflows with both application configurations;
-- maintained local and tagged-documentation link checks;
-- fresh-cache remote dependency resolution, tests, and build with the expected
-  Promptkit origin commit; and
-- Promptkit's complete documented validation independently at its clean local
-  and remote `v0.1.0` tag.
-
-These checks cover the retained CLI, HTTP, configuration, containment,
-formatting, error-mapping, security, and representative executable behavior.
-The working trees contain no generated binaries, temporary workspaces,
-replacement directives, credentials, or migration residue.
-
-## Handoff
-
-The Step 7 gate is satisfied. [Step 8](migration.md#step-8-migrate-downstream-consumers-to-promptkit)
-owns downstream consumer inventory and migration. Step 9 remains responsible
-for the breaking Scriptorium release and final documentation cutover; neither
-later gate is complete.