Document the native CLI and migration workflows
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user