Documentation cleanup and bugfixes

README.md

@@ -138,8 +138,6 @@ Starts the HTTP API.
 **Optional Flags:**
 - `--addr`: Listen address (default `:8080`).
 - `--schema-dir`: Base directory for validation schemas.
-- `--model`: Default model override.
-- `--timeout`: Default request timeout.
 
 ## HTTP API
 
@@ -152,6 +150,7 @@ Executes a prompt. No built-in authentication is provided; deploy behind a trust
 {
   "prompt_id": "generic.structured_events",
   "profile_id": "local-quality",
+  "include_raw_output": false,
   "inputs": {
     "transcript": {"type": "file", "uri": "./examples/fixtures/transcript.md"}
   },
@@ -166,11 +165,18 @@ Executes a prompt. No built-in authentication is provided; deploy behind a trust
 }
 ```
 
+`profile_id` is optional. If omitted, Scriptorium uses the prompt's `default_profile`. If neither is available, the run fails.
+
 **Response:**
 Returns a `200 OK` with the generated artifact, validation results, and metadata including the `prompt_id` and the `selected_profile_id`.
 
 **Validation Failures:**
-If the model output fails validation (e.g., invalid JSON), the API returns `200 OK` with `validation.status = "failed"`. The original `raw_model_output` is preserved in the response to allow debugging.
+If the model output fails validation (e.g., invalid JSON), the API returns `200 OK` with `validation.status = "failed"`.
+
+**Raw Output Exposure:**
+- `raw_model_output` is omitted by default.
+- Set `include_raw_output: true` in the request to include it in the response.
+- Raw output is preserved internally in run results regardless of HTTP exposure.
 
 ## Prompt Definition Authoring
 
@@ -186,26 +192,31 @@ default_profile: local-quality
 inputs:
   - name: transcript
     required: true
+    content_type: text/markdown
     description: "The raw session transcript"
   - name: glossary
     required: false
+    content_type: application/yaml
+    description: "Optional glossary terms"
 
-templates:
+messages:
   - role: system
     content: "You are a helpful assistant."
   - role: user
     content_file: messages/extract_events.tmpl
 
-output_format: json
-validation:
+output:
+  format: json
   validation_mode: json_schema
   schema_path: structured_events.schema.json
   repair_attempts: 2
 ```
 
 **Key Features:**
-- **Inline vs File**: Use `content` for short prompts or `content_file` for larger templates.
+- **Inline vs File**: Use `content` for short prompts or `content_file` for larger templates. Exactly one must be set per message.
+- **Path Resolution**: `content_file` paths are resolved relative to the prompt YAML file.
 - **Inputs**: Mark inputs as `required` to ensure the runner fails early if they are missing.
+- **Input Metadata**: `content_type` is currently descriptive metadata and not enforced yet.
 - **Validation**: Support `none`, `basic`, `json`, and `json_schema`.
 - **Repair**: `repair_attempts` enables bounded retries to fix structured output.