Document the native CLI and migration workflows
This commit is contained in:
@@ -39,7 +39,7 @@ Likely cause:
|
||||
Diagnostics:
|
||||
|
||||
```bash
|
||||
narratio session validate 2026-04-04 --session /path/session.yml
|
||||
narratio session validate 2026-04-04 --session-file /path/session.yml
|
||||
```
|
||||
|
||||
Safe fix:
|
||||
@@ -62,7 +62,7 @@ Likely cause:
|
||||
Diagnostics:
|
||||
|
||||
```bash
|
||||
narratio session plan 2026-04-04 --config /path/pipeline.yml --campaign-file /path/campaign.yml --session /path/session.yml
|
||||
narratio session plan 2026-04-04 --config /path/pipeline.yml --campaign-file /path/campaign.yml --session-file /path/session.yml
|
||||
```
|
||||
|
||||
Safe fix:
|
||||
@@ -115,23 +115,27 @@ Diagnostics:
|
||||
narratio config sources --config /path/pipeline.yml --overlay testing
|
||||
```
|
||||
|
||||
Add `--campaign` or `--campaign-file` when the pipeline has party-driven
|
||||
artifact families. The output identifies each effective logical field's root,
|
||||
import, overlay, default, campaign, party, or family source without printing
|
||||
the field value or credential contents. Empty optional import selections are
|
||||
reported separately; selected invalid files still fail.
|
||||
Native sources list the actual files and import evidence for the selected
|
||||
scope. To trace a value, use `config explain --path POINTER`, or discover paths
|
||||
with `config explain --list`. App inspection keeps family declarations;
|
||||
`artifacts list` derives concrete members from the selected campaign/party.
|
||||
|
||||
Safe fix:
|
||||
|
||||
- move a duplicated base field so it has one owner;
|
||||
- correct the selected overlay; or
|
||||
- correct the campaign party/family declaration that owns generated values.
|
||||
- inspect the field's effective origin and history;
|
||||
- correct the selected source or overlay; or
|
||||
- select the intended roster when reviewing family members.
|
||||
|
||||
To review what would actually change before switching overlays, run `config
|
||||
diff` with the same pipeline and campaign selectors. It compares normalized
|
||||
effective values rather than YAML formatting or source-file layout.
|
||||
To compare an explicit pipeline root with its testing overlay, select the root
|
||||
on both sides:
|
||||
|
||||
Relevant reference: [Configuration inspection](./config.md#read-only-effective-pipeline-inspection).
|
||||
```sh
|
||||
narratio config diff --config /path/pipeline.yml --against-config /path/pipeline.yml --against-overlay testing --details
|
||||
```
|
||||
|
||||
The sides use independent defaults. Comparison concerns effective native values,
|
||||
including declarations, rather than generated domain objects or YAML layout.
|
||||
See [configuration inspection](./cli.md#configuration-inspection).
|
||||
|
||||
## Audio mode conflict
|
||||
|
||||
@@ -165,7 +169,7 @@ Likely causes:
|
||||
|
||||
- key not defined in `pipeline.scriptorium.artifacts`;
|
||||
- empty list entry (for example trailing comma);
|
||||
- `run-stage` used with non-`analyze`/`publish` target.
|
||||
- selected run/plan range contains neither `analyze` nor `publish`.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
@@ -202,7 +206,7 @@ narratio session plan 2026-04-04 --from render --through analyze
|
||||
Safe fix:
|
||||
|
||||
- widen the bounded range to include the first reported stage, or recover that
|
||||
stage explicitly with `run-stage` before retrying. The failed check does not
|
||||
stage explicitly with `run --stage` before retrying. The failed check does not
|
||||
create a run-local directory or modify the manifest. Narratio does not
|
||||
resume-validate excluded prefix stages, and stages after `--through` are not
|
||||
prerequisites.
|
||||
@@ -243,7 +247,7 @@ Safe fix:
|
||||
for a successful checkpoint.
|
||||
|
||||
```bash
|
||||
narratio run-stage transcribe 2026-04-04
|
||||
narratio run 2026-04-04 --stage transcribe
|
||||
```
|
||||
|
||||
Valid earlier speaker checkpoints remain reusable even while aggregate
|
||||
@@ -271,7 +275,7 @@ Safe fix:
|
||||
retry if the replacement attempt is interrupted.
|
||||
|
||||
```bash
|
||||
narratio run-stage transcribe 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage transcribe --force
|
||||
```
|
||||
|
||||
Transport replay and application retries do not provide an exactly-once remote
|
||||
@@ -375,7 +379,7 @@ Safe fix:
|
||||
An exit-zero polish with a valid transcript succeeds even when Audita reports
|
||||
recoverable errors or no corrections. Missing reports are allowed when Audita
|
||||
reporting is disabled externally. Edits to Audita-owned files behind unchanged
|
||||
selectors require `narratio run-stage polish <session-id> --force` to replace a
|
||||
selectors require `narratio run <session-id> --stage polish --force` to replace a
|
||||
previously successful result. See the [Audita integration contract](./integrations/audita.md).
|
||||
|
||||
## Notarius executable missing
|
||||
@@ -447,7 +451,7 @@ Safe fix:
|
||||
evidence before extraction:
|
||||
|
||||
```bash
|
||||
narratio run-stage prepare 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage prepare --force
|
||||
```
|
||||
|
||||
Do not point Notarius directly at the original source path or edit the manifest
|
||||
@@ -607,7 +611,7 @@ Symptom:
|
||||
Safe fix:
|
||||
|
||||
```bash
|
||||
narratio run-stage extract 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage extract --force
|
||||
```
|
||||
|
||||
Narratio fingerprints its invocation contract and prepared Narratio reference
|
||||
@@ -650,7 +654,7 @@ Safe fix:
|
||||
the canonical path as a substitute for current evidence.
|
||||
|
||||
```bash
|
||||
narratio analyze 2026-04-04 --artifacts session_recap
|
||||
narratio run 2026-04-04 --stage analyze --force --artifacts session_recap
|
||||
```
|
||||
|
||||
Relevant references: [Operations: Artifact Selection](./operations.md#artifact-selection)
|
||||
@@ -730,7 +734,7 @@ Safe fix:
|
||||
|
||||
```bash
|
||||
narratio run 2026-04-04
|
||||
narratio publish 2026-04-04
|
||||
narratio run 2026-04-04 --stage publish --force
|
||||
```
|
||||
|
||||
After current records exist, inspect them and publish explicitly. Do not copy
|
||||
@@ -775,7 +779,7 @@ Safe fix:
|
||||
reusable unless selected themselves.
|
||||
|
||||
```bash
|
||||
narratio analyze 2026-04-04 --artifacts session_recap
|
||||
narratio run 2026-04-04 --stage analyze --force --artifacts session_recap
|
||||
```
|
||||
|
||||
Relevant reference: [Analyze Internals](./internal/stage-analyze.md#invariants).
|
||||
@@ -809,7 +813,7 @@ narratio session restore 2026-04-04
|
||||
or rerun prepare after correcting session config:
|
||||
|
||||
```bash
|
||||
narratio run-stage prepare 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage prepare --force
|
||||
```
|
||||
|
||||
Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow).
|
||||
@@ -911,7 +915,7 @@ Diagnostics:
|
||||
```bash
|
||||
narratio session artifacts 2026-04-04 --remote
|
||||
narratio session status 2026-04-04
|
||||
narratio run-stage publish 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage publish --force
|
||||
```
|
||||
|
||||
Safe fix:
|
||||
@@ -944,8 +948,8 @@ Safe fix:
|
||||
- rerun render and then retry downstream stage(s):
|
||||
|
||||
```bash
|
||||
narratio run-stage render 2026-04-04 --force
|
||||
narratio run-stage analyze 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage render --force
|
||||
narratio run 2026-04-04 --stage analyze --force
|
||||
```
|
||||
|
||||
Relevant reference: [Operations: Stage Execution](./operations.md#stage-execution-and-continuation-behavior).
|
||||
|
||||
Reference in New Issue
Block a user