Document application config support

README.md

@@ -38,7 +38,25 @@ Callers can explicitly provide a `profile_id` to override the prompt's `default_
 
 ## Precedence
 
-When resolving runtime settings, Scriptorium follows this precedence model (highest to lowest):
+Scriptorium uses two precedence layers:
+
+### Application Configuration Precedence
+
+For application-level adapter settings (for example prompt/profile/schema directories, server address, and render output default), precedence is:
+
+1. **CLI Flags**
+2. **`config.yml`**
+3. **Built-in application defaults**
+
+Application config loading behavior:
+- Default config path: `/etc/scriptorium/config.yml`
+- Override path: `--config <PATH>` (supported by `run`, `render`, and `serve`)
+- If `--config` is provided, the file must exist and be valid.
+- If `--config` is omitted, missing `/etc/scriptorium/config.yml` is allowed.
+
+### Runtime Model Precedence
+
+When resolving runtime model settings, Scriptorium follows this precedence model (highest to lowest):
 
 1. **Runtime Overrides**: Provided via CLI flags or HTTP request `model` object.
 2. **Execution Profile**: Settings defined in the selected profile.
@@ -65,17 +83,32 @@ Available CLI commands:
 - `scriptorium render`
 - `scriptorium serve`
 
+All commands accept `--config <PATH>`.
+
+`prompt_dir` and `profile_dir` may be supplied by CLI flags or `config.yml`:
+- `--prompt-dir` or `config.yml` `prompt_dir`
+- `--profile-dir` or `config.yml` `profile_dir`
+
+`schema_dir` and `serve` `addr` may also be supplied by `config.yml` where applicable:
+- `--schema-dir` or `config.yml` `schema_dir`
+- `--addr` or `config.yml` `server.addr`
+
 ### `scriptorium run`
 
 Runs a single prompt execution.
 
 **Required Flags:**
-- `--prompt-dir`: Directory containing prompt YAML files.
-- `--profile-dir`: Directory containing profile YAML files.
 - `--prompt`: The prompt ID to execute.
 - `--input`: Input mapping `name=path` (repeatable).
 
+**Required Effective Settings:**
+- Prompt directory: `--prompt-dir` or `config.yml` `prompt_dir`
+- Profile directory: `--profile-dir` or `config.yml` `profile_dir`
+
 **Optional Flags:**
+- `--config`: Application config file path. Default discovery path is `/etc/scriptorium/config.yml`.
+- `--prompt-dir`: Override prompt directory from config.
+- `--profile-dir`: Override profile directory from config.
 - `--profile`: Override the prompt's default profile.
 - `--var`: Template variable `name=value` (repeatable).
 - `--out`: Write output to a file instead of stdout.
@@ -90,7 +123,14 @@ Runs a single prompt execution.
 
 **Examples:**
 
-Using the prompt's `default_profile`:
+Using `config.yml` for prompt/profile directories:
+```bash
+scriptorium run \
+  --prompt generic.markdown_summary \
+  --input transcript=./examples/fixtures/transcript.md
+```
+
+Overriding config directories explicitly:
 ```bash
 scriptorium run \
   --prompt-dir ./prompts \
@@ -154,12 +194,17 @@ Prepares and renders a prompt without calling the LLM.
 It may include `api_key_env` names where relevant.
 
 **Required Flags:**
-- `--prompt-dir`: Directory containing prompt YAML files.
-- `--profile-dir`: Directory containing profile YAML files.
 - `--prompt`: The prompt ID to render.
 - `--input`: Input mapping `name=path` (repeatable).
 
+**Required Effective Settings:**
+- Prompt directory: `--prompt-dir` or `config.yml` `prompt_dir`
+- Profile directory: `--profile-dir` or `config.yml` `profile_dir`
+
 **Optional Flags:**
+- `--config`: Application config file path. Default discovery path is `/etc/scriptorium/config.yml`.
+- `--prompt-dir`: Override prompt directory from config.
+- `--profile-dir`: Override profile directory from config.
 - `--profile`: Override the prompt's default profile.
 - `--var`: Template variable `name=value` (repeatable).
 - `--out`: Write output to a file instead of stdout.
@@ -180,7 +225,22 @@ Render formatting is modular; additional output formats can be added later witho
 
 **Examples:**
 
-Default text output:
+Default text output using `config.yml` directories:
+```bash
+scriptorium render \
+  --prompt generic.markdown_summary \
+  --input transcript=./examples/fixtures/transcript.md
+```
+
+Explicit config path:
+```bash
+scriptorium render \
+  --config ./examples/config.yml \
+  --prompt generic.markdown_summary \
+  --input transcript=./examples/fixtures/transcript.md
+```
+
+Explicit directory overrides:
 ```bash
 scriptorium render \
   --prompt-dir ./prompts \
@@ -248,14 +308,30 @@ scriptorium render \
 
 Starts the HTTP API.
 
-**Required Flags:**
-- `--prompt-dir`: Directory containing prompt YAML files.
-- `--profile-dir`: Directory containing profile YAML files.
+**Required Effective Settings:**
+- Prompt directory: `--prompt-dir` or `config.yml` `prompt_dir`
+- Profile directory: `--profile-dir` or `config.yml` `profile_dir`
 
 **Optional Flags:**
+- `--config`: Application config file path. Default discovery path is `/etc/scriptorium/config.yml`.
 - `--addr`: Listen address (default `:8080`).
 - `--schema-dir`: Base directory for validation schemas.
 
+**Examples:**
+
+Using `config.yml`:
+```bash
+scriptorium serve
+```
+
+Overriding config for local use:
+```bash
+scriptorium serve \
+  --prompt-dir ./prompts \
+  --profile-dir ./profiles \
+  --addr :9090
+```
+
 ## HTTP API
 
 ### `POST /v1/runs`

architecture.md

@@ -28,6 +28,7 @@ Scriptorium uses a ports-and-adapters architecture to decouple the core executio
 - `cmd/scriptorium`: Binary entrypoint for CLI and HTTP server.
 - `internal/domain`: Core domain contracts, including `PromptDefinition`, `ExecutionProfile`, `PreparedRun`, `RunResult`, and related metadata.
 - `internal/usecase`: `Runner` use case logic, including prompt preparation, profile selection, runtime override resolution, full run execution, validation, and bounded repair.
+- `internal/config`: Application-level config model/loader for adapter settings (for example prompt/profile/schema directories, server address, and render format default).
 - `internal/promptdef`: Repository for loading and validating Prompt Definitions from the filesystem.
 - `internal/profile`: Repository for loading Execution Profiles from the filesystem.
 - `internal/artifact`: Input artifact resolution (`inline`, `file`).
@@ -40,6 +41,28 @@ Scriptorium uses a ports-and-adapters architecture to decouple the core executio
 
 Exact package names may evolve, but the architectural boundaries should remain stable.
 
+### Application Configuration
+
+`config.yml` is adapter/application setup, not domain logic.
+
+Application config is intended for application-level settings such as:
+- `prompt_dir`
+- `profile_dir`
+- `schema_dir`
+- `server.addr`
+- `defaults.render_format`
+
+Application config precedence is:
+1. CLI flags
+2. `config.yml`
+3. Built-in application defaults
+
+Runtime model settings are intentionally separate:
+- Execution profiles and runtime overrides continue to own endpoint/model/runtime behavior.
+- `config.yml` does not replace execution profiles.
+
+The core use case (`Runner.Prepare`/`Runner.Run`) does not need to know whether adapter-level settings came from CLI flags or `config.yml`; it receives resolved dependencies and requests from adapters.
+
 ## 3. Core Execution Model
 
 Scriptorium has two closely related execution paths:
@@ -457,4 +480,4 @@ Future work should remain grounded in the current architecture:
 - **Profiles**: Support more granular profile versioning and environment-specific profiles.
 - **HTTP**: Add an HTTP prepare/render endpoint if Narratio or another caller needs it.
 
-Future render formats should plug into the formatter layer and should not require changes to the usecase layer.
+Future render formats should plug into the formatter layer and should not require changes to the usecase layer.

examples/config.yml

@@ -0,0 +1,9 @@
+prompt_dir: ./prompts
+profile_dir: ./profiles
+schema_dir: ./schemas
+
+server:
+  addr: :8080
+
+defaults:
+  render_format: text