Document Tomorrow generated-text workflow

docs/troubleshooting.md

@@ -185,6 +185,52 @@ prompt, profile, model configuration, or validation issue.
 Relevant docs: [Operations guide](operations.md),
 [Scriptorium integration](integrations/scriptorium.md).
 
+## Generated Text Validation Fails
+
+Symptom: Tomorrow or Hourly generation fails with generated-text decode,
+unknown-field, required-field, or multiple-JSON-values context.
+
+Likely cause: Scriptorium wrote structured JSON that does not match the
+GeneratedText contract for the selected report.
+
+Diagnostic:
+
+```sh
+weatherreporter inspect metadata RUN_ID
+```
+
+Then inspect the generated-text raw path recorded in metadata, if present.
+
+Safe fix: update the Scriptorium prompt or schema configuration so the prompt
+writes the expected structured JSON for the report.
+
+Relevant docs: [Operations guide](operations.md),
+[Generated Text internals](internal/generatedtext.md),
+[Scriptorium integration](integrations/scriptorium.md).
+
+## Template Rendering Fails
+
+Symptom: Tomorrow or Hourly generation fails with report template parsing or
+execution context after generated text validation succeeds.
+
+Likely cause: an embedded template references a missing context field or
+receives a value shape that does not match its typed render context.
+
+Diagnostic:
+
+```sh
+weatherreporter inspect metadata RUN_ID
+```
+
+If metadata records generated-text and render-context paths, inspect those
+artifacts along with the template named by the report definition.
+
+Safe fix: update the embedded template or render-context builder so the
+template uses the implemented typed context.
+
+Relevant docs: [Report Templates](templates.md),
+[Report Template internals](internal/reporttemplate.md).
+
 ## Batch Command Returns Nonzero
 
 Symptom: `run morning` or `run evening` returns nonzero.