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

@@ -5,7 +5,8 @@ polished transcripts, validated Notarius extraction lanes, and generated
artifacts. artifacts.
It runs a deterministic workflow with manifest-driven continuation, remote It runs a deterministic workflow with manifest-driven continuation, remote
publish, and restore support. publish, and restore support. Its CommandKit CLI provides native configuration
inspection, structured operation reports, progress, and shell completion.
```sh ```sh
narratio run 2026-04-04 narratio run 2026-04-04

View File

@@ -1,497 +1,449 @@
# CLI Reference # CLI Reference
## Shortest Useful Command ## Command tree
```bash
narratio run 2026-04-04
```
This runs the canonical full pipeline for session `2026-04-04`.
## Command Overview
Top-level commands:
- `version`: print the Narratio build version.
- `run <session_id>`: run all or one contiguous range of the canonical stage order.
- `regenerate-artifacts <session_id>`: force-run extraction through analysis.
- `run-stage <stage> <session_id>`: run one stage.
- `analyze <session_id>`: force-run analyze.
- `publish <session_id>`: force-run publish.
- `clean <session_id>` or `clean --all`: remove local work/spool state.
- `session <subcommand>`: session helper commands.
- `config <subcommand>`: validate, display, source-trace, catalog, or compare resolved pipeline configuration.
Session subcommands:
- `session init <session_id>`
- `session plan <session_id>`
- `session validate <session_id>`
- `session status <session_id>`
- `session restore <session_id>`
- `session artifacts <session_id>`
- `session locks <session_id>`
- `session locks add <session_id> <source>`
- `session locks remove <session_id> <source>`
## Common Config Flags
Most session-aware commands accept:
- `--config <pipeline.yml>`
- `--campaign <id>`
- `--campaign-file <campaign.yml>`
- `--session <session.yml>`
- `--session-id <session_id>`
- `--previous-session-id <session_id>`
- `--overlay <name>`
- `--secrets-dir <directory>`
Rules:
- `--campaign` and `--campaign-file` are mutually exclusive.
- `--session` is not used by `session init`.
- if both positional `<session_id>` and `--session-id` are provided, values must match.
- `--previous-session-id` is a strict expectation: the selected session file
must contain the same `previous_session_id`.
- `--overlay` selects `overlays/<name>.yml` relative to the pipeline root. It
may be supplied once; omitted, empty, and the exact name `default` select the
base configuration, while an unknown named overlay fails. The same selection
applies to all common-flag commands, including `regenerate-artifacts`.
- `--secrets-dir` selects ConfigKit credential-file bootstrap explicitly. A
relative value uses caller CWD. Without the flag, Narratio uses the optional
`/usr/local/etc/narratio/secrets` directory.
- `clean --all` cannot be combined with campaign/session selectors.
- notification delivery is currently limited to the configured `noop` mode; see
the [configuration reference](./config.md#notifications).
## Session ID Input Rules
Session-aware commands accept one of these forms:
- positional session ID: `... <session_id>`
- compatibility flag: `... --session-id <session_id>`
When both are present, command parsing requires an exact match.
Commands with additional positionals keep their command-specific order:
- `run-stage <stage> <session_id>` or `run-stage <stage> --session-id <session_id>`
- `session locks add <session_id> <source>` or `session locks add --session-id <session_id> <source>`
- `session locks remove <session_id> <source>` or `session locks remove --session-id <session_id> <source>`
## Command Reference
### `config validate`, `config show`, `config sources`, `config artifacts`, and `config diff`
```bash
narratio config validate [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config show [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config sources [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config artifacts [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config diff <left-overlay> <right-overlay> [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--secrets-dir <directory>]
```
These commands resolve the selected overlay, defaults, ordinary paths, and—if
a campaign is selected—the campaign-owned party. They neither discover or load
a session nor create a workspace, manifest, run, lock, adapter, or remote
connection. Like every pipeline-loading command, they bootstrap the selected or
conventional secrets directory before resolving configuration; `config show`
never includes bootstrap reports or secret values in its YAML output.
Typed credential references, including `notarius.credentials[]`, must therefore
resolve even though these inspection commands never construct an adapter.
Campaign selection is optional for a pipeline without party-driven artifact
families. A pipeline with `scriptorium.artifact_families` needs a selected or
configured default campaign so Narratio can expand its concrete artifacts and
publish rules. `--campaign` and `--campaign-file` remain mutually exclusive.
Session, range, force, and artifact-execution flags are not accepted.
`config validate` writes a concise root-path, selected-overlay (or `none`), and
effective-digest summary after successful complete validation. `config show`
writes one deterministic, secret-free YAML document containing defaulted and
expanded concrete configuration. It omits ConfigKit directives, artifact
family declarations, and runtime provenance.
`config sources` reports the same fully validated resolution without printing
effective values. Its header identifies the root, ordered imports, selected
overlay and its file, selected campaign, party source, and digest. The
remaining tab-separated records are sorted as `path`, `role`, and `source`.
Roles distinguish root, import, overlay, normalization, centralized default,
campaign, party, and generated family ownership. Records labeled
`resolution` retain their effective pre-normalization source contributors;
superseded definitions remain historical evidence in the artifact catalog.
Records labeled
`empty_import` identify the source-local declaration path, selector, and
location of an optional import that selected no sources. A generated party member has
one family record and one party record at the same logical path. The output
never reads or prints secret values.
`config artifacts` prints the concrete catalog used by analysis, ordered by
artifact key. Its tab-separated header is `key`, `source`, `definitions`,
`enabled`, `output`, `dependencies`, `family`, `character`, `family_source`, and
`party_source`. Definitions and effective dependencies are sorted comma-separated
lists, and control characters in fields are escaped. Family-member rows identify
their family, character, contributing family source files, and party file.
Family source paths are comma-separated when ConfigKit reports a composite
origin. An empty catalog prints only the header. Ordinary artifacts can be
inspected without a campaign; party-driven families retain the campaign
requirement. See
[Scriptorium Artifact Entries](./config.md#scriptorium-artifact-entries) for the
configuration layout.
`config diff` resolves both supplied overlay names independently and compares
their fully resolved, secret-free effective mappings. It does
not accept `--overlay`; the two positional names must be distinct, valid
overlays. When party-driven families are present, both overlays must resolve to
the same selected campaign and party. Use `--campaign-file` if overlay-specific
campaign configuration would otherwise select different files.
Equal overlays print `no differences`. Otherwise, sorted tab-separated records
use one of these forms, with compact JSON values:
```text ```text
added <path> <right-value> narratio
removed <path> <left-value> ├── run SESSION
changed <path> <left-value> <right-value> ├── artifacts
│ ├── list
│ └── regenerate SESSION
├── session
│ ├── init SESSION
│ ├── plan SESSION
│ ├── validate SESSION
│ ├── status SESSION
│ ├── restore SESSION
│ ├── clean [SESSION | --all]
│ ├── artifacts SESSION
│ └── locks
│ ├── list SESSION
│ ├── add SESSION SOURCE
│ └── remove SESSION SOURCE
├── config
│ ├── scopes
│ ├── validate
│ ├── show
│ ├── sources
│ ├── explain
│ └── diff
├── version
├── completion bash|zsh|fish
└── help [COMMAND...]
``` ```
Paths use JSON Pointer notation, with `~0` for `~` and `~1` for `/`. Native Bare root and command groups display help. Use `narratio help session plan`
comparison reports a changed mapping region as one value when a whole mapping or `narratio session plan --help` for command-local flags and operands. Help,
is added or removed; lists are compared as whole values. A `hidden_changed=true` version, completion, and `config scopes` do not bootstrap credentials, load
field indicates a change hidden by redaction. The command compares defaulted concrete artifacts and publish rules, not configuration, contact storage, or initialize adapters.
overlay names, source-file layout, or formatting. It succeeds when differences
are found, making it suitable for review and migration checks.
### `version` ## Invocation syntax
```bash Place flags after the complete command path; they may be interspersed with
narratio version operands there. For example, `narratio session plan --format json SESSION`
and `narratio session plan SESSION --format json` are equivalent. Flags are
local to the selected command. `--` ends option parsing.
Value flags accept `--name value` or `--name=value`. Boolean flags accept
presence as true or an explicit value such as `--force=false`. Repeated
single-value flags use the last successfully parsed value; every occurrence
must parse. Repeatable flags accumulate values. An explicitly supplied empty,
false, or zero value differs from omission. Narratio additionally normalizes
repeatable `--artifacts` values as described below.
## Configuration selectors
| Selector | Meaning |
| --- | --- |
| `--config PATH` | Exact pipeline root, regardless of configuration scope; omission uses discovery. |
| `--overlay NAME` | Pipeline overlay; omitted, empty, or `default` selects the base. |
| `--campaign ID` | Select and assert the effective campaign identity. |
| `--campaign-file PATH` | Exact campaign source; may accompany its identity assertion. |
| `--session ID` | Session identity for native configuration inspection only. |
| `--session-file PATH` | Exact session source; domain commands use positional `SESSION` as the identity assertion. |
| `--party-file PATH` | Select the canonical roster instead of the campaign's default file. |
| `--secrets-dir PATH` | Explicit credential-bootstrap directory. |
| `--previous-session-id ID` | Assert the configured previous-session identity on applicable domain commands. |
Explicit relative file/directory paths use the invocation directory. Explicit
file errors and identity mismatches fail without fallback. A file selects the
source; an identity asserts its effective ID after resolution. File-only
configuration inspection may obtain identity from the file. Selecting a party
file does not rewrite the campaign's party setting; the selected roster feeds
players, family expansion, planning, and execution consistently.
Selectors are installed only where applicable; command help lists them.
`session init` creates new input and therefore has no existing-session-file
or party-file selection. `session clean --all` accepts pipeline/overlay/secrets
selection and rejects campaign, session, party, and previous-session selectors.
When no explicit session file is selected, local discovery precedes remote
acquisition. Only local absence permits remote fallback, with a known identity.
Remote loading prefers authored session-root YAML, then the current commit's
prepared snapshot only when the authored object is absent. Read-only commands
may perform these reads without initializing runtime state. See
[discovery](config.md#discovery-and-selection) and
[credential bootstrap](config.md#secrets-handling) for configuration details.
## Run
```sh
narratio run SESSION
narratio run SESSION --from extract --through analyze
narratio run SESSION --stage analyze --force --artifacts session_recap
``` ```
Official release binaries report their exact Git tag. Binaries built directly The default is the full canonical pipeline:
from source without release linker metadata report `dev`. `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, `render`,
`extract`, `analyze`, `publish`, `notify`, `cleanup`.
`--from` and `--through` select inclusive contiguous bounds. `--stage` selects
one stage and cannot accompany explicitly supplied range flags. `--force`
reruns selected work; dependent invalidation can extend beyond that range.
Bounded starts require valid preceding manifest state. Ordinary execution uses
semantic resume checks rather than rerunning all selected work.
### `run` Analysis-only rebuilding uses `run SESSION --stage analyze --force`; it does
not refresh extraction. Publishing alone uses `run SESSION --stage publish`,
adding `--force` when a rerun is intended. It does not schedule cleanup. See
[operations](operations.md#artifact-development-workflows) for regeneration workflows.
```bash ## Artifacts regenerate
narratio run <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
```sh
narratio artifacts regenerate SESSION
narratio artifacts regenerate SESSION --artifacts session_recap,player_handout
``` ```
Behavior: Forces the fixed inclusive `extract` through `analyze` range. It refreshes the
whole configured Notarius extraction bundle and chunk work, then selected
analysis targets and required prerequisites. `--artifacts` narrows analysis,
not extraction lanes. Publication, notification, and cleanup are outside this
range. Independent `--from`, `--through`, `--stage`, and `--force` flags are
not installed on this command. It accepts applicable context selectors and
returns the same run report as `run`.
- evaluates one inclusive contiguous range of the canonical stage order; ## Artifacts list
- defaults an omitted `--from` to `prepare` and an omitted `--through` to
`cleanup`, so omitting both retains full-pipeline behavior;
- rejects unknown endpoints and a `--from` endpoint after `--through`;
- runs `render` before `extract`; an omitted or disabled Notarius
configuration records an explicit `notarius_disabled` self-skip;
- resolves every selected typed credential during the initial configuration
load, including Notarius credentials when extract is disabled, outside the
selected range, or later skipped as resumable;
- skips already-succeeded stages unless `--force` is set or a stage-specific
resume check finds its durable result obsolete;
- applies `--force` only to stages in the selected range;
- rejects repeated `--from`, `--through`, or `--force` options, including
`--name=value` spellings;
- continues interrupted or partially completed sessions by running non-succeeded stages;
- writes the session manifest as the sole durable progress ledger. Each
invocation also creates its run-local directory and returns an immediate
command summary; neither creates another durable progress record.
- reports the resolved overlay (or `none`) and effective configuration digest.
When `--artifacts` is present, the selected range must contain `analyze` or ```sh
`publish`. Either consumer is sufficient, including a one-stage range. narratio artifacts list --config pipeline.yml --campaign-file campaign.yml
### `regenerate-artifacts`
```bash
narratio regenerate-artifacts <session_id> [--artifacts <name[,name...]>] [...common config flags]
``` ```
Exactly equivalent to: Lists domain definitions: source identities, producers, outputs, dependencies,
and selected-party family/member provenance. It acquires the context needed to
derive that catalog, without requiring a session solely for listing definitions.
It does not add generated members to native `config show` output.
```bash ## Session plan
narratio run <session_id> --force --from extract --through analyze [caller options]
```sh
narratio session plan SESSION --stage analyze --force --format json
``` ```
The command always reruns extraction. Analysis rebuilds the selected configured Accepts the same stage/range, force, artifact, and context selections as `run`.
artifacts and any prerequisites required by those targets; without Reports execution/reuse actions and reasons, analysis targets, prerequisite work,
`--artifacts`, it uses the normal default analysis selection. Publish and notify and publication mappings through shared planners. Planning reads existing state
never run. Common session/configuration options and repeatable artifact values without creating a workspace, changing manifests, acquiring execution locks, or
pass through unchanged. initializing stage adapters. It does not predict unknown output identities.
The forced extraction rebuilds the complete configured Notarius bundle, ## Session validate
disables Notarius checkpoint loading, and requests chunk-plan refresh.
`--artifacts` narrows only the analysis work; it never selects Notarius lanes.
Because the expansion owns `--force`, `--from`, and `--through`, callers cannot ```sh
supply those options. The shared `run` parser reports them as duplicate narratio session validate SESSION --session-file ./session.yml
singleton flags. The alias has no private execution options or behavior, and
runtime diagnostics may identify the operation as `run`.
### `run-stage`
```bash
narratio run-stage <stage> <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
``` ```
Valid stage names: Read-only preflight checks configuration and required input, audio,
previous-session, publication, and lock readiness. Material findings remain in
the report regardless of diagnostic visibility. Invalid configuration uses the
native input classification; readiness failures are operational failures.
- `prepare` ## Session status
- `transcribe`
- `merge`
- `polish`
- `normalize`
- `trim`
- `render`
- `extract`
- `analyze`
- `publish`
- `notify`
- `cleanup`
Rules: ```sh
narratio session status SESSION --format json
- `--artifacts` is accepted only for `analyze` and `publish` stage targets.
### `analyze`
```bash
narratio analyze <session_id> [--artifacts <name[,name...]>] [...common config flags]
``` ```
Equivalent to: Reports local manifest stages and artifacts, configuration provenance, readiness,
and remote current state when storage is available. Remote output entries retain
exact committed declarations and carried-output origins separately from current
configured destinations. An absent remote current pointer is a reported missing
state, rather than an error by itself. Genuine inspection failures can return a
partial report with a failed outcome.
```bash ## Session artifacts
narratio run-stage analyze <session_id> --force [...common config flags]
```sh
narratio session artifacts SESSION --remote
``` ```
This selects only `analyze`: it does not invoke Notarius, replace extraction, Reports definitions, dependencies, local availability/evidence, and optional
or remove existing extract outputs. `--artifacts` narrows the forced analysis remote publication state without reading artifact payload bodies. Without
targets and their required analysis prerequisites. `--remote`, this command avoids remote artifact inspection. Current publication
outcomes include `published`, `carried_locked`, `locked_unpublished`,
`optional_missing`, and `unselected`.
### `publish` ## Session init
```bash ```sh
narratio publish <session_id> [--artifacts <name[,name...]>] [...common config flags] narratio session init SESSION --output ./session.yml --audio-dir ./audio
narratio session init SESSION --remote --audio-s3-prefix audio/session/
``` ```
Equivalent to: Choose exactly one destination: `--output PATH` or `--remote`. Options include
`--date YYYY-MM-DD`, `--title TEXT`, `--previous-session-id ID`, `--force`,
configuration/overlay/campaign/secrets selectors, and exactly one audio override
if needed: `--audio-dir PATH` or `--audio-s3-prefix PREFIX`.
```bash A configured session template retains its import/resource authoring context;
narratio run-stage publish <session_id> --force [...common config flags] relative CLI audio paths use the invocation directory. Generated YAML is
standalone and concrete. `--format` changes only the confirmation report,
never the generated YAML file. See [initialization](operations.md#session-initialization).
## Session restore
```sh
narratio session restore SESSION --dry-run
narratio session restore SESSION --force --include-audio
``` ```
This command selects only `publish`; it does not invoke cleanup. Use a normal Uses pointer-selected committed state and returns actions/conflicts. Dry runs
full run to include configured cleanup, or `run-stage cleanup` to retry cleanup make no local directory or mode changes. Actual restore preserves confined
from valid publication evidence. replacement, transition locking, incomplete-restore recovery markers, and
manifest-last installation. `--force` permits replacement only of eligible
regular files. The public report is separate from the persisted restore
execution report. See [restore operations](operations.md#restore-workflow).
### `clean` ## Session clean
```bash ```sh
narratio clean <session_id> [--dry-run] [--clear-cache] [...common config flags] narratio session clean SESSION --dry-run
narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>] narratio session clean --all --dry-run --clear-cache
``` ```
Behavior: Choose positional `SESSION` or `--all`. Removes the selected local workspace
and spool state; cache deletion requires `--clear-cache`. Dry runs return planned
actions without deletion. Partial failures retain completed actions. This manual
operation is separate from the pipeline cleanup stage. Exact scope and recovery
implications belong in [cleanup operations](operations.md#cleanup).
- session mode removes the selected session's local work and spool state; ## Session locks
- `--all` removes all local session work and spool state;
- cache remains unless `--clear-cache` is provided.
See [Operations: Cleanup](./operations.md#cleanup) for manual and pipeline-stage ```sh
deletion scope. narratio session locks list SESSION
narratio session locks add SESSION narratio.artifact.session_recap --reason 'manual review'
### `session plan` narratio session locks remove SESSION narratio.artifact.session_recap
```bash
narratio session plan <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
``` ```
Uses the same inclusive bounds, endpoint validation, force scope, and artifact A bare locks group displays help. List reports independent remote locks sorted
selection contract as `run`. It validates config and prints run/skip decisions by source. Add reports an existing lock unless `--force` requests one
for selected stages only without creating the local workdir or changing the conditional, generation-matched replacement; concurrent change requires retry.
manifest. Resume-capable selected stages are checked against durable evidence. Remove is idempotent. `--reason TEXT` is available on add. See
The output includes the resolved overlay (or `none`) and effective configuration [publish locks](operations.md#publish-locks) for their publication effect.
digest without writing provenance or any manifest state.
For `analyze`, the preview also lists explicit targets, prerequisite-only work,
execution order, and reusable current artifacts with concise reasons. These
artifact decisions come from the same reconciliation and work planner used by
execution; the preview does not predict output identities.
### `session validate` ## `--artifacts` selection rules
```bash `run`, `session plan`, and `artifacts regenerate` accept repeatable
narratio session validate <session_id> [...common config flags] `--artifacts NAME[,NAME...]`. Values are trimmed, deduplicated, and sorted.
Family keys select all concrete members; concrete keys select one member.
Analysis includes required prerequisite closure. Publication selects applicable
configured artifact outputs. The option requires a selected analysis or publish
consumer and does not select built-in output sources or individual extraction
lanes. See [artifact configuration](config.md#scriptorium-artifact-families).
## Configuration inspection
`config scopes` lists operations and features without loading. The four scopes
are `app` (default), `campaign`, `session`, and `party`. They expose their actual
typed ConfigKit results, with native provenance, resolution history, and safe
secret views. App inspection needs no campaign/party expansion. Domain catalogs
and execution plans are separate views.
```sh
narratio config show --scope app --format json
narratio config show --scope session --session SESSION --session-file ./session.yml
narratio config show --scope party --party-file ./party.yml
narratio config show --path /scriptorium --format yaml
narratio config sources --scope campaign --campaign-file ./campaign.yml
narratio config explain --path /scriptorium --format json
narratio config explain --list --under /scriptorium --historical
narratio config validate --details --severity error
``` ```
Read-only preflight checks for config validity, required inputs, audio mode, - `show` displays safe effective values; `--path POINTER` selects a current
previous-session requirements, publish outputs, and independent remote locks. value, including present null. An empty pointer selects the root.
- `sources` lists native source records, imports, placements, version evidence,
and empty optional-import selections. `--source-id ID` selects a record from
that load. Available source evidence can be reported after load failure.
- `explain --path POINTER` reports effective/history fragments, origins,
resolution reasons/dependencies, and safe secret-reference metadata.
`explain --list` discovers paths. `--under POINTER`, `--historical`, and
`--explicit=true|false` filter discovery; they require `--list`. Historical-only
paths do not match an explicitness filter. Neither mode supplied shows help.
- `validate` returns concise status or native structured scope outcomes.
`--details` includes findings; repeatable `--severity error|warning` and
`--code CODE` filter displayed findings, never validation success.
- `--scope all` is supported for show/validate, requiring applicable context for
every reached scope. It is unsupported for sources, explain, and diff.
### `session status` Paths use JSON Pointer: escape `/` as `~1` and `~` as `~0`. Malformed pointers
fail as usage; a well-formed unknown selected path fails operationally.
Native report fields and detailed source/history semantics are documented in the
[selected CommandKit CLI contract](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/docs/cli.md#configuration-scopes).
```bash ### Independent comparisons and overrides
narratio session status <session_id> [...common config flags]
```sh
narratio config diff --config pipeline.yml --against-config pipeline.yml --against-overlay testing --details --check
narratio config diff --scope party --party-file before.yml --against-party-file after.yml
narratio config show --scope app --set '/whisperx/concurrency=2'
``` ```
Prints local manifest state and, when storage is available, status for the Diff loads each side independently. In addition to native `--against-config`
pointer-selected remote commit and its declared published outputs. Current and `--against-overlay`, applicable scopes accept `--against-campaign`,
publish metadata reports `published`, `carried_locked`, `locked_unpublished`, `--against-campaign-file`, `--against-session`, `--against-session-file`, and
`optional_missing`, and `unselected`; carried output lines include the run `--against-party-file`. Omitted right-side selectors use their own normal
derived from their exact declared key, the key itself, and its declared defaults; they never inherit left-side selections. Each party default follows
destination. A separately displayed `dest` is the destination requested by the that side's campaign.
current configuration and may differ while an older declaration is locked.
### `session init` Concise diff reports `additions`, `changes`, and `deletions`; detailed diff
reports `scope` and `differences` with `path`, `before`, `after`, and
`hidden_changed`. Snapshots distinguish absence, null, and redaction. Comparison
uses effective values rather than source arrangement. Secret changes remain
hidden safely. A diff is inspection output, not a configuration patch.
```bash Only app inspection supports ordered, repeatable `--set POINTER=JSON`, plus
narratio session init <session_id> --output ./session.yml [options] `--against-set POINTER=JSON` for the comparison side. ConfigKit applies these
narratio session init <session_id> --remote [options] during that load. They affect only that invocation. Other scopes and aggregate
inspection reject overrides. Execution/planning use files and overlays;
they have no field-override flags.
## Reporting and visibility
Reports go to stdout; diagnostics and progress go to stderr. Domain commands
return one final public report where useful, including meaningful partial work
on failure. `--format text|yaml|json` selects presentation. Automatic structured
reports use YAML; text uses the same data. Version and native inspection commands
may have native text renderers. Report format does not change artifact formats.
There is no public report schema-version field.
| Category | Ordinary | `--quiet` | `--verbose` | `--debug` |
| --- | --- | --- | --- | --- |
| Final report | Shown | Hidden | Shown | Shown |
| Terminal failure | Shown | Shown | Shown | Shown |
| Info and Warning | Hidden | Hidden | Shown | Shown |
| Debug | Hidden | Hidden | Hidden | Shown |
| Progress by default | Hidden | Hidden | Hidden | Shown |
The last enabled quiet/verbose/debug mode wins. Explicit false clears only the
currently selected matching mode, returning to ordinary mode. There is no mode
stack. Independent `--progress` or `--progress=false` overrides the default;
quiet always suppresses progress. Verbose and progress can be combined.
Progress covers stage transitions/reuse, audio transfers/cache reuse, and
individual durable speaker/artifact checkpoints and validated reuse. Info adds
selected sources, destinations, and decision context. Concurrent completion
order is not fixed. Workers settle before the final report.
Console debug does not enable downstream debug captures or change retention.
Downstream streams stay in captured logs and are not replayed automatically.
Quiet changes visibility, not execution, persistence, or logging. A report or
diagnostic delivery failure can fail the invocation after durable work has
completed; it does not roll back that work.
### Public domain report fields
Optional fields appear when meaningful; these reports do not expose raw
manifests, resolved credentials, or internal dependency containers.
| Report | Fields |
| --- | --- |
| Run/regenerate | `campaign`, `session_id`, `run_id`, `stages`, `executed`, `skipped`, `stage_results`, `available_artifacts`, `artifact_targets`, `complete` |
| Plan | `campaign`, `session_id`, `stages` with `name`, `action`, `reason`, optional `analysis`; `publication_actions` |
| Catalog | `artifacts` with source, producer, output, enabled state, dependencies, optional concrete key and family/member/source provenance |
| Validation | `campaign`, `session_id`, `session_source`, `valid`, `findings` with severity, category, message |
| Status/artifacts | Identities/source, `local_manifest`, `stages`, `artifacts`, optional `remote`, configuration provenance, audio/previous-artifact readiness, `findings` |
| Init | `campaign`, `session_id`, `destination`, `remote`, `written` |
| Locks | Identities, `operation`, `result`, `complete`, optional `source`, `locks` |
| Restore | Identities/run, `dry_run`, `complete`, `status`, `downloaded`, `conflicts`, `actions` |
| Clean | Optional identities, `all`, `dry_run`, `complete`, `cache`, `actions`, optional `error` |
Run `stages` is the complete selection. `executed` includes attempted work,
including failures and self-skips. `skipped` includes reuse and self-skips.
Each `stage_results` entry has `name`, `attempted`, `outcome`
(`completed`, `failed`, `reused`, `skipped`, `not_attempted`), and optional
`reason`. Available artifacts carry `stage`, optional `source`, `kind`, `path`,
optional `producer_run_id`, and durable `evidence` (`stage_result`,
`speaker_checkpoint`, `artifact_checkpoint`). Failed or unpersisted work is not
reported as completed.
Plan analysis contains `targets`, `prerequisites`, `execute`, and `reuse`;
artifact entries identify key, optional family/character, role, reason, and
force. Publication actions identify source, destination, required, and selected.
Remote status outputs retain source, destination, required, state, lock state,
optional outcome, declared destination/key, origin run, and error. Restore
actions carry kind, relative local path, remote key, status, optional reason/error.
Clean actions carry path, status (`would_delete`, `deleted`, `missing`, `empty`,
`failed`), and optional error; cache records whether it was preserved, requested,
processed, or not applicable. Lock rows include source, reason, creation time,
and whether publication is configured for that source.
## Cancellation and exit status
Ctrl-C and termination cancel acquisition and active operations. Narratio stops
scheduling work, waits for started workers, attempts terminal local manifest
persistence, and releases acquired resources. Successful checkpoints remain
resumable. Cancellation does not schedule cleanup. Abrupt process death has no
added finalization guarantee.
| Status | Meaning |
| --- | --- |
| `0` | Success, including ordinary diff with differences. |
| `1` | Operational/readiness failure, cancellation, or output failure. |
| `2` | Invalid invocation or identifiable invalid configuration input. |
| `3` | `config diff --check` found differences. |
Missing/unreadable sources and ambiguous or callback loading failures are
operational; malformed or explicitly rejected configuration input uses native
input classification. Mixed failures preserve underlying causes and operational
precedence. Terminal failure is presented once, including in quiet mode.
## Version and completion
```sh
narratio version --format text
narratio version --scope commandkit --format json
source <(narratio completion bash)
source <(narratio completion zsh)
narratio completion fish | source
``` ```
Required target selection: Version text is `NAME VERSION` with an optional revision; structured identity
contains `name`, `version`, and `revision`. Development builds without an embedded
version report `dev`. Bash requires bash-completion initialized; Zsh requires
its completion system initialized. Native completion offers command/flag names,
static stage/scope values, and applicable file/directory hints. Dynamic campaign
and artifact completion is deferred.
- exactly one of: ## Migration from the previous CLI
- `--output <path>`
- `--remote`
Options: Removed command paths have no compatibility aliases.
- `--config <pipeline.yml>` | Previous invocation | Current invocation |
- `--campaign <id>` or `--campaign-file <campaign.yml>` | --- | --- |
- `--secrets-dir <directory>` | `run-stage STAGE SESSION` | `run SESSION --stage STAGE` |
- `--previous-session-id <id>` | `analyze SESSION` | `run SESSION --stage analyze --force` |
- `--date <YYYY-MM-DD>` | `publish SESSION` | `run SESSION --stage publish --force` |
- `--title <text>` | `regenerate-artifacts SESSION` | `artifacts regenerate SESSION` |
- `--audio-dir <path>` | `clean SESSION` / `clean --all` | `session clean SESSION` / `session clean --all` |
- `--audio-s3-prefix <prefix>` | `config artifacts` | `artifacts list` |
- `--force` | `session locks SESSION` | `session locks list SESSION` |
| `--session FILE` | `--session-file FILE`; inspection `--session` now asserts identity |
| `--session-id ID` | Positional `SESSION` on domain commands; `--session ID` on config inspection |
| `config diff LEFT_OVERLAY RIGHT_OVERLAY` | `config diff --overlay LEFT_OVERLAY --against-overlay RIGHT_OVERLAY` |
Rules: Campaign identity and file selectors may now accompany each other. Party-file
selection consistently overrides the roster without editing campaign settings.
- `--audio-dir` and `--audio-s3-prefix` are mutually exclusive. Native configuration inspection retains declarations and their actual evidence;
- if campaign `session_template_file` is configured, `session init` renders it. use catalog/plan/session views for generated domain products. Comparison defaults
- generated session YAML must be concrete (no unresolved `{{ ... }}` placeholders). are independent. Field overrides are inspection-only. Update scripts to consume
- template imports and relative resources resolve in the template's local structured reports and exit classifications, place flags after the complete
authoring context. Generated output contains standalone effective values. command path, and account for native repetition and cancellation behavior.
- relative `--audio-dir` paths resolve from the invocation directory.
### `session restore`
```bash
narratio session restore <session_id> [--dry-run] [--force] [--include-audio] [...common config flags]
```
Behavior:
- discovers committed remote current state;
- plans local restores;
- writes an execution report;
- blocks unresolved conflicts. `--force` permits replacement only of eligible
regular files.
See [Operations: Restore Workflow](./operations.md#restore-workflow) for the
default restore scope, report location, and conflict-handling workflow.
### `session artifacts`
```bash
narratio session artifacts <session_id> [--remote] [...common config flags]
```
Lists effective built-in, configured Scriptorium, and configured extraction
sources; reports planned, available, unavailable, and published state without
reading payload bodies; and includes publish rules, lock state, and optional
remote published-state availability. Remote inspection uses exact commit
declarations and displays the five current publish outcomes when recorded.
### `session locks`
```bash
narratio session locks <session_id> [...common config flags]
narratio session locks add <session_id> <source> [--reason <text>] [--force] [...common config flags]
narratio session locks remove <session_id> <source> [...common config flags]
```
Behavior:
- list mode validates and reports independent remote locks sorted by source;
- add creates one lock and reports an existing lock unless `--force` is used;
- `--force` performs one generation-matched replacement and reports a
concurrent change for operator retry; and
- remove is idempotent and reports when the source was not locked.
See [Operations: Publish Locks](./operations.md#publish-locks) for lock storage
and publication behavior.
## `--artifacts` Selection Rules
An artifact-family key selects all of its concrete character members. A
concrete generated key selects only that member; mixed family and concrete
selection is deduplicated and executed as concrete keys. The resulting plan
and command output identify both the concrete key and, where applicable, its
family and character ID.
- accepted on `run`, `session plan`, `run-stage`, `analyze`, and `publish`;
- repeatable and comma-separated values are combined, surrounding whitespace
is removed, and duplicate names are collapsed;
- names must exist in `pipeline.scriptorium.artifacts`;
- empty entries are invalid;
- on `run-stage`, only `analyze` and `publish` accept the option.
Effects:
- selects explicit analyze targets; required configured prerequisites may be
reused or rebuilt before them;
- filters publish rules that source `narratio.artifact.<name>`;
- does not filter built-in transcript/bounds or explicitly configured
`narratio.extraction.<name>` publish sources; and
- does not select or filter Notarius lanes.
## Common Workflows
Run full pipeline:
```bash
narratio run 2026-04-04
```
Dry-run restore plan:
```bash
narratio session restore 2026-04-04 --dry-run
```
Generate a concrete session file from template/default structure:
```bash
narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"
```
Force publish only:
```bash
narratio publish 2026-04-04
```
Regenerate post-transcript artifacts without publishing:
```bash
narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout
```
## Output And Exit Behavior
- Successful commands write their result or summary to standard output and
exit with status `0`.
- Command failures and invalid invocations write an error to standard error and
exit with status `1`.
- An unknown top-level command also prints the top-level usage summary to
standard error.
- `session restore --help` prints its command-specific usage and exits with
status `0`.
Output is intended for operator inspection. Narratio does not currently offer
a machine-readable CLI output mode; durable machine-readable state is recorded
in manifests and reports described in [Operations](./operations.md).

View File

@@ -2,7 +2,8 @@
## Purpose ## Purpose
Narratio resolves three YAML documents: Narratio loads pipeline, campaign, and session YAML, with a canonical party
roster selected explicitly or through the campaign:
- `pipeline.yml`: pipeline/runtime settings - `pipeline.yml`: pipeline/runtime settings
- `campaign.yml`: campaign identity and stable input defaults - `campaign.yml`: campaign identity and stable input defaults
@@ -37,7 +38,8 @@ Selection rules:
### `session.yml` ### `session.yml`
When `--session` is omitted, local search order is: An explicit `--session-file` selects exactly that file. Otherwise local search
order is:
1. `/usr/local/etc/narratio/session.yml` 1. `/usr/local/etc/narratio/session.yml`
2. `/etc/narratio/session.yml` 2. `/etc/narratio/session.yml`
@@ -52,43 +54,36 @@ from `session init --remote --force`. When that object is absent, loading falls
back to the current commit's standalone prepared session. Published snapshots back to the current commit's standalone prepared session. Published snapshots
remain immutable; restore validates the pointer-selected committed state. remain immutable; restore validates the pointer-selected committed state.
### Read-only effective pipeline inspection ### Native inspection and domain derivation
`narratio config validate`, `narratio config show`, `narratio config sources`, Native configuration inspection exposes four actual typed ConfigKit results:
and `narratio config artifacts` use the same `--config`, `--campaign`, app (the default pipeline scope), campaign, session, and party. Defaults,
`--campaign-file`, and normalization, and configuration-owned validation finish within their supported
`--overlay` selection rules as pipeline commands, but do not select, discover, load lifecycle. Session configuration includes applicable campaign defaults
or load a session. They resolve configured typed credential references as part before handoff. Completed values remain unchanged by planning or execution.
of the ordinary ConfigKit load but expose only their environment-variable names;
they do not create runtime state.
`narratio config diff <left-overlay> <right-overlay>` uses the same pipeline and
campaign selectors, resolves each named overlay with an independent ConfigKit
load, and does not accept a separate `--overlay` flag.
Campaign selection is optional only when the resolved pipeline has no App inspection retains artifact-family declarations and needs no campaign or
`scriptorium.artifact_families`. When families are declared, Narratio selects a party solely for expansion. Narratio derives concrete artifact catalogs, players,
campaign through an explicit flag or `pipeline.campaigns.default_campaign_id`, resolved dependencies, and publication actions separately using the selected
then parses the campaign-owned party and expands concrete artifacts and any canonical roster. `artifacts list` inspects those domain definitions;
family publish rules before validation. `config validate` prints the resulting `session plan` and `session artifacts` expose decisions and availability.
root, overlay, and effective digest. `config show` emits the normalized
effective pipeline YAML, with defaults and concrete expansion included but
ConfigKit directives and family declarations omitted. This review projection is
not promised to be a reloadable authoring document. `config sources` prints a stable
source projection instead of effective values: root/import/overlay/default
ownership plus campaign/party and generated-family records. Canonical derived
players trace to the party. `config artifacts` lists the concrete artifact map,
effective dependencies, and definition contributor paths, which may identify
several files for one family member. The [CLI reference](cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff)
owns command syntax and output conventions.
`config diff` compares normalized field values rather than YAML text or source Native sources/explanations retain actual imports, origins, history, and recorded
ownership. It emits native ordered `added`, `removed`, and `changed` records with resolution evidence. Comparisons load each side independently using its own
JSON Pointer paths and compact JSON values. Lists are compared atomically, and normal defaults. App-only inspection overrides apply during that invocation's
changed regions may contain whole values. It reports `no differences` when the load. Safe views hide resolved credentials. Persisted preparation projections
complete effective configurations are equal. Concrete retain reference names and do not replace the native inspection result.
family members and generated publish rules participate after expansion; moving See the [CLI reference](cli.md#configuration-inspection) for scopes, selectors,
an equal value between eligible root/import sources does not create a path operations, overrides, comparison modes, and report shapes.
difference.
### Party selection
`--party-file` selects an exact canonical roster instead of the campaign-default
file. Explicit relative paths use the invocation directory; invalid or missing
explicit input fails without fallback. The campaign's configured party field
remains unchanged. Inspection, players, family derivation, planning, and execution
use the same selected roster. Format and validation belong in the
[party integration contract](integrations/party.md).
### Migrating to the maintained bundle ### Migrating to the maintained bundle
@@ -99,7 +94,8 @@ in the fixed `overlays/testing.yml` overlay. Put ordinary artifacts and families
in the recommended one-definition files shown by that bundle. Convert campaign in the recommended one-definition files shown by that bundle. Convert campaign
rosters to [canonical party input](integrations/party.md), then express character rosters to [canonical party input](integrations/party.md), then express character
work as families. Inspect the result with `config validate`, `config show`, work as families. Inspect the result with `config validate`, `config show`,
`config sources`, and `config artifacts`; use `config diff default testing` to `config sources`, and `artifacts list`; use
`config diff --against-overlay testing` to
review the overlay before running a session. Unversioned party documents are review the overlay before running a session. Unversioned party documents are
rejected. rejected.
@@ -135,9 +131,10 @@ remote state with an unsafe legacy identity must be migrated before use.
`party_file`) are campaign-owned; the first three may be overridden by the `party_file`) are campaign-owned; the first three may be overridden by the
session. The optional `spell_catalog_file` also inherits a campaign value session. The optional `spell_catalog_file` also inherits a campaign value
when omitted by the session. when omitted by the session.
- `party_file` is parsed when pipeline and campaign configuration are combined. - The selected party is parsed when domain context or party inspection needs
It must be a versioned [canonical party](integrations/party.md), is it. It must be a versioned [canonical party](integrations/party.md). The
campaign-owned and derives the players input internally. `players_file` and campaign supplies its default file; an explicit CLI selection replaces it
for the invocation and supplies the derived players input. `players_file` and
session `party_file` are unsupported configuration keys. session `party_file` are unsupported configuration keys.
- Exactly one audio mode must be configured in session input: - Exactly one audio mode must be configured in session input:
- local (`audio_dir` or `audio_files`), or - local (`audio_dir` or `audio_files`), or
@@ -626,19 +623,19 @@ does not provide adapter-specific input passthrough fields.
Each `narratio.artifact.<name>` input source automatically contributes an Each `narratio.artifact.<name>` input source automatically contributes an
effective dependency on that configured artifact. Narratio unions these inferred effective dependency on that configured artifact. Narratio unions these inferred
edges with explicit `depends_on` entries, then trims, deduplicates, and sorts the edges with explicit `depends_on` entries, then trims, deduplicates, and sorts the
result during final configuration resolution. Authors use `depends_on` only for result during domain catalog derivation. Authors use `depends_on` only for
ordering constraints that are not already expressed by an artifact input. ordering constraints that are not already expressed by an artifact input.
Use [`narratio config artifacts`](./cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff) Use [`narratio artifacts list`](./cli.md#artifacts-list)
to inspect keys, definition sources, outputs, and effective dependencies without to inspect keys, definition sources, outputs, and effective dependencies without
loading a session or creating runtime state. loading a session or creating runtime state.
### Scriptorium Artifact Families ### Scriptorium Artifact Families
`pipeline.scriptorium.artifact_families` declares a shared artifact template `pipeline.scriptorium.artifact_families` declares a shared artifact template
for every canonical campaign character. Configuration resolution expands each for every canonical campaign character. Domain catalog derivation expands each
family into ordinary `pipeline.scriptorium.artifacts` entries before analyze family into separate concrete artifact entries before analyze planning or
planning or Scriptorium invocation. Party parsing rejects unsupported document Scriptorium invocation, retaining the authored declarations in configuration.
schemas before family expansion. Party parsing rejects unsupported document schemas before family expansion.
For each `pipeline.scriptorium.artifact_families.<name>`: For each `pipeline.scriptorium.artifact_families.<name>`:

View File

@@ -58,16 +58,16 @@ Configured definitions are always registered. Without an explicit selection,
the effective analyze set contains enabled definitions. With `--artifacts`, the the effective analyze set contains enabled definitions. With `--artifacts`, the
exact named configured definitions become the effective set for that invocation, exact named configured definitions become the effective set for that invocation,
regardless of their `enabled` value. The effective-set resolver itself does not regardless of their `enabled` value. The effective-set resolver itself does not
expand dependencies. Configuration has already materialized the sorted union of expand dependencies. Shared domain catalog derivation has materialized the sorted
explicit ordering edges and configured-artifact input edges, and the analyze union of explicit ordering edges and configured-artifact input edges, and the analyze
work planner closes targets over that one concrete prerequisite graph. work planner closes targets over that one concrete prerequisite graph.
Availability is separate from executability. Configuration may normalize a Availability is separate from executability. Invocation selection normalizes a
family selection into its concrete generated members before this resolver runs. family selection into its concrete generated members before this resolver runs.
The effective set retains optional family The effective set retains optional family
and character origin metadata, but its keys, catalog sources, and runtime and character origin metadata, but its keys, catalog sources, and runtime
lookups remain concrete configured-artifact identities. lookups remain concrete configured-artifact identities.
Family publish policies are likewise expanded into ordinary configured-source Family publish policies are likewise expanded into ordinary configured-source
publish rules during configuration resolution. publish actions during domain catalog derivation.
Configured outputs, including non-executable prerequisites, become available Configured outputs, including non-executable prerequisites, become available
only when the versioned analyze state identifies a current result whose source, only when the versioned analyze state identifies a current result whose source,
contract, canonical configured path, size, and checksum match a confined contract, canonical configured path, size, and checksum match a confined

View File

@@ -2,100 +2,94 @@
User-visible fields, defaults, discovery, and selection belong in the User-visible fields, defaults, discovery, and selection belong in the
[Configuration Reference](../config.md). This document describes the [Configuration Reference](../config.md). This document describes the
`internal/config` loading and resolution boundary. `internal/config` loading and derivation boundary established by
[ADR 0003](../adr/0003-assign-configuration-ownership.md).
## Pipeline Loading ## Typed Configuration Handoff
Commands bootstrap secrets once before loading, then select an explicit file or Pipeline, campaign, session, and party loaders retain their actual typed
native required discovery. ConfigKit loads typed defaults, source-root imports, ConfigKit results. ConfigKit owns imports, overlay composition, inheritance,
and the selected overlay, resolves inheritance, and strictly decodes the presence, typed secrets, and native source/history evidence. Narratio's
result. Narratio applies recorded defaults, normalization, resource resolution, supported definition callbacks complete configuration-owned defaults,
and effective-domain validation. The selected root, source contexts, metadata, normalization, resource resolution, and validation before handoff. Consumers
and authoring result are retained for provenance. Family expansion and checks read completed values without mutation.
requiring the campaign occur after campaign and party resolution.
Resource resolution consults native entry origins and source contexts before Session definitions receive selected-campaign defaults before loading finishes.
normalization. An effective source supplies the base when usable; otherwise the Recorded resolution preserves explicit empty/null/false/zero behavior and
main source, then the captured invocation directory, is the fallback. Explicit truthful dependencies. Identity and previous-session assertions are separate
CLI file references use the invocation directory. Derived values record their request checks against completed values. Standalone document renderers preserve
dependencies. See the [configuration reference](../config.md#pipeline-imports-and-overlays) materialization semantics without providing a second inspection authority.
for the resource classifications and native authoring contract.
## Loaded Context Resolution Resource resolution consults native entry origins and source contexts. A usable
effective source supplies the base, otherwise the main source and then captured
invocation directory provide the fallback. Explicit CLI paths use the invocation
directory. See [resource rules](../config.md#pipeline-imports-and-overlays).
`LoadedPipelineCampaign` carries the selected pipeline and campaign into local ## Invocation Acquisition
or remote session resolution. Local campaign, session, and party loads enable
imports through their own ConfigKit definitions; only the pipeline selects an
overlay. Native optional search distinguishes an absent local session from an
invalid selected file. Remote session bytes have no incidental download-directory
context, and retain object provenance. Effective session strings are checked for
unresolved template tokens, and campaign/session identity and stable-input rules
remain Narratio-owned.
Campaign and session loaders retain detached document values after their own `internal/app/configuration_acquisition.go` owns lazy invocation selections and
resolution. The session document is captured before campaign defaults are copied acquired context. Exact sources and effective-identity assertions are
into runtime session state. Configuration-owned renderers produce standalone complementary. App acquisition needs no campaign or party for expansion;
campaign and session YAML, preserving omitted session overrides. Prepare uses campaign acquisition needs no session. Session acquisition loads campaign
those renderers and canonical party rendering for materialization and resume context when required for defaults. Explicit party acquisition does not require
comparison. a session. Credential bootstrap runs once per reached invocation after static
input checks.
## Inspection And Provenance `LoadedPipelineCampaign` retains one selected pipeline/campaign while local or
remote session resolution proceeds. Only absence permits remote fallback;
access, decoding, and identity failures retain their causes. Remote acquisition
prefers authored session-root input and uses the committed prepared snapshot
only when authored input is absent. Temporary materialization retains object
provenance and releases resources on success or failure. Read-only acquisition
creates no runtime workspace, execution lock, restore state, or stage adapter.
Read-only inspection shares production pipeline and campaign selection without ## Native Inspection
session discovery, workspace initialization, adapters, or manifest access. After
applicable campaign and family resolution, a safe typed final-domain DTO contains
concrete artifacts and generated publish rules. It stores credential reference
names rather than typed secrets. A defaults-backed native result freezes this
DTO without resolving credentials again; `WriteEffective` supplies show and
prepared pipeline YAML, and deterministic JSON of the same DTO supplies the
versioned semantic digest. Resolved resources participate in that digest, while
source layout and secret values do not.
Authoring results separately supply native origins, source histories, and empty `configuration_commands.go` adapts actual results with `ckconfig.FromConfigKit`.
optional-import evidence to source and artifact inspection. Family and party Native show, sources, explain/history, validation, and comparisons consume that
context identifies generated entries without reparsing sources. Diff fully result's values and evidence. There is no flattened replacement snapshot,
resolves each side against the same selected campaign and party, then uses synthetic source reconciliation, or generated family catalog in app inspection.
ConfigKit `Diff` on the safe snapshots. The command presents native JSON Pointer
paths and safe compact values.
## Canonical Party Domain Comparison sides load independently using each side's normal defaults and
selectors. App-only overrides pass through native selection into ConfigKit;
they remain invocation-local. Field overrides are unavailable to domain
execution/planning and other scopes. Shared bootstrap does not imply shared
overridden results. Public inspection and error paths preserve typed-secret
redaction and credential reference metadata.
File-backed party loading enables imports; `ParseParty` accepts contextless bytes. ## Canonical Party And Derived Catalog
The shared definition checks the main document's version and Narratio validates
the effective character roster. Native acquisition order and source coordinates
establish roster order, favoring each child's own declaration. A deterministic
renderer writes standalone canonical party YAML from that roster; the players
projection and family expansion use the same resolved roster. The external format
is defined in the [party contract](../integrations/party.md).
## Validation Ownership File-backed party loading supports imports; contextless `ParseParty` accepts
bytes. The definition checks the main version and effective roster. Native
source coordinates establish roster order, favoring each child's declaration.
A deterministic renderer materializes canonical party YAML. The selected roster
supplies both the players projection and concrete family members, including when
an explicit party file replaces the campaign default.
ConfigKit owns composition, inheritance, presence, typed-secret resolution, and `ArtifactCatalog` carries derived artifacts, family/member origins, resolved
provenance. Narratio owns validation and normalization of effective domain dependencies, and expanded publication outputs separately from pipeline values.
values. Source histories are inspection evidence, not an additional acceptance Family declarations remain in the typed pipeline result. Derivation sorts
gate. Focused configuration and application tests exercise imports, resource family keys and character IDs, substitutes `{character_id}` in outputs,
contexts, snapshots, secret-safe inspection, party resolution, and materialized resolves closed member variables, and checks key/output collisions and domain
inputs through the production boundaries. dependencies. Member-artifact inputs become ordinary concrete artifact sources;
family publish declarations become ordinary publication actions. No family
wildcard matcher is added to runtime publication.
## Artifact Family Resolution Catalog listing, planning, stage execution, artifact inspection, fingerprinting,
and previous-session requirements consume the same derived products. Validation
of these products belongs to domain derivation rather than app inspection.
External roster shape belongs in the [party contract](../integrations/party.md).
Pipeline loading retains `scriptorium.artifact_families` as a resolution-only ## Safe Persistence And Semantic Resume
declaration. Once campaign party resolution establishes a canonical roster,
configuration expands families in sorted family-key and character-ID order
into ordinary `ScriptoriumArtifactConfig` values. The expansion owns the narrow
`{character_id}` output substitution, closed member-variable selectors, key and
output collision checks, and the runtime-only family-origin catalog. It then
removes family declarations from `ScriptoriumConfig`, runs ordinary Scriptorium
validation, and refreshes the effective pipeline digest. Stages and adapters
therefore receive only concrete artifact maps.
The catalog retains sorted family member keys plus family/character/source Preparation materializes standalone campaign/session/party/players inputs and
origins and the typed dependency/publish declarations for their later owners. a secret-safe pipeline projection. The projection preserves credential names,
`member_dependencies` add corresponding ordinary concrete dependencies, while family declarations, numeric values, and null/empty distinctions. It is a
the family-only `narratio.member_artifact.<family>` input form is rewritten to persistence service, not a fabricated native result. An effective digest is
the matching ordinary configured-artifact source. The catalog records those informational; resume compares result-affecting semantic evidence from the same
resolved dependency and input identities with their declaring family and party concrete products used by execution. Source arrangement, provenance, and overlay
member. No member-artifact source is registered as a runtime policy source. labels alone do not invalidate work.
An enabled family publish declaration expands to ordinary configured-artifact
publish rules before the existing publish and lock validators run. Runtime Focused configuration/application fixtures cover imports, defaults, selected
publication consequently receives no family wildcard or special matcher. rosters, independent comparisons, override isolation, secret-safe persistence,
and unchanged completed configuration across domain derivation and execution.

View File

@@ -373,4 +373,4 @@ where the last session transition can require operator interpretation.
- Transcribe speaker state: `internal/manifest/transcribe_state.go` - Transcribe speaker state: `internal/manifest/transcribe_state.go`
- Package tests: `internal/manifest/*_test.go` - Package tests: `internal/manifest/*_test.go`
- Assembled execution behavior: `internal/app/runner_test.go`, - Assembled execution behavior: `internal/app/runner_test.go`,
`internal/app/run_stage_test.go` `internal/app/run_selection_test.go`

View File

@@ -16,7 +16,8 @@ cmd/narratio -> internal/app -> configuration and production composition
-> manifests and artifact resolution -> durable local/remote output -> manifests and artifact resolution -> durable local/remote output
``` ```
The executable delegates process behavior to the application boundary. The The executable supplies signal-aware context and caller-owned streams to the
native CommandKit application boundary. The
application resolves configuration, composes concrete collaborators, acquires application resolves configuration, composes concrete collaborators, acquires
session safety controls, and runs commands. Pipeline commands execute the session safety controls, and runs commands. Pipeline commands execute the
canonical stage sequence through adapter interfaces, while manifests record canonical stage sequence through adapter interfaces, while manifests record
@@ -26,8 +27,10 @@ The pipeline runner follows one explicit invocation lifecycle: inspect bounded
prerequisites without mutation, prepare the workspace layout, acquire one prerequisites without mutation, prepare the workspace layout, acquire one
session lock, load or create the authoritative session manifest, compose only session lock, load or create the authoritative session manifest, compose only
the collaborators needed by the selected range, execute each selected stage in the collaborators needed by the selected range, execute each selected stage in
order, and then return the summary. Cleanup, when selected, is the ordinary order, finalize terminal state, release resources, and return a possibly partial
final stage rather than runner finalization work. summary with preserved failure causes. Narrow terminal local persistence detaches
cancellation; active work retains the canceled operation context. Cleanup, when
selected, is the ordinary final stage rather than runner finalization work.
The lock remains held from manifest initialization through finalization, and a The lock remains held from manifest initialization through finalization, and a
failed stage or required manifest save prevents later stages from starting. failed stage or required manifest save prevents later stages from starting.
@@ -36,8 +39,8 @@ failed stage or required manifest save prevents later stages from starting.
| Area | Implemented owners | Responsibility | | Area | Implemented owners | Responsibility |
| --- | --- | --- | | --- | --- | --- |
| Executable | `cmd/narratio` | Process entry, standard stream wiring, argument handoff, and exit status. | | Executable | `cmd/narratio` | Process entry, standard stream wiring, argument handoff, and exit status. |
| Application orchestration | `internal/app` | Command dispatch, configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, and user-facing reporting. | | Application orchestration | `internal/app` | Native CommandKit declarations/reporting, lazy configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, and user-facing reporting. |
| Configuration | [`internal/config`](configuration.md) | ConfigKit-backed pipeline imports and overlays, canonical party and family expansion, strict YAML loading, defaults, normalization, session templating, and validation. | | Configuration | [`internal/config`](configuration.md) | Typed ConfigKit results and lifecycle defaults, imports/overlays, canonical party loading, separate catalog/player/publication derivation, session templating, and validation. |
| Pipeline stages | `internal/stage` | Canonical stage registry, shared stage contract, execution dependencies, and implemented stage behavior. | | Pipeline stages | `internal/stage` | Canonical stage registry, shared stage contract, execution dependencies, and implemented stage behavior. |
| External boundaries | `internal/adapters`, `internal/audio` | WhisperX HTTP, downstream subprocesses, notification, object storage, and S3 audio materialization behind Narratio contracts. | | External boundaries | `internal/adapters`, `internal/audio` | WhisperX HTTP, downstream subprocesses, notification, object storage, and S3 audio materialization behind Narratio contracts. |
| Manifests | `internal/manifest` | Durable session progress, stage transitions, validation, and atomic persistence. | | Manifests | `internal/manifest` | Durable session progress, stage transitions, validation, and atomic persistence. |
@@ -45,7 +48,7 @@ failed stage or required manifest save prevents later stages from starting.
| Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. | | Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. |
| Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. | | Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. |
| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus atomic single-file replacement, bounded reads, workspace modes, and root-scoped cleanup helpers. | | Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus atomic single-file replacement, bounded reads, workspace modes, and root-scoped cleanup helpers. |
| Logging | `internal/logging` | Application logger construction and shared structured logging behavior. | | Logging | `internal/logging` | Small Narratio-owned diagnostic/progress interface adapted to the invocation reporter. |
The application boundary composes concrete implementations. Stages depend on The application boundary composes concrete implementations. Stages depend on
Narratio-level contracts; external transport and SDK details remain in Narratio-level contracts; external transport and SDK details remain in
@@ -137,4 +140,4 @@ before changing behavior.
The stage registry is implemented in `internal/stage/placeholders.go` and its The stage registry is implemented in `internal/stage/placeholders.go` and its
ordering is protected by `internal/app/planner_test.go`. Cross-invocation skip, ordering is protected by `internal/app/planner_test.go`. Cross-invocation skip,
force, failure, and invalidation behavior is exercised in force, failure, and invalidation behavior is exercised in
`internal/app/runner_test.go` and `internal/app/run_stage_test.go`. `internal/app/runner_test.go` and `internal/app/run_selection_test.go`.

View File

@@ -53,7 +53,7 @@ Supported source families:
manifest record and durable output pass the configured-artifact evidence manifest record and durable output pass the configured-artifact evidence
contract; an incidental or stale canonical file is unavailable. contract; an incidental or stale canonical file is unavailable.
- validates selected artifact dependency order (cycle-safe topo ordering). - validates selected artifact dependency order (cycle-safe topo ordering).
- consumes only the concrete dependency graph finalized by configuration; - consumes only the concrete dependency graph derived in the shared domain catalog;
planning, prerequisite closure, execution, reuse, invalidation, and semantic planning, prerequisite closure, execution, reuse, invalidation, and semantic
evidence do not infer a second graph from inputs. evidence do not infer a second graph from inputs.
- resolves required/optional inputs per artifact source definition into an - resolves required/optional inputs per artifact source definition into an

View File

@@ -39,9 +39,9 @@ stage non-resumable. A failure is recorded against cleanup; publish remains
succeeded and remote current state is unchanged. On a later normal full run, succeeded and remote current state is unchanged. On a later normal full run,
valid upstream stages are skipped and cleanup is retried without republishing. valid upstream stages are skipped and cleanup is retried without republishing.
`narratio publish` selects publish only and never invokes cleanup. A bounded run `narratio run SESSION --stage publish` selects publish only and never invokes cleanup. A bounded run
through `notify` or any earlier endpoint also excludes it. Operators may run through `notify` or any earlier endpoint also excludes it. Operators may run
`narratio run-stage cleanup <session_id>` directly; missing, failed, malformed, `narratio run <session_id> --stage cleanup` directly; missing, failed, malformed,
or identity-mismatched publication evidence fails before deletion. or identity-mismatched publication evidence fails before deletion.
## Implementation And Tests ## Implementation And Tests

View File

@@ -129,7 +129,7 @@ evidence does not replace those safety checks.
The commit boundary and cleanup authorization are normative architecture invariants; see The commit boundary and cleanup authorization are normative architecture invariants; see
[Architecture](../policy/architecture.md#publish-commit-boundary). [Architecture](../policy/architecture.md#publish-commit-boundary).
Publish never deletes local state. The standalone `publish` command selects Publish never deletes local state. `run SESSION --stage publish` selects
only this stage; a full run selects notify and cleanup afterward. only this stage; a full run selects notify and cleanup afterward.
## Related Contracts And Tests ## Related Contracts And Tests

View File

@@ -72,7 +72,7 @@ The canonical cleanup stage:
republishing. republishing.
Manual cleanup uses the same root-confined deletion mechanism. Invocation Manual cleanup uses the same root-confined deletion mechanism. Invocation
syntax and exact deletion scope belong in [CLI](../cli.md#clean) and syntax and exact deletion scope belong in [CLI](../cli.md#session-clean) and
[Operations](../operations.md#cleanup). [Operations](../operations.md#cleanup).
## Invariants ## Invariants

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 and Session Selection
Campaign selection priority: Identity and exact-file selection are complementary: a selected file supplies
configuration and an explicit ID asserts its effective identity. Session domain
- `--campaign-file` commands take positional identity; `--session-file` selects its source. An
- `--campaign` explicit `--party-file` supplies the roster consistently across consumers.
- `pipeline.campaigns.default_campaign_id` See [CLI selectors](cli.md#configuration-selectors) and
[configuration discovery](config.md#discovery-and-selection) for selection rules.
Session source priority: Existing scripts should follow the [CLI migration table](cli.md#migration-from-the-previous-cli).
- `--session`
- local default search paths
- remote session object (S3) when local session file is not found and storage is configured
## Session Initialization ## Session Initialization
@@ -70,21 +66,19 @@ narratio run 2026-04-04
narratio session status 2026-04-04 narratio session status 2026-04-04
``` ```
Run, plan, and status output identify the resolved pipeline overlay (or `none`) Status distinguishes currently resolved configuration provenance from the last
and effective configuration digest. Status distinguishes the current resolved persisted configuration, helping diagnose overlay switches without changing
value from the last value persisted in the session manifest, which helps semantic resume authority. Run and plan reports describe execution and decisions;
diagnose overlay switches without changing resume authority. see the [report fields](cli.md#public-domain-report-fields).
Before switching an operational overlay, compare its effective meaning with the Before switching an operational overlay, compare its effective configuration
production base through `narratio config diff default <overlay>`. with the base through `narratio config diff --against-overlay NAME`. When using an
The command is read-only and succeeds whether it finds differences or not. Its explicit root, supply it with both `--config` and `--against-config`. Each side
sorted records describe defaulted, expanded concrete configuration—not source loads independently using its own defaults. Native inspection retains authored
file layout—so it can be used to review model, artifact, and publish changes family declarations; use `narratio artifacts list` to review concrete identities,
without creating a session or run. Use `narratio config artifacts` to review the outputs, dependencies, and selected-party members. See
concrete artifact identities, definitions, outputs, and dependencies. Select the [configuration inspection](cli.md#configuration-inspection) for selection and
same campaign explicitly when overlays could resolve different campaign paths; comparison details.
see the [CLI reference](cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff)
for syntax and record format.
## Stage Execution and Continuation Behavior ## Stage Execution and Continuation Behavior
@@ -148,7 +142,7 @@ the stage self-skip.
Single-stage execution: Single-stage execution:
```bash ```bash
narratio run-stage normalize 2026-04-04 --force narratio run 2026-04-04 --stage normalize --force
``` ```
Contiguous bounded execution uses inclusive canonical endpoints: 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: After correcting the underlying problem, retry normally:
```bash ```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, 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: URL and language:
```bash ```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 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 | | 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 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 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 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. | | 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 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: For the extraction-plus-analysis development loop, use:
```bash ```bash
narratio regenerate-artifacts 2026-04-04 narratio artifacts regenerate 2026-04-04
narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout 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 `extract` through `analyze`. Extraction always rebuilds its complete configured
bundle. Analysis rebuilds the selected targets and their required analysis bundle. Analysis rebuilds the selected targets and their required analysis
prerequisites, or uses the normal default selection when no artifact names are prerequisites, or uses the normal default selection when no artifact names are
@@ -268,7 +262,7 @@ set is ready:
```bash ```bash
narratio session artifacts 2026-04-04 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 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 Narratio cannot observe edits inside Notarius configuration behind an unchanged
selector. Force extraction after such an edit when a replacement is intended. selector. Force extraction after such an edit when a replacement is intended.
Use `regenerate-artifacts` when both extraction and analysis must be rebuilt; Use `artifacts regenerate` when both extraction and analysis must be rebuilt;
use `analyze` when the existing extraction bundle should be preserved. Field use `run SESSION --stage analyze --force` when the existing extraction bundle
should be preserved. Field
semantics belong in [Configuration](./config.md#notarius-configuration-overlay), semantics belong in [Configuration](./config.md#notarius-configuration-overlay),
with Audita selectors covered under with Audita selectors covered under
[Audita selection and credentials](./config.md#audita-selection-and-credentials). [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 member only. Manifests and plan output retain the concrete key as the durable
identity and include the family and character ID as optional provenance. identity and include the family and character ID as optional provenance.
`--artifacts` can be used on `run`, `session plan`, `run-stage`, `analyze`, and `--artifacts` can be used on `run`, `session plan`, and
`publish`. For a bounded run or plan, the selected range must contain `analyze` `artifacts regenerate`. For a bounded run or plan, the selected range must contain `analyze`
or `publish`. or `publish`.
Selection behavior: 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 - selects explicit analyze targets and permits their required configured
prerequisites to be reused or rebuilt first; prerequisites to be reused or rebuilt first;
- filters publish rules for `narratio.artifact.<name>` sources only; - 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: the source configuration and refresh prepared state first:
```bash ```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 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, Narratio's polish resume evidence tracks selected config path, Audita overlay,
profiles, ordered modules, description, schema, and output identity. Editing profiles, ordered modules, description, schema, and output identity. Editing
Audita-owned files behind unchanged selectors is invisible to Narratio; force 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 ## External Command Lifecycle
@@ -581,7 +576,7 @@ the committed manifest and declared transcript/artifact objects.
To intentionally replace the current extraction result, run: To intentionally replace the current extraction result, run:
```bash ```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, Narratio automatically reruns extraction when its recorded invocation contract,
@@ -610,16 +605,10 @@ before commit selection.
Run publish only: Run publish only:
```bash ```bash
narratio publish 2026-04-04 narratio run 2026-04-04 --stage publish --force
``` ```
Equivalent: This selection stops after publish and does not invoke cleanup. A
```bash
narratio run-stage publish 2026-04-04 --force
```
This standalone command stops after publish and does not invoke cleanup. A
default full `run` continues through notify and cleanup. default full `run` continues through notify and cleanup.
Publish commit model: Publish commit model:
@@ -689,7 +678,7 @@ Operational rules:
Examples: Examples:
```bash ```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 add 2026-04-04 narratio.artifact.session_recap --reason "manual edits" --force
narratio session locks remove 2026-04-04 narratio.artifact.session_recap narratio session locks remove 2026-04-04 narratio.artifact.session_recap
``` ```
@@ -847,20 +836,20 @@ the session workload.
Session-scoped cleanup: Session-scoped cleanup:
```bash ```bash
narratio clean 2026-04-04 narratio session clean 2026-04-04
``` ```
Global cleanup: Global cleanup:
```bash ```bash
narratio clean --all narratio session clean --all
``` ```
Dry-run and cache variants: Dry-run and cache variants:
```bash ```bash
narratio clean 2026-04-04 --dry-run --clear-cache narratio session clean 2026-04-04 --dry-run --clear-cache
narratio clean --all --dry-run --clear-cache narratio session clean --all --dry-run --clear-cache
``` ```
Rules: 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 uses root-confined deletion, and does not read or mutate object storage. A
failure leaves publish succeeded and the remote committed snapshot current. failure leaves publish succeeded and the remote committed snapshot current.
Retry with a normal full run: valid upstream work, including publish and notify, 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 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. state.
Older local manifests that contain the retired cleanup-obligation field are 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. - Restore requires configured object storage and committed remote current state.
- Pipeline-loading commands bootstrap filesystem secrets once before configuration - Pipeline-loading commands bootstrap filesystem secrets once before configuration
resolution and object-store initialization. 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.

View File

@@ -265,7 +265,7 @@ rereads remote storage. A cleanup failure makes the invocation incomplete while
leaving publish succeeded and the committed remote snapshot authoritative. A leaving publish succeeded and the committed remote snapshot authoritative. A
normal later full run reuses valid upstream stages and retries cleanup. normal later full run reuses valid upstream stages and retries cleanup.
The standalone `publish` command selects only publish and therefore never `run SESSION --stage publish` selects only publish and therefore never
invokes cleanup. Operators may select cleanup directly only when the manifest invokes cleanup. Operators may select cleanup directly only when the manifest
contains valid successful publication evidence. contains valid successful publication evidence.

View File

@@ -792,6 +792,16 @@ contracts, deliberate migration guidance, or immutable historical records.
## Stage 20: Update canonical documentation and migration workflows ## Stage 20: Update canonical documentation and migration workflows
**Completed.** Rewrote the CLI reference for the native command tree, selectors,
inspection/comparison/override behavior, public reports, visibility, completion,
cancellation, and exit classifications. Updated configuration/domain ownership,
operator and troubleshooting workflows, maintained examples, README, and current
publication-policy references while preserving accepted ADRs and release history.
Audited actual runtime/test imports against existing pinned dependency notices;
no additional incorporated components were missing. The offline example
walkthrough, documentation links, maintained configuration examples, native
version/release-builder tests, and diff checks pass with Go 1.27.4.
Read: documentation and OSS policies, roadmap migration requirements, current Read: documentation and OSS policies, roadmap migration requirements, current
CLI/config/operations/internal owners, maintained examples, and release scripts. CLI/config/operations/internal owners, maintained examples, and release scripts.

View File

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

View File

@@ -26,17 +26,22 @@ in the [configuration reference](../docs/config.md).
Inspect it offline with: Inspect it offline with:
```sh ```sh
narratio config validate --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml narratio config validate --config examples/production-testing/pipeline.yml
narratio config show --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing narratio config show --config examples/production-testing/pipeline.yml --overlay testing
narratio config sources --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing narratio config sources --config examples/production-testing/pipeline.yml --overlay testing
narratio config artifacts --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing narratio artifacts list --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing
narratio config diff default testing --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml narratio config diff --against-config examples/production-testing/pipeline.yml --against-overlay testing --config examples/production-testing/pipeline.yml
``` ```
These inspection commands load configuration and resolve explicit credential These inspection commands load configuration and resolve explicit credential
references, but do not load a session or create runtime state. This bundle is references, but do not load a session or create runtime state. This bundle is
intentionally local-storage and credential-reference free so the walkthrough intentionally local-storage and credential-reference free so the walkthrough
needs no tools or cloud services. needs no tools or cloud services. Native app inspection retains family
declarations; `artifacts list` derives their concrete members using the selected
campaign. Diff selects the example root on both sides because omitted
right-side selectors use their own discovery defaults. To isolate the
walkthrough from installed credential files, add `--secrets-dir` pointing to
an existing empty directory to each command.
- [Full annotated pipeline](pipeline.full.annotated.yml): every implemented - [Full annotated pipeline](pipeline.full.annotated.yml): every implemented
pipeline section with explanatory comments. pipeline section with explanatory comments.
- [Extraction subset pipeline](pipeline.extraction-subset.yml): a focused - [Extraction subset pipeline](pipeline.extraction-subset.yml): a focused