8.9 KiB
Configuration Reference
This document owns Scriptorium's application settings, discovery, and source selection. CLI syntax and the HTTP API have separate owners. Framework definitions and execution semantics belong to the pinned PromptKit v0.23.3 formats; ConfigKit v1.2.1 owns native composition and inspection.
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, including full settings, application imports, framework fragment composition, collection checkout discovery, and framework inheritance.
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 defines their enforcement; operations 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. 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 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 selects one framework entry with two optional imports:
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 imports multiple profiles/prompts and a source-relative message; the review example 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
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.