Document chunk plan caching and provenance

docs/config.md

@@ -48,6 +48,8 @@ Built-in defaults:
 - `workspace.diagnostics.enabled`: `true`
 - `workspace.resume.enabled`: `false`
 - `workspace.debug.enabled`: `false`
+- `workspace.chunk_cache.mode`: `auto`
+- `workspace.chunk_cache.directory`: unset
 
 No pipelines are built in. A run requires a configured pipeline.
 
@@ -97,6 +99,8 @@ These environment variables are applied after the config file:
 - `NOTARIUS_WORKSPACE_RESUME_ENABLED`: boolean resume checkpointing
   enablement.
 - `NOTARIUS_WORKSPACE_DEBUG_ENABLED`: boolean debug artifact enablement.
+- `NOTARIUS_WORKSPACE_CHUNK_CACHE_MODE`: chunk-plan cache mode.
+- `NOTARIUS_WORKSPACE_CHUNK_CACHE_DIR`: chunk-plan cache root.
 - `NOTARIUS_WORK_DIR`: deprecated diagnostics work directory compatibility
   override.
 - `NOTARIUS_DIAGNOSTICS_RETENTION`: deprecated diagnostics retention
@@ -344,11 +348,35 @@ casts still must be present in the source transcript.
 - `directory`: optional workspace root for Notarius-owned local state.
 - `resume.enabled`: boolean resume checkpointing setting.
 - `debug.enabled`: boolean debug artifact setting.
+- `chunk_cache.mode`: persistent chunk-plan cache mode: `auto`, `bypass`, or
+  `refresh`. The default is `auto`.
+- `chunk_cache.directory`: optional chunk-plan cache root. This value is the
+  root itself; Notarius does not append `chunk-plans` to it.
 - `diagnostics`: optional diagnostics settings defined below.
 
-`workspace.resume.enabled` and `workspace.debug.enabled` are independent.
-Enabling one does not enable the other. For directory layout, state lifecycle,
-permissions, and sensitive content, see [Operations](operations.md).
+`workspace.resume.enabled`, `workspace.debug.enabled`, and
+`workspace.chunk_cache` are independent. `workspace.directory` does not affect
+chunk-plan placement. For directory layout, state lifecycle, permissions, and
+sensitive content, see [Operations](operations.md).
+
+`chunk_cache.mode` accepts only `auto`, `bypass`, and `refresh`. In `auto`, a
+valid source-addressed plan is reused and a missing or invalid record is
+regenerated and published after chunk validation. `bypass` neither reads nor
+writes plan-cache state. `refresh` always generates a new plan and publishes it
+only after validation succeeds.
+
+Configuration values are applied in file then environment order; an explicit
+`--chunk_cache` CLI value has highest precedence for the mode. The cache root
+is selected from environment, file, then the per-user default; there is no CLI
+root override. Every supplied value is parsed strictly even when a higher
+precedence value wins, so malformed configuration is still an error.
+
+When `chunk_cache.directory` is unset, the root is
+`<os.UserCacheDir>/notarius/chunk-plans`. On Unix this is ordinarily
+`$XDG_CACHE_HOME/notarius/chunk-plans` when `XDG_CACHE_HOME` is an absolute
+path, or `$HOME/.cache/notarius/chunk-plans` when it is unset. A relative
+`XDG_CACHE_HOME` is rejected by `os.UserCacheDir`; Notarius reports that as a
+configuration error and does not fall back to another directory.
 
 ## Diagnostics
 
@@ -390,6 +418,7 @@ Configuration validation checks:
 - supported stage-worker keys and an effective extract worker count in the
   inclusive range `1..concurrency.total_llm`;
 - supported diagnostics retention and non-empty work directory;
+- a supported chunk-cache mode and a chunk-cache directory without NUL bytes;
 - stale removed fields such as `llm_profiles`.
 
 Pipeline resolution additionally checks: