Add documentation for prompt, profile, schema, and main configuration files

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.