Clarify user and integration documentation contracts

docs/troubleshooting.md

@@ -24,6 +24,8 @@ Safe fix:
 
 - pass explicit `--config`, `--campaign` or `--campaign-file`, and `--session`.
 
+Relevant reference: [Configuration discovery](./config.md#discovery-and-selection).
+
 ## Session template placeholders rejected
 
 Symptom:
@@ -44,6 +46,8 @@ Safe fix:
 
 - generate concrete session YAML with `narratio session init`.
 
+Relevant reference: [Operations: Session Initialization](./operations.md#session-initialization).
+
 ## Strict decode or schema validation failure
 
 Symptom:
@@ -64,6 +68,8 @@ Safe fix:
 
 - align config with [docs/config.md](./config.md) and maintained files under `examples/`.
 
+Relevant reference: [Configuration](./config.md).
+
 ## Audio mode conflict
 
 Symptom:
@@ -74,10 +80,18 @@ Likely cause:
 
 - configured both local and S3 session audio inputs.
 
+Diagnostics:
+
+```bash
+narratio session validate 2026-04-04
+```
+
 Safe fix:
 
 - use local mode (`audio_dir` or `audio_files`) or S3 mode (`audio_s3.prefix`), not both.
 
+Relevant reference: [Session configuration](./config.md#session).
+
 ## `--artifacts` selection error
 
 Symptom:
@@ -90,10 +104,18 @@ Likely causes:
 - empty list entry (for example trailing comma);
 - `run-stage` used with non-`analyze`/`publish` target.
 
+Diagnostics:
+
+```bash
+narratio session artifacts 2026-04-04
+```
+
 Safe fix:
 
 - provide only configured keys and use `--artifacts` with supported commands/stages.
 
+Relevant reference: [CLI artifact selection](./cli.md).
+
 ## Previous-session artifact input missing
 
 Symptom:
@@ -124,6 +146,8 @@ or rerun prepare after correcting session config:
 narratio run-stage prepare 2026-04-04 --force
 ```
 
+Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow).
+
 ## Session lock conflict (`.lock`)
 
 Symptom:
@@ -147,6 +171,8 @@ Safe fix:
 - wait for active process completion;
 - remove stale lock only after confirming no live process owns it.
 
+Relevant reference: [Operations: Local State Layout](./operations.md#local-state-layout).
+
 ## Restore conflict without `--force`
 
 Symptom:
@@ -168,6 +194,8 @@ Safe fix:
 - review conflicts;
 - rerun with `--force` only when remote state should overwrite local.
 
+Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow).
+
 ## Restore current-state discovery failure
 
 Symptom:
@@ -191,6 +219,8 @@ Safe fix:
 - resolve storage/auth issue;
 - republish from healthy local state if current pointer is missing.
 
+Relevant reference: [Operations: Publish Workflow](./operations.md#publish-workflow).
+
 ## Publish output failure
 
 Symptom:
@@ -217,6 +247,8 @@ Safe fix:
 - correct publish source/destination rules;
 - retry after storage failure is resolved.
 
+Relevant reference: [Publish configuration](./config.md#publish-configuration-summary).
+
 ## Render markdown source missing
 
 Symptom:
@@ -232,7 +264,6 @@ Diagnostics:
 
 ```bash
 narratio session status 2026-04-04
-narratio run-stage render 2026-04-04 --force
 ```
 
 Safe fix:
@@ -244,6 +275,8 @@ narratio run-stage render 2026-04-04 --force
 narratio run-stage analyze 2026-04-04 --force
 ```
 
+Relevant reference: [Operations: Stage Execution](./operations.md#stage-execution-and-continuation-behavior).
+
 ## Secrets or storage credential failure
 
 Symptom:
@@ -269,6 +302,8 @@ Safe fix:
 - provide required env vars;
 - keep secret values out of YAML.
 
+Relevant reference: [Secrets](./config.md#secrets-handling).
+
 ## S3 audio prepare failure
 
 Symptom:
@@ -284,7 +319,7 @@ Likely causes:
 Diagnostics:
 
 ```bash
-narratio run-stage prepare 2026-04-04 --force
+narratio session validate 2026-04-04
 ```
 
 Safe fix:
@@ -292,6 +327,8 @@ Safe fix:
 - verify prefix contents and storage access;
 - keep session audio mode consistent.
 
+Relevant reference: [Operations](./operations.md).
+
 ## References
 
 - [docs/cli.md](./cli.md)