# 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.