Document ordered pipeline operations and retire sequential examples

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] [--chunk_cache auto|bypass|refresh] [--output-dir path] [--resume] [--debug [--debug-dir path]] [--llm-profile id] [--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] [--resume] [--recompute-step step-id] [--debug [--debug-dir path]] [--llm-profile id] [--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]
 ```
@@ -28,11 +28,17 @@ Flags:
 - `--config path`: config file path. If omitted, Notarius uses the discovery
   rules in [Configuration](config.md#discovery).
 - `--only lane-a,lane-b`: run only the named artifact lanes. Values are
-  comma-separated and must be non-empty.
+  comma-separated and must be non-empty. This retains its existing behavior for
+  implicit single-step pipelines; explicit multi-step pipelines reject it
+  rather than inferring dependency closure.
 - `--resume`: request checkpoint reuse for this invocation. Checkpoint recording
   must be enabled in configuration. See
   [Operations](operations.md#checkpoint-cache) for prerequisites and reuse
   behavior.
+- `--recompute-step step-id`: with `--resume` and checkpoint recording enabled,
+  force the named ordered step and every transitive dependent lane to execute.
+  Compatible required predecessors and unrelated lanes remain reusable. The
+  value must identify an explicit step; it cannot be combined with `--only`.
 - `--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
@@ -58,8 +64,10 @@ rejected output counts, and the output directory. A debug-enabled run also
 prints `debug=<bundle-path>`. If the run completes with warnings, the warning
 count is printed to stderr.
 
-Reference flags are resolved against selected chunk, extractor, merger, and
-normalizer targets before the run starts. Flat slot names are accepted only
+Reference flags are external file bindings resolved against selected chunk,
+extractor, merger, and normalizer targets before the run starts. Generated
+artifact bindings are configured in ordered steps and cannot be introduced by a
+CLI path flag. Flat slot names are accepted only
 when exactly one selected target declares that slot. For configured reference
 bindings, precedence, path resolution, and validation, see
 [Configuration](config.md#pipelines).
@@ -94,30 +102,21 @@ go run ./cmd/notarius run dnd-session \
   --reference spells.extract.glossary=./campaign-glossary.txt
 ```
 
-For the operator-driven NPC-to-spell workflow, bind the normalized NPC lane
-payload from the completed NPC run to the spell extractor:
+For the maintained NPC-grounded workflow, use the explicit ordered pipeline.
+The first step produces the normalized NPC artifact; the second step receives
+it in memory and fans it out to spell extraction, combat extraction, and combat
+normalization:
 
 ```sh
-go run ./cmd/notarius run dnd-spells \
-  --config examples/dnd-npc-spell-sequential.config.yml \
+go run ./cmd/notarius run dnd-npc-grounded \
+  --config examples/dnd-npc-grounded.config.yml \
   --input examples/seriatim-minimal-transcript.json \
-  --reference spells.extract.npcs=./npc-run/lanes/npcs.json
+  --output-dir ./npc-grounded-output
 ```
 
-For the independent NPC-to-combat workflow, bind the same completed NPC lane
-to both combat stages explicitly:
-
-```sh
-go run ./cmd/notarius run dnd-combat \
-  --config examples/dnd-npc-combat-sequential.config.yml \
-  --input examples/seriatim-minimal-transcript.json \
-  --reference combat.extract.npcs=./npc-run/lanes/npcs.json \
-  --reference combat.normalize.npcs=./npc-run/lanes/npcs.json
-```
-
-The two selectors are independent stage-local bindings. Binding extraction
-does not implicitly bind normalization, and Notarius does not discover or
-schedule the preceding NPC run.
+The generated NPC content remains contextual grounding, not spell or combat
+evidence. It is represented in manifests and debug summaries by bounded
+identity and producer provenance, not by payload content or a filesystem path.
 
 The same grammar can target chunk, merge, and normalize slots when the configured
 modules declare them:
@@ -161,6 +160,23 @@ go run ./cmd/notarius run dnd-session \
   --resume
 ```
 
+To selectively rerun one ordered step and its dependent lanes, use the step ID
+from the configuration. The selected step and dependents are reported as
+`forced_recompute`; reusable predecessors are reported as `reused`:
+
+```sh
+go run ./cmd/notarius run dnd-npc-grounded \
+  --config examples/dnd-npc-grounded.config.yml \
+  --input examples/seriatim-minimal-transcript.json \
+  --resume --recompute-step grounded-events
+```
+
+Checkpoint decisions use these categories: `reused`, `executed`,
+`forced_recompute`, and `dependency_invalidated`. The reason code and bounded
+detail identify the decision without exposing reference content, local paths,
+or secrets. `--recompute-step` requires checkpoint recording and `--resume`;
+unknown step IDs, empty values, and combinations with `--only` are rejected.
+
 Use `--debug` to retain the redacted summary and trace bundle for one run. The
 bundle is allocated before pipeline resolution; once allocated, its path is
 also printed to stderr if the command fails. Debug-write failures cause exit