Documentation cleanup and bugfixes

architecture.md

@@ -50,7 +50,7 @@ The `Runner.Run` flow executes the following steps:
    - Built-in application defaults.
 5. **Resolve Artifacts**: Load all named input artifacts defined in the request.
 6. **Render Prompt**: Apply template variables and input artifacts to the prompt templates.
-7. **Call LLM**: Execute the generation request using the resolved `ExecutionTarget`.
+7. **Call LLM**: Execute the generation request using the resolved execution target (effective runtime settings).
 8. **Validate/Repair**: 
    - Validate the model output against the output contract.
    - If structured validation fails and `repair_attempts > 0`, perform bounded repair and re-validate.
@@ -86,13 +86,18 @@ Key domain types:
 
 ### CLI
 - `run`: Executes a prompt. Uses flags like `--prompt`, `--profile`, `--input`, and various runtime overrides (e.g., `--model`, `--temperature`).
-- `serve`: Starts the HTTP API.
+- `serve`: Starts the HTTP API using infrastructure-only flags (`--addr`, `--prompt-dir`, `--profile-dir`, `--schema-dir`). It does not introduce a server-level model/runtime precedence layer.
 
 ### HTTP API
 - `POST /v1/runs`: Accepts `RunRequest` JSON and returns `RunResponse` JSON. No built-in auth.
+- Request may include runtime overrides under `model` and an `include_raw_output` boolean.
+- `raw_model_output` is exposed only when explicitly requested with `include_raw_output=true`.
 
 ### YAML Shapes
-- **Prompt YAML**: Includes `id`, `version`, `default_profile`, `inputs`, `templates`, and `validation`.
+- **Prompt YAML**: Includes `id`, `version`, optional `default_profile`, `inputs`, `messages`, and `output`.
+  - Inputs support `name`, `required`, optional `content_type`, and `description`.
+  - Messages require `role` and exactly one of `content` or `content_file`.
+  - `content_file` resolves relative to the prompt YAML location.
 - **Profile YAML**: Includes `id`, `endpoint`, `model`, generation params, and `api_key_env`.
 
 ## 7. Guardrails