Document extraction reference support

docs/troubleshooting.md

@@ -102,6 +102,34 @@ go run ./cmd/notarius run dnd-session \
 - For `config validate`, include `--pipeline` when using `--only`.
 - Confirm the lane ID exists under `pipelines.<id>.artifacts`.
 
+## Reference Binding Failure
+
+Symptoms include:
+
+- `reference slot "..." is not declared`
+- `reference slot "..." is declared by multiple selected lanes`
+- `required reference slot "..." is not bound`
+- `--reference must use slot=path or lane.slot=path`
+- `--without-reference must use slot or lane.slot`
+- `read "...": no such file`
+- `must be UTF-8 text`
+- `is ... bytes, limit ...`
+
+Fix:
+
+- Confirm the selected extractor declares the slot. The implemented
+  `dnd/spells` extractor declares optional `roster` and `glossary` slots.
+- Use `lane.slot=path` when more than one selected lane declares the same slot.
+- Use `--without-reference slot` to remove optional config bindings; do not pass
+  an empty `--reference slot=`.
+- Check whether a path came from config or CLI. Config paths are relative to
+  the config file. CLI reference paths are relative to the current working
+  directory.
+- Ensure the file is readable UTF-8 text and within any byte limit declared by
+  the extractor.
+- If diagnostics are retained, inspect `resolved-pipeline.json`,
+  `resolved-references.json`, and `error.log`.
+
 ## Seriatim Input Validation Failure
 
 Symptoms include `seriatim input`, `parse JSON`, `segments must not be empty`,