Document Scriptorium as a Promptkit application

docs/development.md

@@ -1,63 +1,56 @@
 # Development
 
-This is the contributor entry point for Scriptorium. Use the task-specific
-reading guide below before making changes. Canonical architecture, contracts,
-component behavior, and policies remain in their owning documents.
+This is the contributor entry point for Scriptorium. Scriptorium is an
+application that consumes the public
+[Promptkit v0.1.0 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md);
+framework implementation work belongs in Promptkit.
 
 ## Initial Orientation
 
 Before starting work:
 
 1. inspect the working tree and preserve unrelated changes;
-2. read the architecture policy for code or design work;
-3. read the policy, contract, and internal documents listed for the task;
-4. inspect the relevant implementation and tests before deciding how to change
-   them.
+2. read the [architecture policy](policy/architecture.md);
+3. follow the task-specific contracts and internal documents below; and
+4. inspect the relevant implementation and tests before changing them.
 
-Start with:
-
-- [Architecture policy](policy/architecture.md) for system boundaries,
-  invariants, and non-goals;
-- [Internal component overview](internal/overview.md) for the current package
-  and component map;
-- [Documentation policy](policy/documentation.md) before changing
-  documentation;
-- [Testing policy](policy/testing.md) before adding, rewriting, or deleting
-  tests.
+Also read the [documentation policy](policy/documentation.md) before changing
+documentation and the [testing policy](policy/testing.md) before changing
+tests.
 
 ## Task-Specific Reading Guide
 
 | Task | Read before changing |
 | --- | --- |
 | Repository orientation or component responsibility | [Internal component overview](internal/overview.md) and [architecture policy](policy/architecture.md) |
-| Public Go package or engine behavior | [Go package consumer contract](consumers/pkg-scriptorium.md), [internal component overview](internal/overview.md), [runner internals](internal/runner.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
-| CLI commands, flags, output, or exit behavior | [CLI contract](cli.md), [internal component overview](internal/overview.md), and [adapter internals](internal/adapters.md) |
-| HTTP routes, DTOs, limits, or status mapping | [HTTP API contract](api.md), [internal component overview](internal/overview.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
-| Application configuration | [Configuration contract](config.md), [internal component overview](internal/overview.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
-| Prompt, profile, schema, or artifact loading | [Configuration contract](config.md), [internal component overview](internal/overview.md), and [source internals](internal/sources.md) |
-| Runner orchestration, rendering, validation, or repair | [Runner internals](internal/runner.md) and [source internals](internal/sources.md) |
-| OpenAI-compatible request or response behavior | [OpenAI-compatible integration](integrations/openai-compatible-chat.md), [LLM internals](internal/llm.md), [runner internals](internal/runner.md), and [adapter internals](internal/adapters.md) |
+| CLI commands, flags, output, or exit behavior | [CLI contract](cli.md) and [adapter internals](internal/adapters.md) |
+| 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), and [source internals](internal/sources.md) |
+| 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.1.0/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md) |
+| 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) |
-| Examples or copyable assets | The owning contract for the demonstrated behavior and the related files under `examples/` |
-| Architecture decisions or future work | The [documentation policy](policy/documentation.md), relevant accepted ADRs such as [ADR 0001](adr/0001-adopt-canonical-documentation-ownership.md), and relevant roadmap documents under `roadmap/` |
+| Release packaging | `.woodpecker/release.yml`, [operations](operations.md), and the architecture policy |
+| 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 |
 
-For cross-cutting changes, follow every applicable row. Internal component
-documents own detailed subsystem change recipes.
+Cross-project changes land and release in Promptkit before Scriptorium adopts
+the tagged version. Do not commit a Go workspace, local replacement, vendored
+Promptkit source, or an import of a Promptkit `internal` package.
 
 ## Baseline Validation
 
-Use focused checks while iterating, then run validation proportionate to the
-change and the risks described by the testing policy.
-
-The repository-level baseline for code changes is:
+For code changes, run:
 
 ```bash
 go test ./...
+go test -race ./...
 go vet ./...
 go build ./cmd/scriptorium
 ```
 
-Documentation-only work does not require the full Go suite unless it changes
-commands, examples, generated output, or another behavior that the suite
-validates. Always check changed links, paths, examples, and canonical ownership.
+Check formatting with `gofmt`, run `git diff --check`, and validate affected
+examples and documentation links. Documentation-only work does not require
+unrelated new tests, but commands and examples changed by documentation must be
+run.