159 lines
8.9 KiB
Markdown
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
|