Document chunk plan caching and provenance

docs/cli.md

@@ -9,7 +9,7 @@ For the minimal end-to-end invocation, see the [README](../README.md).
 
 ```text
 notarius help
-notarius run <pipeline-id> --input path/to/source.json [--config path/to/config.yml] [--only lane-a,lane-b] [--output-dir path] [--diagnostics-dir path] [--llm-profile id] [--resume] [--session-id id] [--reference selector=path] [--without-reference selector]
+notarius run <pipeline-id> --input path/to/source.json [--config path/to/config.yml] [--only lane-a,lane-b] [--chunk_cache auto|bypass|refresh] [--output-dir path] [--diagnostics-dir path] [--llm-profile id] [--resume] [--session-id id] [--reference selector=path] [--without-reference selector]
 notarius config validate [--config path/to/config.yml] [--pipeline pipeline-id] [--only lane-a,lane-b]
 notarius pipelines list [--config path/to/config.yml] [--json]
 ```
@@ -31,6 +31,12 @@ Flags:
   comma-separated and must be non-empty.
 - `--resume`: request checkpoint reuse for this invocation. See
   [Operations](operations.md#checkpoints) for prerequisites and reuse behavior.
+- `--chunk_cache auto|bypass|refresh`: select chunk-plan reuse for this
+  invocation. `auto` reuses a valid plan by canonical source digest, `bypass`
+  performs no plan-cache I/O, and `refresh` regenerates and replaces a valid
+  plan only after chunk validation succeeds. See
+  [Configuration](config.md#workspace) for the persistent setting, precedence,
+  and cache-root selection.
 - `--output-dir path`: output root. Defaults to `./notarius-output`.
 - `--diagnostics-dir path`: diagnostics work directory override for this
   invocation. It does not change the workspace directory.
@@ -125,6 +131,24 @@ go run ./cmd/notarius run dnd-session \
   --resume
 ```
 
+Use `refresh` when intentionally replacing the cached plan for the same source:
+
+```sh
+go run ./cmd/notarius run dnd-session \
+  --config examples/dnd-spells.config.yml \
+  --input examples/seriatim-minimal-transcript.json \
+  --chunk_cache refresh
+```
+
+Use `bypass` for a one-off run that must not inspect or create plan-cache state:
+
+```sh
+go run ./cmd/notarius run dnd-session \
+  --config examples/dnd-spells.config.yml \
+  --input examples/seriatim-minimal-transcript.json \
+  --chunk_cache bypass
+```
+
 For checkpoint behavior, durable output, diagnostics, retention, and failure
 inspection, see [Operations](operations.md).