# 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