Document completed workspace behavior

docs/troubleshooting.md

@@ -280,6 +280,50 @@ Fix:
 - Pass `--session-id <id>` to `notarius run`.
 - Use a stable, non-secret identifier from the external orchestrator.
 
+## Resume Or Checkpoint Reuse Failure
+
+Symptoms include:
+
+- `--resume requires workspace.resume.enabled: true`
+- `checkpoint artifact is missing`
+- `checkpoint workspace schema version`
+- `checkpoint dependency fingerprints do not match`
+- a resumed run executes work instead of reusing a checkpoint
+
+Fix:
+
+- Set both `workspace.directory` and `workspace.resume.enabled: true`.
+- Use `--resume`; plain `notarius run` executes normally and refreshes
+  checkpoints.
+- Confirm the current run uses the same input bytes, resolved pipeline, selected
+  lanes, runtime LLM profile override, and materialized references as the run
+  that wrote the checkpoint.
+- Inspect retained diagnostics `checkpoint-events.json` to see which workflow
+  steps were reused or executed.
+- If a checkpoint payload is missing or corrupt, rerun without relying on that
+  checkpoint. Notarius executes invalidated steps normally and writes fresh
+  checkpoints when checkpointing remains enabled.
+
+Checkpoint files can contain source text, intermediate outputs, rejected
+outputs, metadata, and warnings. Protect the workspace directory accordingly.
+
+## Debug Output Missing Or Too Verbose
+
+Symptoms:
+
+- no files appear under `<workspace.directory>/debug/<run-id>/`;
+- debug files contain more source, reference, prompt, or model-output material
+  than expected.
+
+Fix:
+
+- Set both `workspace.directory` and `workspace.debug.enabled: true`.
+- Confirm you are inspecting the current run ID. Debug output is per invocation
+  and is not used for resume.
+- Disable `workspace.debug.enabled` after the inspection run. Debug output may
+  contain sensitive source material, reference material, prompt inputs, model
+  outputs, and validation payloads.
+
 ## Output Write Failure
 
 Symptoms include: