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`