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

@@ -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).