From fc81eeb4d1ad4f489d81a25bd1e1d088a28b456b Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Fri, 8 May 2026 09:15:58 -0500
Subject: [PATCH] Add documentation for prompt, profile, schema, and main
 configuration files

---
 docs/config/config-yml.md           | 48 +++++++++++++++++
 docs/config/profile-definitions.md  | 41 +++++++++++++++
 docs/config/prompt-definitions.md   | 73 +++++++++++++++++++++++++
 docs/config/schema-definitions.md   | 82 +++++++++++++++++++++++++++++
 docs/{ => integrations}/narratio.md |  0
 5 files changed, 244 insertions(+)
 create mode 100644 docs/config/config-yml.md
 create mode 100644 docs/config/profile-definitions.md
 create mode 100644 docs/config/prompt-definitions.md
 create mode 100644 docs/config/schema-definitions.md
 rename docs/{ => integrations}/narratio.md (100%)

diff --git a/docs/config/config-yml.md b/docs/config/config-yml.md
new file mode 100644
index 0000000..f245418
--- /dev/null
+++ b/docs/config/config-yml.md
@@ -0,0 +1,48 @@
+# Main `config.yml`
+
+`config.yml` defines application-level defaults used by CLI commands.
+
+By default, Scriptorium looks for `/etc/scriptorium/config.yml`. You can also pass `--config PATH`.
+
+## Complete Example
+
+```yaml
+prompt_dir: ./prompts
+profile_dir: ./profiles
+schema_dir: ./schemas
+
+server:
+  addr: :8080
+
+defaults:
+  render_format: text
+```
+
+## Available Options
+
+- `prompt_dir` (optional): Default directory for prompt definition YAML files.
+- `profile_dir` (optional): Default directory for execution profile YAML files.
+- `schema_dir` (optional): Base directory for JSON schema files used by `json_schema` validation.
+
+### `server`
+
+- `addr` (optional): HTTP server listen address for `scriptorium serve`.
+
+### `defaults`
+
+- `render_format` (optional): Default output format for `scriptorium render`.
+- Allowed values: `text`, `json`.
+
+## Precedence
+
+For run/render/serve settings, precedence is:
+
+1. Explicit CLI flags
+2. `config.yml`
+3. Built-in defaults
+
+## Notes and Rules
+
+- Unknown YAML fields fail to load (strict decoding).
+- This file does not accept API keys.
+- `config.yml` sets directory/server defaults only; prompt/profile content remains in their own files.
diff --git a/docs/config/profile-definitions.md b/docs/config/profile-definitions.md
new file mode 100644
index 0000000..23de3a2
--- /dev/null
+++ b/docs/config/profile-definitions.md
@@ -0,0 +1,41 @@
+# Execution Profile Definitions
+
+Execution Profiles define **how** Scriptorium calls an LLM endpoint.
+
+A profile file is YAML, typically stored under `profiles/`, for example `profiles/local-quality.yaml`.
+
+## Complete Example
+
+```yaml
+id: local-quality
+endpoint: http://localhost:8000/v1
+model: gpt-4.1
+temperature: 0.0
+max_tokens: 1200
+top_p: 1.0
+timeout_seconds: 180
+reasoning_effort: medium
+api_key_env: SCRIPTORIUM_API_KEY
+extra_params:
+  provider: openrouter
+  route: fallback
+```
+
+## Available Options
+
+- `id` (required): Unique profile identifier used by `--profile` or prompt `default_profile`.
+- `endpoint` (required): OpenAI-compatible base URL, usually ending in `/v1`.
+- `model` (required): Model name to request at that endpoint.
+- `temperature` (optional): Sampling temperature. Valid range is `0` to `2`.
+- `max_tokens` (optional): Max completion tokens. Must be `>= 0`.
+- `top_p` (optional): Nucleus sampling parameter. Valid range is `0` to `1`.
+- `timeout_seconds` (optional): Request timeout in seconds. Must be `>= 0`.
+- `reasoning_effort` (optional): Provider/model-specific reasoning level string.
+- `api_key_env` (optional): Environment variable name that holds the API key.
+- `extra_params` (optional): String key/value map for provider-specific parameters.
+
+## Notes and Rules
+
+- Raw API keys are not supported. Do **not** add `api_key` fields.
+- Unknown YAML fields fail to load (strict decoding).
+- If `api_key_env` is set, the environment variable must be present when the run executes.
diff --git a/docs/config/prompt-definitions.md b/docs/config/prompt-definitions.md
new file mode 100644
index 0000000..aa1681c
--- /dev/null
+++ b/docs/config/prompt-definitions.md
@@ -0,0 +1,73 @@
+# Prompt Definition Files
+
+Prompt Definitions define **what** Scriptorium should do.
+
+A prompt file is YAML, typically stored under `prompts/`, for example `prompts/generic.structured_events.yaml`.
+
+## Complete Example
+
+```yaml
+id: generic.structured_events
+version: "1.0.0"
+default_profile: local-quality
+description: Extract events from a transcript into structured JSON.
+
+inputs:
+  - name: transcript
+    required: true
+    content_type: text/markdown
+    description: Source transcript
+  - name: glossary
+    required: false
+    content_type: text/yaml
+    description: Optional glossary context
+
+messages:
+  - role: system
+    content: |
+      You are a structured extraction assistant.
+      Return only JSON.
+  - role: user
+    content_file: ./generic.structured_events.user.md
+
+output:
+  format: json
+  validation_mode: json_schema
+  schema_path: structured_events.schema.json
+  repair_attempts: 1
+```
+
+## Available Options
+
+- `id` (required): Prompt identifier used by `--prompt` / `prompt_id`.
+- `version` (required): Prompt version string.
+- `default_profile` (optional): Execution profile ID used when no explicit profile is provided.
+- `description` (optional): Human-readable description.
+
+### `inputs[]`
+
+- `name` (required): Logical input name referenced in templates via `{{input "name"}}`.
+- `required` (optional): If `true`, run fails when input is missing.
+- `content_type` (optional): Metadata only (not enforced yet).
+- `description` (optional): Human-readable input description.
+
+### `messages[]`
+
+- `role` (required): Message role such as `system` or `user`.
+- `content` (optional): Inline Go-template message body.
+- `content_file` (optional): Path to a template file.
+
+Each message must set **exactly one** of `content` or `content_file`.
+
+### `output`
+
+- `format` (required): One of `text`, `markdown`, `json`.
+- `validation_mode` (required): One of `none`, `basic`, `json`, `json_schema`.
+- `schema_path` (required when `validation_mode: json_schema`): Path to JSON Schema file.
+- `repair_attempts` (required): Number of bounded repair retries (`>= 0`).
+
+## Notes and Rules
+
+- Unknown YAML fields fail to load (strict decoding).
+- `content_file` paths are resolved relative to the prompt YAML file.
+- For `json_schema` validation mode, Scriptorium also sends provider-level structured output requests automatically.
diff --git a/docs/config/schema-definitions.md b/docs/config/schema-definitions.md
new file mode 100644
index 0000000..f314387
--- /dev/null
+++ b/docs/config/schema-definitions.md
@@ -0,0 +1,82 @@
+# JSON Schema Definition Files
+
+Schema definition files describe the expected JSON output contract for prompts that use:
+
+- `output.format: json`
+- `output.validation_mode: json_schema`
+
+Schema files are JSON, typically stored under `schemas/`, for example `schemas/structured_events.schema.json`.
+
+## Complete Example
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/structured-events.schema.json",
+  "title": "Structured Events",
+  "description": "Expected shape for extracted event output",
+  "type": "object",
+  "properties": {
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "High-level session summary"
+    },
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "title": { "type": "string" },
+          "type": {
+            "type": "string",
+            "enum": ["discovery", "combat", "social", "travel", "downtime", "other"]
+          },
+          "notes": { "type": "string" }
+        },
+        "required": ["title", "type"],
+        "additionalProperties": false
+      },
+      "minItems": 0
+    }
+  },
+  "required": ["summary", "events"],
+  "additionalProperties": false,
+  "$defs": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}
+```
+
+## Available Options
+
+Scriptorium does not define custom schema keywords. It expects a valid JSON Schema document and passes it to the validator/provider.
+
+Commonly used JSON Schema options include:
+
+- `$schema`: Draft identifier URI.
+- `$id`: Schema identifier URI.
+- `title`: Human-readable schema title.
+- `description`: Human-readable schema description.
+- `type`: Expected JSON type (`object`, `array`, `string`, etc.).
+- `properties`: Object field definitions.
+- `required`: Required object fields.
+- `additionalProperties`: Whether undeclared fields are allowed.
+- `items`: Array item schema.
+- `enum`: Allowed literal values.
+- `const`: Single allowed literal value.
+- `oneOf`, `anyOf`, `allOf`: Composition rules.
+- `minimum`, `maximum`: Numeric bounds.
+- `minLength`, `maxLength`, `pattern`: String constraints.
+- `minItems`, `maxItems`: Array constraints.
+- `$defs`: Reusable local definitions.
+- `$ref`: Reference to another schema/definition.
+
+## Notes and Rules
+
+- Schema path comes from prompt `output.schema_path` and is resolved relative to `schema_dir`.
+- If schema loading fails for `json_schema` mode, the run fails before the LLM request.
+- Keep schemas strict (`additionalProperties: false`) when you want predictable output shape.
diff --git a/docs/narratio.md b/docs/integrations/narratio.md
similarity index 100%
rename from docs/narratio.md
rename to docs/integrations/narratio.md