Document the native CLI and migration workflows

This commit is contained in:
2026-11-20 06:41:59 +00:00
parent faa8cb5822
commit 0e9cbc9c2a
16 changed files with 633 additions and 672 deletions

View File

@@ -6,17 +6,13 @@ For command syntax, see [docs/cli.md](./cli.md). For field-level config, see [do
## Campaign and Session Selection
Campaign selection priority:
- `--campaign-file`
- `--campaign`
- `pipeline.campaigns.default_campaign_id`
Session source priority:
- `--session`
- local default search paths
- remote session object (S3) when local session file is not found and storage is configured
Identity and exact-file selection are complementary: a selected file supplies
configuration and an explicit ID asserts its effective identity. Session domain
commands take positional identity; `--session-file` selects its source. An
explicit `--party-file` supplies the roster consistently across consumers.
See [CLI selectors](cli.md#configuration-selectors) and
[configuration discovery](config.md#discovery-and-selection) for selection rules.
Existing scripts should follow the [CLI migration table](cli.md#migration-from-the-previous-cli).
## Session Initialization
@@ -70,21 +66,19 @@ narratio run 2026-04-04
narratio session status 2026-04-04
```
Run, plan, and status output identify the resolved pipeline overlay (or `none`)
and effective configuration digest. Status distinguishes the current resolved
value from the last value persisted in the session manifest, which helps
diagnose overlay switches without changing resume authority.
Status distinguishes currently resolved configuration provenance from the last
persisted configuration, helping diagnose overlay switches without changing
semantic resume authority. Run and plan reports describe execution and decisions;
see the [report fields](cli.md#public-domain-report-fields).
Before switching an operational overlay, compare its effective meaning with the
production base through `narratio config diff default <overlay>`.
The command is read-only and succeeds whether it finds differences or not. Its
sorted records describe defaulted, expanded concrete configuration—not source
file layout—so it can be used to review model, artifact, and publish changes
without creating a session or run. Use `narratio config artifacts` to review the
concrete artifact identities, definitions, outputs, and dependencies. Select the
same campaign explicitly when overlays could resolve different campaign paths;
see the [CLI reference](cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff)
for syntax and record format.
Before switching an operational overlay, compare its effective configuration
with the base through `narratio config diff --against-overlay NAME`. When using an
explicit root, supply it with both `--config` and `--against-config`. Each side
loads independently using its own defaults. Native inspection retains authored
family declarations; use `narratio artifacts list` to review concrete identities,
outputs, dependencies, and selected-party members. See
[configuration inspection](cli.md#configuration-inspection) for selection and
comparison details.
## Stage Execution and Continuation Behavior
@@ -148,7 +142,7 @@ the stage self-skip.
Single-stage execution:
```bash
narratio run-stage normalize 2026-04-04 --force
narratio run 2026-04-04 --stage normalize --force
```
Contiguous bounded execution uses inclusive canonical endpoints:
@@ -199,7 +193,7 @@ canonical `transcripts/raw/<speaker>.json` files remain durable, however.
After correcting the underlying problem, retry normally:
```bash
narratio run-stage transcribe 2026-04-04
narratio run 2026-04-04 --stage transcribe
```
Narratio hashes the current prepared audio, validates recorded transcript JSON,
@@ -213,7 +207,7 @@ a WhisperX model or private server-side configuration changes behind the same
URL and language:
```bash
narratio run-stage transcribe 2026-04-04 --force
narratio run 2026-04-04 --stage transcribe --force
```
Force durably clears the reusable collection before sending requests. If that
@@ -242,21 +236,21 @@ Choose the narrowest workflow that matches the intended replacement:
| Intent | Command | Preserved and rebuilt state |
| --- | --- | --- |
| Rebuild analysis only | [`narratio analyze 2026-04-04`](./cli.md#analyze) | Preserves transcripts and the current extraction bundle; force-runs selected analysis artifacts and their required analysis prerequisites. |
| Rebuild extraction and analysis | [`narratio regenerate-artifacts 2026-04-04`](./cli.md#regenerate-artifacts) | Preserves transcripts; force-runs the complete configured extraction bundle, then selected analysis. `--artifacts` narrows analysis only. |
| Rebuild analysis only | [`narratio run 2026-04-04 --stage analyze --force`](./cli.md#run) | Preserves transcripts and the current extraction bundle; force-runs selected analysis artifacts and their required analysis prerequisites. |
| Rebuild extraction and analysis | [`narratio artifacts regenerate 2026-04-04`](./cli.md#artifacts-regenerate) | Preserves transcripts; force-runs the complete configured extraction bundle, then selected analysis. `--artifacts` narrows analysis only. |
| Continue bounded work normally | [`narratio run 2026-04-04 --from extract --through analyze`](./cli.md#run) | Uses ordinary resume decisions: current extraction and analysis can be skipped, while incomplete or obsolete work runs. |
All three stop before publication. Inspect the results and run
[`narratio publish`](./cli.md#publish) separately when delivery is intended.
[`narratio run SESSION --stage publish --force`](./cli.md#run) separately when delivery is intended.
For the extraction-plus-analysis development loop, use:
```bash
narratio regenerate-artifacts 2026-04-04
narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout
narratio artifacts regenerate 2026-04-04
narratio artifacts regenerate 2026-04-04 --artifacts session_recap,player_handout
```
This command is a transparent expansion to a forced bounded `run` from
This command shares the forced bounded execution operation from
`extract` through `analyze`. Extraction always rebuilds its complete configured
bundle. Analysis rebuilds the selected targets and their required analysis
prerequisites, or uses the normal default selection when no artifact names are
@@ -268,7 +262,7 @@ set is ready:
```bash
narratio session artifacts 2026-04-04
narratio publish 2026-04-04
narratio run 2026-04-04 --stage publish --force
```
If planning or execution reports stale, missing, failed, or tampered
@@ -352,8 +346,9 @@ not create a separate workspace or retain a separate current extraction result.
Narratio cannot observe edits inside Notarius configuration behind an unchanged
selector. Force extraction after such an edit when a replacement is intended.
Use `regenerate-artifacts` when both extraction and analysis must be rebuilt;
use `analyze` when the existing extraction bundle should be preserved. Field
Use `artifacts regenerate` when both extraction and analysis must be rebuilt;
use `run SESSION --stage analyze --force` when the existing extraction bundle
should be preserved. Field
semantics belong in [Configuration](./config.md#notarius-configuration-overlay),
with Audita selectors covered under
[Audita selection and credentials](./config.md#audita-selection-and-credentials).
@@ -367,13 +362,13 @@ concrete character artifact. Select a concrete generated key to operate on one
member only. Manifests and plan output retain the concrete key as the durable
identity and include the family and character ID as optional provenance.
`--artifacts` can be used on `run`, `session plan`, `run-stage`, `analyze`, and
`publish`. For a bounded run or plan, the selected range must contain `analyze`
`--artifacts` can be used on `run`, `session plan`, and
`artifacts regenerate`. For a bounded run or plan, the selected range must contain `analyze`
or `publish`.
Selection behavior:
- validates names against `pipeline.scriptorium.artifacts`;
- validates names against the derived concrete catalog and family selections;
- selects explicit analyze targets and permits their required configured
prerequisites to be reused or rebuilt first;
- filters publish rules for `narratio.artifact.<name>` sources only;
@@ -429,7 +424,7 @@ prepared file is missing or inconsistent with its manifest checksum, repair
the source configuration and refresh prepared state first:
```bash
narratio run-stage prepare 2026-04-04 --force
narratio run 2026-04-04 --stage prepare --force
```
Starting a replacement clears the previous extraction payload from the current
@@ -538,7 +533,7 @@ contract](./integrations/audita.md) for report placement and limits.
Narratio's polish resume evidence tracks selected config path, Audita overlay,
profiles, ordered modules, description, schema, and output identity. Editing
Audita-owned files behind unchanged selectors is invisible to Narratio; force
polish with `narratio run-stage polish <session-id> --force` after such edits.
polish with `narratio run <session-id> --stage polish --force` after such edits.
## External Command Lifecycle
@@ -581,7 +576,7 @@ the committed manifest and declared transcript/artifact objects.
To intentionally replace the current extraction result, run:
```bash
narratio run-stage extract 2026-04-04 --force
narratio run 2026-04-04 --stage extract --force
```
Narratio automatically reruns extraction when its recorded invocation contract,
@@ -610,16 +605,10 @@ before commit selection.
Run publish only:
```bash
narratio publish 2026-04-04
narratio run 2026-04-04 --stage publish --force
```
Equivalent:
```bash
narratio run-stage publish 2026-04-04 --force
```
This standalone command stops after publish and does not invoke cleanup. A
This selection stops after publish and does not invoke cleanup. A
default full `run` continues through notify and cleanup.
Publish commit model:
@@ -689,7 +678,7 @@ Operational rules:
Examples:
```bash
narratio session locks 2026-04-04
narratio session locks list 2026-04-04
narratio session locks add 2026-04-04 narratio.artifact.session_recap --reason "manual edits" --force
narratio session locks remove 2026-04-04 narratio.artifact.session_recap
```
@@ -847,20 +836,20 @@ the session workload.
Session-scoped cleanup:
```bash
narratio clean 2026-04-04
narratio session clean 2026-04-04
```
Global cleanup:
```bash
narratio clean --all
narratio session clean --all
```
Dry-run and cache variants:
```bash
narratio clean 2026-04-04 --dry-run --clear-cache
narratio clean --all --dry-run --clear-cache
narratio session clean 2026-04-04 --dry-run --clear-cache
narratio session clean --all --dry-run --clear-cache
```
Rules:
@@ -879,9 +868,9 @@ Cleanup derives only the configured run-scoped spool and workspace targets,
uses root-confined deletion, and does not read or mutate object storage. A
failure leaves publish succeeded and the remote committed snapshot current.
Retry with a normal full run: valid upstream work, including publish and notify,
is skipped while the failed cleanup stage runs again. `run-stage cleanup` is
is skipped while the failed cleanup stage runs again. `run SESSION --stage cleanup` is
also available when the manifest has valid publish evidence. A range ending at
`notify` or earlier and the standalone `publish` command never delete local
`notify` or earlier and `run SESSION --stage publish` never delete local
state.
Older local manifests that contain the retired cleanup-obligation field are
@@ -900,3 +889,9 @@ normal migration path.
- Restore requires configured object storage and committed remote current state.
- Pipeline-loading commands bootstrap filesystem secrets once before configuration
resolution and object-store initialization.
Console progress and informational diagnostics use native invocation visibility.
`--progress` shows work without requiring verbose mode; `--verbose` adds source
and decision context. Console `--debug` does not enable downstream debug capture
or change retention. Downstream streams stay in captured logs. See
[CLI reporting](cli.md#reporting-and-visibility) for mode combinations and formats.