Document raw pipeline completion

docs/troubleshooting.md

@@ -200,7 +200,8 @@ Fix:
 - Or use an existing Scriptorium profile ID with `--llm-profile`.
 
 Use `--llm-profile <id>` when one run should force every LLM-backed binding to
-the same Scriptorium profile.
+the same Scriptorium profile. The override applies to effective chunk, extract,
+merge, and normalize bindings.
 
 ## Missing API Key Environment Variable
 
@@ -285,17 +286,58 @@ Symptoms include:
 - `create output directory`
 - `write output file`
 - `output file name must`
+- `unsupported media type`
+- `invalid JSON`
 
 Fix:
 
 - Ensure `--output-dir` points to a directory path or a path that can be
   created.
 - Check filesystem permissions and available disk space.
+- The production JSON output encoder writes lane payloads under `lanes/` and
+  accepts only valid `application/json` normalized outputs. If an error names an
+  unsupported media type or invalid JSON, inspect the lane's merge and normalize
+  module output.
 - If diagnostics were retained, inspect `run-report.json`, `run-manifest.json`,
   and `error.log`.
 
 The CLI rejects unsafe logical output paths before writing files.
 
+## Raw Output Rejection
+
+Symptoms include a successful run with:
+
+- `validation_status` set to `rejected`;
+- non-empty `rejected.json`;
+- `rejected_outputs` entries in `manifest.json`.
+
+Explanation and fixes:
+
+- Validator rejection is a non-fatal run outcome. Rejected module outputs do not
+  pass to the next pipeline stage.
+- Check `rejected.json` for the stage, lane, module, chunk, validator, reason,
+  message, and attempt count.
+- Increase a module binding's `retries` only when re-running the same module
+  input can reasonably produce an acceptable output.
+- If rejection is deterministic, fix the source input, module configuration, or
+  validator configuration rather than adding retries.
+
+## Retry Exhaustion
+
+Symptoms include:
+
+- errors containing `failed after ... attempt(s)`;
+- rejected output records with `attempt_count` greater than `1`.
+
+Fix:
+
+- `retries` is the number of extra attempts after the first attempt for chunk,
+  extract, merge, and normalize bindings.
+- Framework-level errors after the last attempt fail the run.
+- Validator rejections after the last attempt are recorded as rejected outputs.
+- Check retained `error.log`, `run-manifest.json`, and `rejected.json` for the
+  operation, module key, lane, chunk, and attempt count.
+
 ## Diagnostics Directory Surprise
 
 Symptom: the diagnostics directory is missing after a successful run.