Files
scriptorium/docs/config.md

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.