Expose run-wide reasoning effort controls

docs/cli.md

@@ -41,14 +41,21 @@ pipeline ID and **--input** are required.
 | **--only lane-a,lane-b** | Run only the selected comma-separated artifact lanes when that selection is valid for the configured pipeline. |
 | **--llm-profile id** | Override effective LLM-capable module bindings with one configured profile. |
 | **--session-id id** | Supply a non-empty prompt session identifier to LLM-backed module calls. |
+| **--reasoning-effort value** | Replace the selected PromptKit profile's reasoning effort for every LLM-backed call in this run. The value must be non-empty and the flag may be specified only once. |
+| **--clear-reasoning-effort** | Clear reasoning effort inherited from the selected PromptKit profile for every LLM-backed call in this run. |
 | **--reference selector=path** | Add or replace a file reference binding. Repeatable. |
 | **--without-reference selector** | Remove a configured optional reference binding. Repeatable. |
 
 **--chunk_cache** accepts only **auto**, **bypass**, or **refresh**.
 **--debug-dir**, **--output-dir**, **--session-id**, and
-**--recompute-step** reject explicit empty values. **--recompute-step**
-requires **--resume**; checkpoint requirements and reuse behavior are
-documented in [Operations](operations.md).
+**--reasoning-effort**, and **--recompute-step** reject explicit empty values.
+**--reasoning-effort** and **--clear-reasoning-effort** are mutually exclusive.
+When neither is present, reasoning effort comes from the selected PromptKit
+profile. These controls apply to the shared run client, including retries and
+LLM-backed validators, and do not modify configuration or profile files.
+Persistent reasoning settings remain a PromptKit profile concern.
+**--recompute-step** requires **--resume**; checkpoint requirements and reuse
+behavior are documented in [Operations](operations.md).
 
 ### Reference selectors
 

docs/internal/cli.md

@@ -63,9 +63,13 @@ the adapter mechanics remain in [LLM Runtime](llm.md).
 
 The factory also accepts `LLMRuntimeOverrides`, whose reasoning pointer
 preserves inherit, replace, and clear states across the composition boundary.
-Run orchestration currently passes the zero value, so production execution
-inherits the selected PromptKit profile. No command flag or Notarius
-configuration field exposes this internal override yet.
+Run orchestration constructs this value from the mutually exclusive
+`--reasoning-effort` and `--clear-reasoning-effort` controls. Absence preserves
+a nil pointer, replacement is trimmed, and clear uses a non-nil empty string.
+The same override reaches the one shared production client, checkpoint
+identity, and debug invocation metadata. Persistent reasoning configuration
+remains owned by PromptKit profiles; Notarius configuration has no reasoning
+field.
 
 ## Run Orchestration
 

docs/internal/llm.md

@@ -40,8 +40,11 @@ Client construction may also receive a run-wide reasoning-effort override from
 the CLI factory boundary. The adapter copies the caller-owned pointer and
 creates a fresh PromptKit execution override for each request: a nil pointer
 inherits the selected profile, a non-empty value replaces it, and an empty
-value clears inherited reasoning. Ordinary CLI execution currently supplies no
-override, so profile behavior remains unchanged.
+value clears inherited reasoning. The CLI's mutually exclusive
+`--reasoning-effort` and `--clear-reasoning-effort` controls select those
+states. With neither flag, profile behavior remains unchanged. Because
+production constructs one shared client, the selected state applies uniformly
+to module calls, retries, and LLM-backed validators for the whole run.
 
 An empty request profile lets the prompt select its configured default. The CLI
 prepares every explicitly selected binding profile before a run begins, so a

docs/operations.md

@@ -121,6 +121,9 @@ provenance, the effective PromptKit profile-source fingerprint, and
 prepared-component fingerprints. Changing profile content causes a cold miss
 even when its profile ID is unchanged. A changed identity produces a cold miss;
 Notarius does not migrate, rewrite, or delete older checkpoint directories.
+Reasoning-effort inheritance, replacement, and explicit clearing are distinct
+runtime identities, so checkpoints created under one state are not reused by
+either of the others.
 
 Checkpoint state is confined below an identity-specific path:
 
@@ -180,7 +183,9 @@ warning, checkpoint, chunk-plan, and terminal reporting artifacts. The trace
 contains allowlisted application diagnostic records and can include source or
 derived application data. Neither surface is a cache input. Do not treat a
 debug bundle as safe to share merely because its configuration summary is
-redacted.
+redacted. Invocation metadata omits reasoning effort when it is inherited,
+records the replacement value when one is supplied, and records an empty value
+when inherited reasoning was explicitly cleared.
 
 Notarius never creates debug state without an explicit request and never
 automatically deletes a requested bundle. If allocation succeeds, the command
@@ -209,7 +214,10 @@ or automatic cleanup command.
 ## Operational Limits
 
 Provider execution settings and the generation timeout come from the selected
-PromptKit profile. PromptKit v0.1.0 does not add a provider retry loop;
+PromptKit profile. The invocation-only **--reasoning-effort** and
+**--clear-reasoning-effort** controls may replace or clear that profile setting
+for all LLM-backed calls in one run without changing the profile. PromptKit
+v0.2.0 does not add a provider retry loop;
 Notarius binding retries rerun the complete module operation and validation
 chain as defined by [module bindings](config.md#module-bindings-and-validators).