Files
scriptorium/docs/config.md

159 lines
8.9 KiB
Markdown

# Configuration Reference
This document owns Scriptorium's application settings, discovery, and source
selection. [CLI syntax](cli.md) and the [HTTP API](api.md) have separate owners.
Framework definitions and execution semantics belong to the pinned
[PromptKit v0.23.3 formats][formats]; ConfigKit v1.2.1 owns
[native composition and inspection][configkit].
## Discovery And Precedence
An explicit `--config` selects that file, including an explicitly empty value
(which fails rather than falling back). With no selection, ConfigKit searches
these native presets in order, selecting one main file:
| Preset | Directories in order | Filename groups |
| --- | --- | --- |
| WorkingDirectory | Current working directory | Named only |
| UserConfigDirectory | Go user-config directory / `scriptorium`, then the user-config directory | Named then Generic in the application directory; Named only in the base |
| HomeDirectory | Go home directory / `.scriptorium`, then the home directory | Named then Generic in the application directory; Named only in the base |
| UnixSystemDirectories | `/usr/local/etc/scriptorium`, `/etc/scriptorium`, then `/etc` | Named then Generic in application directories; Named only in `/etc` |
Named means `scriptorium.yml`, then `scriptorium.yaml`. Generic means
`config.yml`, `config.yaml`, `main.yml`, then `main.yaml`.
ConfigKit uses native Go directory resolution (including its user-config/home
environment behavior) and checks every filename in one directory before the next.
Candidates are not configuration layers. Optional exhaustion uses application
defaults; a selected-file acquisition/decoding error is terminal.
ConfigKit assembles the main, enabled imports, and selected overlay, applies its
inheritance/composition rules, creates typed defaults and strictly decodes, applies
explicit override records, then runs application normalization and validation.
An override can correct a decoded value before validation, but cannot repair
source/composition/decoding errors. The completed result is authoritative:
runtime settings conversion does not merge, default, or normalize again.
## Application Settings
Complete copyable configurations are maintained under
[examples](../examples/config.yml), including [full settings](../examples/config.full.yml),
[application imports](../examples/config.composed.yml),
[framework fragment composition](../examples/config.collections.yml),
[collection checkout discovery](../examples/config.discovery.yml), and
[framework inheritance](../examples/config.inheritance.yml).
```yaml
promptkit:
configuration: ./examples/promptkit.yml
schema_dir: ./examples/schemas
```
The `promptkit` section contains acquisition settings, not embedded framework
definitions. Profiles, prompts, backends, and collections belong in the separate
framework document. The retired `promptkit_sources`, top-level `schema_dir`,
and `defaults.render_format` fields have no compatibility conversion and are
rejected by strict decoding, as are unknown/raw credential fields.
| Field | Default | Meaning |
| --- | --- | --- |
| `promptkit.configuration` | empty | One external framework file; omission/empty selects no external main. |
| `promptkit.schema_dir` | `.` | Schema base directory passed to PromptKit. |
| `transient_retries` | upstream default | Optional nonnegative engine retry count. Omitted/null delegates upstream; zero disables additional transient attempts. |
| `server.addr` | `:8080` | HTTP listen address. |
| `server.artifact_root` | empty | Root enabling HTTP file-artifact references. |
| `server.max_request_bytes` | `16777216` | Encoded HTTP request limit; zero is unlimited. |
| `server.max_artifact_bytes` | `16777216` | HTTP file-artifact limit; zero is unlimited. |
| `server.max_response_bytes` | `16777216` | Encoded HTTP response limit; zero is unlimited. |
Size fields are nonnegative signed 64-bit values. [HTTP behavior](api.md) defines
their enforcement; [operations](operations.md) covers safe deployment choices.
ConfigKit strictly decodes application YAML: empty files, unknown fields,
multiple documents, aliases/anchors, and incompatible/null values fail under its
schema rules. Explicit empty strings and numeric zeros remain values. The
nullable retry field preserves null. Application paths are trimmed/cleaned and
the server address is trimmed within ConfigKit's resolver, with native
normalization evidence. Paths remain relative to process cwd, not the application
file's directory. No general environment-variable override layer is installed.
## Explicit Imports And Selected Overlays
Application imports use native root `config.imports` and are enabled during
loading. ConfigKit owns paths/directories/globs, requiredness, destination/item
placement, inheritance, sequence policy, and source-root confinement; consult its
[pinned contract][configkit]. Scriptorium does not widen the selected file's
canonical source root or implement another traversal/merge policy.
`--overlay NAME` passes the name unchanged to ConfigKit. At the selected release,
empty and exact lowercase `default` select none; other names use letters,
digits, underscores, or hyphens and select `overlays/NAME.yml` beneath the main
source root. A missing selected overlay fails. It is not a filesystem-path flag,
inherited stack, or fallback-root mechanism. An active overlay after absent-main
search exhaustion has no independent filesystem root in this application.
Only `serve` has named application override flags, for its HTTP settings.
Native application-scope `--set` records are passed directly to ConfigKit.
Nonconflicting records are supported; duplicate and ancestor/descendant paths
are rejected rather than resolved by order. Configuration commands have no
application-defined source/schema/HTTP selectors or comparison counterparts.
Native comparison selections and supported overrides are independent on each side.
## Framework Source Mapping
A nonempty resolved `promptkit.configuration` becomes an import-enabled
`configkit.File` main input to PromptKit. An empty value leaves its main absent.
The native bundled OpenRouter underlay remains enabled; no application source
list, directory expansion, or local precedence interpreter is installed.
Imports in that external document compose framework definitions using PromptKit's
schema and ConfigKit's native rules. The [maintained entry file](../examples/promptkit.yml)
imports the application's maintained prompt/profile fragments and backend
definitions. Peer conflicts are errors, not filename-order precedence.
Native whole-record replacement and inheritance remain framework-owned.
Application settings do not embed or re-decode framework definitions.
PromptKit captures message-file resources with their defining source context
when constructing the engine. Schema/artifact reads, credential resolution, and
provider work retain native preparation/runtime lifecycles. The server keeps one
engine until restarted; later CLI invocations perform fresh loads.
### Collection Checkout Discovery
The [discovery configuration](../examples/config.discovery.yml) selects
[one framework entry](../examples/discovery/framework.yml) with two optional imports:
```yaml
config:
imports:
- glob: collections/*/collection.yml
- glob: collections/*/collection.yaml
```
Each independently maintained checkout declares its namespace and explicitly
imports its own definitions relative to its entry file. Checkout names do not
determine resource IDs. The [support example](../examples/discovery/collections/support-repo/collection.yml)
imports multiple profiles/prompts and a source-relative message; the
[review example](../examples/discovery/collections/review-repo/collection.yaml)
uses the other spelling. Arbitrary checkout YAML is not loaded implicitly.
Either glob may have no matches. New checkouts become visible on a later
invocation, not through server hot reload. Entries in one discovery document are
peers: conflicting qualified IDs fail instead of relying on glob order.
## Inspection And Credentials
The native `app` scope exposes the actual application result without acquiring
framework definitions or credentials. The `promptkit` scope exposes the captured
framework result selected by the application config/overlay. They are not merged
into one synthetic document. See [CLI inspection](cli.md#application-configuration-inspection)
for operations and independent comparison.
PromptKit owns profiles, namespaces, provider controls, repairs, retries, and
credential resolution. Store credential environment-variable names, not raw
values; supply the selected environment to the process. Native framework
redaction is limited to classified fields and history, not arbitrary sensitive
content. Protect application, prompt, prepared, and generated reports as data.
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md
[configkit]: https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md