Finalize artifact workflow documentation

docs/troubleshooting.md

@@ -355,6 +355,103 @@ successful stages are then marked stale normally.
 
 Relevant reference: [Operations: Extraction Workflow](./operations.md#extraction-workflow).
 
+## Analysis artifact evidence is not current
+
+Symptom:
+
+- ordinary continuation or `session plan` schedules one or more configured
+  artifacts even though a canonical output file exists; or
+- publish reports a configured artifact source unavailable.
+
+Likely causes:
+
+- the per-artifact record is stale, missing, failed, unselected, malformed, or
+  from the legacy aggregate-only manifest contract;
+- a configured prompt/profile, dependency, input identity, output path, or
+  effective variable changed; or
+- the recorded output is missing, unsafe, empty, or has a size/checksum that no
+  longer matches its manifest evidence.
+
+Diagnostics:
+
+```bash
+narratio session status 2026-04-04
+narratio session artifacts 2026-04-04
+narratio session plan 2026-04-04 --from analyze --through analyze
+```
+
+Safe fix:
+
+- investigate unexpected path or checksum changes as possible tampering;
+- otherwise let the selected analyze work rerun, or explicitly regenerate only
+  the affected targets; and
+- never edit the fingerprint/checksum in the manifest or copy an old file into
+  the canonical path as a substitute for current evidence.
+
+```bash
+narratio analyze 2026-04-04 --artifacts session_recap
+```
+
+Relevant references: [Operations: Artifact Selection](./operations.md#artifact-selection)
+and [Artifact Internals](./internal/artifacts.md#resolution-rules).
+
+## Legacy aggregate analysis requires regeneration
+
+Symptom:
+
+- a manifest from an older Narratio version reports aggregate analyze success
+  and the old files are present, but configured artifact sources remain
+  unavailable.
+
+Likely cause:
+
+- the manifest has no supported per-artifact analyze state. Aggregate output
+  lists do not establish current configured-artifact authority.
+
+Safe fix:
+
+- regenerate the required artifacts. A partial selection makes only its
+  targets and prerequisites eligible for current state; unselected legacy
+  files intentionally remain unavailable. Run full analysis later when every
+  enabled configured artifact must become current.
+
+```bash
+narratio analyze 2026-04-04 --artifacts session_recap
+narratio analyze 2026-04-04
+```
+
+After current records exist, inspect them and publish explicitly. Do not delete
+the legacy files merely to influence selection; availability is manifest-owned.
+
+Relevant references: [Operations: Stage Execution and Continuation Behavior](./operations.md#stage-execution-and-continuation-behavior)
+and [Manifest Internals](./internal/manifest.md#analyze-owned-artifact-state).
+
+## Scriptorium private input changed without a rerun
+
+Symptom:
+
+- a prompt, profile, imported configuration file, executable, or other input
+  loaded privately by Scriptorium changed, but Narratio still considers an
+  artifact current.
+
+Likely cause:
+
+- analysis fingerprints cover Narratio-observable semantic identities, not
+  executable contents or arbitrary files and transitive configuration that
+  Scriptorium loads behind its configured paths and identifiers.
+
+Safe fix:
+
+- explicitly force the affected target after changing an unobserved private
+  input. Force applies to explicit targets; current prerequisites remain
+  reusable unless selected themselves.
+
+```bash
+narratio analyze 2026-04-04 --artifacts session_recap
+```
+
+Relevant reference: [Analyze Internals](./internal/stage-analyze.md#invariants).
+
 ## Previous-session artifact input missing
 
 Symptom: