Finish Scriptorium runtime documentation

docs/troubleshooting.md

@@ -34,7 +34,7 @@ Symptoms include:
 
 Fix:
 
-- Use `version: 1`.
+- Use `version: 2`.
 - Remove unknown YAML fields.
 - Validate with:
 
@@ -157,21 +157,31 @@ Fix:
   whitespace.
 - `end` must be greater than or equal to `start`.
 
-## Missing LLM Base URL Or Model
+## Scriptorium Profile Source Failure
 
 Symptoms include:
 
-- `LLM profile "default" base URL must not be empty`
-- `LLM profile "default" model must not be empty`
-- `base URL must be valid`
+- `scriptorium profile_dir and profile_file are mutually exclusive`
+- `scriptorium.profile_dir must not be empty when set`
+- `scriptorium.profile_file must not be empty when set`
+- `profile load`
+- `profile not found`
 
 Fix:
 
-- Set `base_url` and `model` in `llm_profiles.default`.
-- Or set `NOTARIUS_LLM_DEFAULT_BASE_URL` and
-  `NOTARIUS_LLM_DEFAULT_MODEL`.
-- If a profile needs authentication, set `api_key_env` in YAML or set
-  `NOTARIUS_LLM_DEFAULT_API_KEY`.
+- Configure at most one of `scriptorium.profile_dir` or
+  `scriptorium.profile_file`.
+- Confirm the selected Scriptorium profile ID exists in the configured profile
+  source or Scriptorium built-in profiles.
+- If using `--llm-profile`, pass a Scriptorium profile ID, not a removed
+  Notarius profile ID.
+- Validate the config and selected pipeline:
+
+```sh
+go run ./cmd/notarius config validate \
+  --config path/to/config.yml \
+  --pipeline dnd-session
+```
 
 ## LLM Profile Override Failure
 
@@ -183,38 +193,49 @@ notarius: LLM profile override "..." is not configured
 
 Fix:
 
-- Add the profile under `llm_profiles`.
-- Or use an existing profile ID with `--llm-profile`.
+- Add the profile to the configured Scriptorium profile source.
+- Or use an existing Scriptorium profile ID with `--llm-profile`.
 
-Current runs require exactly one distinct effective LLM profile. If a pipeline
-uses several profiles, run with `--llm-profile <id>` or align the bindings in
-configuration.
+Use `--llm-profile <id>` when one run should force every LLM-backed binding to
+the same Scriptorium profile.
 
-## Provider HTTP Or Response Failure
+## Missing API Key Environment Variable
 
 Symptoms include:
 
-- `provider request failed`
-- `provider returned status 400`
-- `provider returned status 403`
-- `provider response missing choices`
-- `provider response assistant message content is not valid JSON`
+- `api_key_env`
+- `unset environment variable`
+- provider authentication failures after selecting a profile that needs a key
+
+Fix:
+
+- Check the selected Scriptorium profile's `api_key_env` field.
+- Set that environment variable before running Notarius.
+- Do not put raw API keys in Notarius config or file-backed Scriptorium
+  profiles.
+
+## Prompt Or Structured Output Failure
+
+Symptoms include:
+
+- `prompt not found`
+- `prompt render`
+- `schema`
+- `validation`
 - `decode structured output`
 
 Fix:
 
-- Confirm the `base_url` points to an OpenAI-compatible endpoint root. Notarius
-  posts to `<base_url>/chat/completions`.
-- Check `model` and provider credentials.
-- Inspect the retained diagnostics `error.log`.
-- For 400 and 403 responses, fix the request configuration or credentials.
-- For 429 and 5xx responses, the client retries according to `max_retries`; if
-  the failure persists, inspect the provider response and adjust capacity,
-  credentials, or model settings.
-- The assistant message content must decode as JSON matching the extractor's
-  structured response schema.
-
-Provider error messages are redacted for configured API key values.
+- Ensure production modules register their embedded Scriptorium prompt and
+  schema assets.
+- If the error names a profile, select a Scriptorium profile that is available
+  through the configured profile source or built-in catalog.
+- If the error names generated output validation, retry with a model that
+  follows JSON schema instructions reliably.
+- Inspect retained diagnostics `error.log`, `resolved-pipeline.json`, and
+  `run-manifest.json` when available. Prompt text, source text, reference
+  content, raw schema JSON, and secrets are not written to default diagnostics.
+- Provider errors are redacted for bearer tokens and configured API key values.
 
 ## Scene Chunking Failure
 
@@ -234,8 +255,8 @@ Fix:
 
 - Validate the pipeline configuration and confirm the input module provides a
   transcript source when using `chunk: dnd/scenes`.
-- Confirm the LLM profile has a working OpenAI-compatible `base_url`, `model`,
-  and credentials.
+- Confirm the selected Scriptorium profile has a working endpoint, model, and
+  credentials.
 - Inspect retained diagnostics for the run error and resolved pipeline.
 - If the error names malformed structured output, retry with a model that
   follows structured response schemas reliably.
@@ -244,6 +265,16 @@ Fix:
 - Scene boundaries must use exact source-unit IDs, cover the full source
   document, be contiguous, and not overlap.
 
+## Session ID
+
+Symptom: external logs or provider traces cannot be correlated with a Notarius
+run.
+
+Fix:
+
+- Pass `--session-id <id>` to `notarius run`.
+- Use a stable, non-secret identifier from the external orchestrator.
+
 ## Output Write Failure
 
 Symptoms include: