Document the native CLI and migration workflows
This commit is contained in:
820
docs/cli.md
820
docs/cli.md
@@ -1,497 +1,449 @@
|
||||
# CLI Reference
|
||||
|
||||
## Shortest Useful Command
|
||||
|
||||
```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:
|
||||
## Command tree
|
||||
|
||||
```text
|
||||
added <path> <right-value>
|
||||
removed <path> <left-value>
|
||||
changed <path> <left-value> <right-value>
|
||||
narratio
|
||||
├── run SESSION
|
||||
├── 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
|
||||
comparison reports a changed mapping region as one value when a whole mapping
|
||||
is added or removed; lists are compared as whole values. A `hidden_changed=true`
|
||||
field indicates a change hidden by redaction. The command compares defaulted concrete artifacts and publish rules, not
|
||||
overlay names, source-file layout, or formatting. It succeeds when differences
|
||||
are found, making it suitable for review and migration checks.
|
||||
Bare root and command groups display help. Use `narratio help session plan`
|
||||
or `narratio session plan --help` for command-local flags and operands. Help,
|
||||
version, completion, and `config scopes` do not bootstrap credentials, load
|
||||
configuration, contact storage, or initialize adapters.
|
||||
|
||||
### `version`
|
||||
## Invocation syntax
|
||||
|
||||
```bash
|
||||
narratio version
|
||||
Place flags after the complete command path; they may be interspersed with
|
||||
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
|
||||
from source without release linker metadata report `dev`.
|
||||
The default is the full canonical pipeline:
|
||||
`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
|
||||
narratio run <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
|
||||
## Artifacts regenerate
|
||||
|
||||
```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;
|
||||
- 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.
|
||||
## Artifacts list
|
||||
|
||||
When `--artifacts` is present, the selected range must contain `analyze` or
|
||||
`publish`. Either consumer is sufficient, including a one-stage range.
|
||||
|
||||
### `regenerate-artifacts`
|
||||
|
||||
```bash
|
||||
narratio regenerate-artifacts <session_id> [--artifacts <name[,name...]>] [...common config flags]
|
||||
```sh
|
||||
narratio artifacts list --config pipeline.yml --campaign-file campaign.yml
|
||||
```
|
||||
|
||||
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
|
||||
narratio run <session_id> --force --from extract --through analyze [caller options]
|
||||
## Session plan
|
||||
|
||||
```sh
|
||||
narratio session plan SESSION --stage analyze --force --format json
|
||||
```
|
||||
|
||||
The command always reruns extraction. Analysis rebuilds the selected configured
|
||||
artifacts and any prerequisites required by those targets; without
|
||||
`--artifacts`, it uses the normal default analysis selection. Publish and notify
|
||||
never run. Common session/configuration options and repeatable artifact values
|
||||
pass through unchanged.
|
||||
Accepts the same stage/range, force, artifact, and context selections as `run`.
|
||||
Reports execution/reuse actions and reasons, analysis targets, prerequisite work,
|
||||
and publication mappings through shared planners. Planning reads existing state
|
||||
without creating a workspace, changing manifests, acquiring execution locks, or
|
||||
initializing stage adapters. It does not predict unknown output identities.
|
||||
|
||||
The forced extraction rebuilds the complete configured Notarius bundle,
|
||||
disables Notarius checkpoint loading, and requests chunk-plan refresh.
|
||||
`--artifacts` narrows only the analysis work; it never selects Notarius lanes.
|
||||
## Session validate
|
||||
|
||||
Because the expansion owns `--force`, `--from`, and `--through`, callers cannot
|
||||
supply those options. The shared `run` parser reports them as duplicate
|
||||
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]
|
||||
```sh
|
||||
narratio session validate SESSION --session-file ./session.yml
|
||||
```
|
||||
|
||||
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`
|
||||
- `transcribe`
|
||||
- `merge`
|
||||
- `polish`
|
||||
- `normalize`
|
||||
- `trim`
|
||||
- `render`
|
||||
- `extract`
|
||||
- `analyze`
|
||||
- `publish`
|
||||
- `notify`
|
||||
- `cleanup`
|
||||
## Session status
|
||||
|
||||
Rules:
|
||||
|
||||
- `--artifacts` is accepted only for `analyze` and `publish` stage targets.
|
||||
|
||||
### `analyze`
|
||||
|
||||
```bash
|
||||
narratio analyze <session_id> [--artifacts <name[,name...]>] [...common config flags]
|
||||
```sh
|
||||
narratio session status SESSION --format json
|
||||
```
|
||||
|
||||
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
|
||||
narratio run-stage analyze <session_id> --force [...common config flags]
|
||||
## Session artifacts
|
||||
|
||||
```sh
|
||||
narratio session artifacts SESSION --remote
|
||||
```
|
||||
|
||||
This selects only `analyze`: it does not invoke Notarius, replace extraction,
|
||||
or remove existing extract outputs. `--artifacts` narrows the forced analysis
|
||||
targets and their required analysis prerequisites.
|
||||
Reports definitions, dependencies, local availability/evidence, and optional
|
||||
remote publication state without reading artifact payload bodies. Without
|
||||
`--remote`, this command avoids remote artifact inspection. Current publication
|
||||
outcomes include `published`, `carried_locked`, `locked_unpublished`,
|
||||
`optional_missing`, and `unselected`.
|
||||
|
||||
### `publish`
|
||||
## Session init
|
||||
|
||||
```bash
|
||||
narratio publish <session_id> [--artifacts <name[,name...]>] [...common config flags]
|
||||
```sh
|
||||
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
|
||||
narratio run-stage publish <session_id> --force [...common config flags]
|
||||
A configured session template retains its import/resource authoring context;
|
||||
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
|
||||
full run to include configured cleanup, or `run-stage cleanup` to retry cleanup
|
||||
from valid publication evidence.
|
||||
Uses pointer-selected committed state and returns actions/conflicts. Dry runs
|
||||
make no local directory or mode changes. Actual restore preserves confined
|
||||
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
|
||||
narratio clean <session_id> [--dry-run] [--clear-cache] [...common config flags]
|
||||
narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>]
|
||||
```sh
|
||||
narratio session clean SESSION --dry-run
|
||||
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;
|
||||
- `--all` removes all local session work and spool state;
|
||||
- cache remains unless `--clear-cache` is provided.
|
||||
## Session locks
|
||||
|
||||
See [Operations: Cleanup](./operations.md#cleanup) for manual and pipeline-stage
|
||||
deletion scope.
|
||||
|
||||
### `session plan`
|
||||
|
||||
```bash
|
||||
narratio session plan <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
|
||||
```sh
|
||||
narratio session locks list SESSION
|
||||
narratio session locks add SESSION narratio.artifact.session_recap --reason 'manual review'
|
||||
narratio session locks remove SESSION narratio.artifact.session_recap
|
||||
```
|
||||
|
||||
Uses the same inclusive bounds, endpoint validation, force scope, and artifact
|
||||
selection contract as `run`. It validates config and prints run/skip decisions
|
||||
for selected stages only without creating the local workdir or changing the
|
||||
manifest. Resume-capable selected stages are checked against durable evidence.
|
||||
The output includes the resolved overlay (or `none`) and effective configuration
|
||||
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.
|
||||
A bare locks group displays help. List reports independent remote locks sorted
|
||||
by source. Add reports an existing lock unless `--force` requests one
|
||||
conditional, generation-matched replacement; concurrent change requires retry.
|
||||
Remove is idempotent. `--reason TEXT` is available on add. See
|
||||
[publish locks](operations.md#publish-locks) for their publication effect.
|
||||
|
||||
### `session validate`
|
||||
## `--artifacts` selection rules
|
||||
|
||||
```bash
|
||||
narratio session validate <session_id> [...common config flags]
|
||||
`run`, `session plan`, and `artifacts regenerate` accept repeatable
|
||||
`--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,
|
||||
previous-session requirements, publish outputs, and independent remote locks.
|
||||
- `show` displays safe effective values; `--path POINTER` selects a current
|
||||
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
|
||||
narratio session status <session_id> [...common config flags]
|
||||
### Independent comparisons and overrides
|
||||
|
||||
```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
|
||||
pointer-selected remote commit and its declared published outputs. Current
|
||||
publish metadata reports `published`, `carried_locked`, `locked_unpublished`,
|
||||
`optional_missing`, and `unselected`; carried output lines include the run
|
||||
derived from their exact declared key, the key itself, and its declared
|
||||
destination. A separately displayed `dest` is the destination requested by the
|
||||
current configuration and may differ while an older declaration is locked.
|
||||
Diff loads each side independently. In addition to native `--against-config`
|
||||
and `--against-overlay`, applicable scopes accept `--against-campaign`,
|
||||
`--against-campaign-file`, `--against-session`, `--against-session-file`, and
|
||||
`--against-party-file`. Omitted right-side selectors use their own normal
|
||||
defaults; they never inherit left-side selections. Each party default follows
|
||||
that side's campaign.
|
||||
|
||||
### `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
|
||||
narratio session init <session_id> --output ./session.yml [options]
|
||||
narratio session init <session_id> --remote [options]
|
||||
Only app inspection supports ordered, repeatable `--set POINTER=JSON`, plus
|
||||
`--against-set POINTER=JSON` for the comparison side. ConfigKit applies these
|
||||
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:
|
||||
- `--output <path>`
|
||||
- `--remote`
|
||||
## Migration from the previous CLI
|
||||
|
||||
Options:
|
||||
Removed command paths have no compatibility aliases.
|
||||
|
||||
- `--config <pipeline.yml>`
|
||||
- `--campaign <id>` or `--campaign-file <campaign.yml>`
|
||||
- `--secrets-dir <directory>`
|
||||
- `--previous-session-id <id>`
|
||||
- `--date <YYYY-MM-DD>`
|
||||
- `--title <text>`
|
||||
- `--audio-dir <path>`
|
||||
- `--audio-s3-prefix <prefix>`
|
||||
- `--force`
|
||||
| Previous invocation | Current invocation |
|
||||
| --- | --- |
|
||||
| `run-stage STAGE SESSION` | `run SESSION --stage STAGE` |
|
||||
| `analyze SESSION` | `run SESSION --stage analyze --force` |
|
||||
| `publish SESSION` | `run SESSION --stage publish --force` |
|
||||
| `regenerate-artifacts SESSION` | `artifacts regenerate SESSION` |
|
||||
| `clean SESSION` / `clean --all` | `session clean SESSION` / `session clean --all` |
|
||||
| `config artifacts` | `artifacts list` |
|
||||
| `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:
|
||||
|
||||
- `--audio-dir` and `--audio-s3-prefix` are mutually exclusive.
|
||||
- if campaign `session_template_file` is configured, `session init` renders it.
|
||||
- generated session YAML must be concrete (no unresolved `{{ ... }}` placeholders).
|
||||
- template imports and relative resources resolve in the template's local
|
||||
authoring context. Generated output contains standalone effective values.
|
||||
- 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).
|
||||
Campaign identity and file selectors may now accompany each other. Party-file
|
||||
selection consistently overrides the roster without editing campaign settings.
|
||||
Native configuration inspection retains declarations and their actual evidence;
|
||||
use catalog/plan/session views for generated domain products. Comparison defaults
|
||||
are independent. Field overrides are inspection-only. Update scripts to consume
|
||||
structured reports and exit classifications, place flags after the complete
|
||||
command path, and account for native repetition and cancellation behavior.
|
||||
|
||||
@@ -2,7 +2,8 @@
|
||||
|
||||
## 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
|
||||
- `campaign.yml`: campaign identity and stable input defaults
|
||||
@@ -37,7 +38,8 @@ Selection rules:
|
||||
|
||||
### `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`
|
||||
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
|
||||
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`,
|
||||
and `narratio config artifacts` use the same `--config`, `--campaign`,
|
||||
`--campaign-file`, and
|
||||
`--overlay` selection rules as pipeline commands, but do not select, discover,
|
||||
or load a session. They resolve configured typed credential references as part
|
||||
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.
|
||||
Native configuration inspection exposes four actual typed ConfigKit results:
|
||||
app (the default pipeline scope), campaign, session, and party. Defaults,
|
||||
normalization, and configuration-owned validation finish within their supported
|
||||
load lifecycle. Session configuration includes applicable campaign defaults
|
||||
before handoff. Completed values remain unchanged by planning or execution.
|
||||
|
||||
Campaign selection is optional only when the resolved pipeline has no
|
||||
`scriptorium.artifact_families`. When families are declared, Narratio selects a
|
||||
campaign through an explicit flag or `pipeline.campaigns.default_campaign_id`,
|
||||
then parses the campaign-owned party and expands concrete artifacts and any
|
||||
family publish rules before validation. `config validate` prints the resulting
|
||||
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.
|
||||
App inspection retains artifact-family declarations and needs no campaign or
|
||||
party solely for expansion. Narratio derives concrete artifact catalogs, players,
|
||||
resolved dependencies, and publication actions separately using the selected
|
||||
canonical roster. `artifacts list` inspects those domain definitions;
|
||||
`session plan` and `session artifacts` expose decisions and availability.
|
||||
|
||||
`config diff` compares normalized field values rather than YAML text or source
|
||||
ownership. It emits native ordered `added`, `removed`, and `changed` records with
|
||||
JSON Pointer paths and compact JSON values. Lists are compared atomically, and
|
||||
changed regions may contain whole values. It reports `no differences` when the
|
||||
complete effective configurations are equal. Concrete
|
||||
family members and generated publish rules participate after expansion; moving
|
||||
an equal value between eligible root/import sources does not create a
|
||||
difference.
|
||||
Native sources/explanations retain actual imports, origins, history, and recorded
|
||||
resolution evidence. Comparisons load each side independently using its own
|
||||
normal defaults. App-only inspection overrides apply during that invocation's
|
||||
load. Safe views hide resolved credentials. Persisted preparation projections
|
||||
retain reference names and do not replace the native inspection result.
|
||||
See the [CLI reference](cli.md#configuration-inspection) for scopes, selectors,
|
||||
path operations, overrides, comparison modes, and report shapes.
|
||||
|
||||
### 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
|
||||
|
||||
@@ -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
|
||||
rosters to [canonical party input](integrations/party.md), then express character
|
||||
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
|
||||
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
|
||||
session. The optional `spell_catalog_file` also inherits a campaign value
|
||||
when omitted by the session.
|
||||
- `party_file` is parsed when pipeline and campaign configuration are combined.
|
||||
It must be a versioned [canonical party](integrations/party.md), is
|
||||
campaign-owned and derives the players input internally. `players_file` and
|
||||
- The selected party is parsed when domain context or party inspection needs
|
||||
it. It must be a versioned [canonical party](integrations/party.md). The
|
||||
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.
|
||||
- Exactly one audio mode must be configured in session input:
|
||||
- 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
|
||||
effective dependency on that configured artifact. Narratio unions these inferred
|
||||
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.
|
||||
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
|
||||
loading a session or creating runtime state.
|
||||
|
||||
### Scriptorium Artifact Families
|
||||
|
||||
`pipeline.scriptorium.artifact_families` declares a shared artifact template
|
||||
for every canonical campaign character. Configuration resolution expands each
|
||||
family into ordinary `pipeline.scriptorium.artifacts` entries before analyze
|
||||
planning or Scriptorium invocation. Party parsing rejects unsupported document
|
||||
schemas before family expansion.
|
||||
for every canonical campaign character. Domain catalog derivation expands each
|
||||
family into separate concrete artifact entries before analyze planning or
|
||||
Scriptorium invocation, retaining the authored declarations in configuration.
|
||||
Party parsing rejects unsupported document schemas before family expansion.
|
||||
|
||||
For each `pipeline.scriptorium.artifact_families.<name>`:
|
||||
|
||||
|
||||
@@ -58,16 +58,16 @@ Configured definitions are always registered. Without an explicit selection,
|
||||
the effective analyze set contains enabled definitions. With `--artifacts`, the
|
||||
exact named configured definitions become the effective set for that invocation,
|
||||
regardless of their `enabled` value. The effective-set resolver itself does not
|
||||
expand dependencies. Configuration has already materialized the sorted union of
|
||||
explicit ordering edges and configured-artifact input edges, and the analyze
|
||||
expand dependencies. Shared domain catalog derivation has materialized the sorted
|
||||
union of explicit ordering edges and configured-artifact input edges, and the analyze
|
||||
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.
|
||||
The effective set retains optional family
|
||||
and character origin metadata, but its keys, catalog sources, and runtime
|
||||
lookups remain concrete configured-artifact identities.
|
||||
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
|
||||
only when the versioned analyze state identifies a current result whose source,
|
||||
contract, canonical configured path, size, and checksum match a confined
|
||||
|
||||
@@ -2,100 +2,94 @@
|
||||
|
||||
User-visible fields, defaults, discovery, and selection belong in 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
|
||||
native required discovery. ConfigKit loads typed defaults, source-root imports,
|
||||
and the selected overlay, resolves inheritance, and strictly decodes the
|
||||
result. Narratio applies recorded defaults, normalization, resource resolution,
|
||||
and effective-domain validation. The selected root, source contexts, metadata,
|
||||
and authoring result are retained for provenance. Family expansion and checks
|
||||
requiring the campaign occur after campaign and party resolution.
|
||||
Pipeline, campaign, session, and party loaders retain their actual typed
|
||||
ConfigKit results. ConfigKit owns imports, overlay composition, inheritance,
|
||||
presence, typed secrets, and native source/history evidence. Narratio's
|
||||
supported definition callbacks complete configuration-owned defaults,
|
||||
normalization, resource resolution, and validation before handoff. Consumers
|
||||
read completed values without mutation.
|
||||
|
||||
Resource resolution consults native entry origins and source contexts before
|
||||
normalization. An effective source supplies the base when usable; otherwise the
|
||||
main source, then the captured invocation directory, is the fallback. Explicit
|
||||
CLI file references use the invocation directory. Derived values record their
|
||||
dependencies. See the [configuration reference](../config.md#pipeline-imports-and-overlays)
|
||||
for the resource classifications and native authoring contract.
|
||||
Session definitions receive selected-campaign defaults before loading finishes.
|
||||
Recorded resolution preserves explicit empty/null/false/zero behavior and
|
||||
truthful dependencies. Identity and previous-session assertions are separate
|
||||
request checks against completed values. Standalone document renderers preserve
|
||||
materialization semantics without providing a second inspection authority.
|
||||
|
||||
## 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
|
||||
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.
|
||||
## Invocation Acquisition
|
||||
|
||||
Campaign and session loaders retain detached document values after their own
|
||||
resolution. The session document is captured before campaign defaults are copied
|
||||
into runtime session state. Configuration-owned renderers produce standalone
|
||||
campaign and session YAML, preserving omitted session overrides. Prepare uses
|
||||
those renderers and canonical party rendering for materialization and resume
|
||||
comparison.
|
||||
`internal/app/configuration_acquisition.go` owns lazy invocation selections and
|
||||
acquired context. Exact sources and effective-identity assertions are
|
||||
complementary. App acquisition needs no campaign or party for expansion;
|
||||
campaign acquisition needs no session. Session acquisition loads campaign
|
||||
context when required for defaults. Explicit party acquisition does not require
|
||||
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
|
||||
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.
|
||||
## Native Inspection
|
||||
|
||||
Authoring results separately supply native origins, source histories, and empty
|
||||
optional-import evidence to source and artifact inspection. Family and party
|
||||
context identifies generated entries without reparsing sources. Diff fully
|
||||
resolves each side against the same selected campaign and party, then uses
|
||||
ConfigKit `Diff` on the safe snapshots. The command presents native JSON Pointer
|
||||
paths and safe compact values.
|
||||
`configuration_commands.go` adapts actual results with `ckconfig.FromConfigKit`.
|
||||
Native show, sources, explain/history, validation, and comparisons consume that
|
||||
result's values and evidence. There is no flattened replacement snapshot,
|
||||
synthetic source reconciliation, or generated family catalog in app inspection.
|
||||
|
||||
## 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.
|
||||
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).
|
||||
## Canonical Party And Derived Catalog
|
||||
|
||||
## 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
|
||||
provenance. Narratio owns validation and normalization of effective domain
|
||||
values. Source histories are inspection evidence, not an additional acceptance
|
||||
gate. Focused configuration and application tests exercise imports, resource
|
||||
contexts, snapshots, secret-safe inspection, party resolution, and materialized
|
||||
inputs through the production boundaries.
|
||||
`ArtifactCatalog` carries derived artifacts, family/member origins, resolved
|
||||
dependencies, and expanded publication outputs separately from pipeline values.
|
||||
Family declarations remain in the typed pipeline result. Derivation sorts
|
||||
family keys and character IDs, substitutes `{character_id}` in outputs,
|
||||
resolves closed member variables, and checks key/output collisions and domain
|
||||
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
|
||||
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.
|
||||
## Safe Persistence And Semantic Resume
|
||||
|
||||
The catalog retains sorted family member keys plus family/character/source
|
||||
origins and the typed dependency/publish declarations for their later owners.
|
||||
`member_dependencies` add corresponding ordinary concrete dependencies, while
|
||||
the family-only `narratio.member_artifact.<family>` input form is rewritten to
|
||||
the matching ordinary configured-artifact source. The catalog records those
|
||||
resolved dependency and input identities with their declaring family and party
|
||||
member. No member-artifact source is registered as a runtime policy source.
|
||||
An enabled family publish declaration expands to ordinary configured-artifact
|
||||
publish rules before the existing publish and lock validators run. Runtime
|
||||
publication consequently receives no family wildcard or special matcher.
|
||||
Preparation materializes standalone campaign/session/party/players inputs and
|
||||
a secret-safe pipeline projection. The projection preserves credential names,
|
||||
family declarations, numeric values, and null/empty distinctions. It is a
|
||||
persistence service, not a fabricated native result. An effective digest is
|
||||
informational; resume compares result-affecting semantic evidence from the same
|
||||
concrete products used by execution. Source arrangement, provenance, and overlay
|
||||
labels alone do not invalidate work.
|
||||
|
||||
Focused configuration/application fixtures cover imports, defaults, selected
|
||||
rosters, independent comparisons, override isolation, secret-safe persistence,
|
||||
and unchanged completed configuration across domain derivation and execution.
|
||||
|
||||
@@ -373,4 +373,4 @@ where the last session transition can require operator interpretation.
|
||||
- Transcribe speaker state: `internal/manifest/transcribe_state.go`
|
||||
- Package tests: `internal/manifest/*_test.go`
|
||||
- Assembled execution behavior: `internal/app/runner_test.go`,
|
||||
`internal/app/run_stage_test.go`
|
||||
`internal/app/run_selection_test.go`
|
||||
|
||||
@@ -16,7 +16,8 @@ cmd/narratio -> internal/app -> configuration and production composition
|
||||
-> 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
|
||||
session safety controls, and runs commands. Pipeline commands execute the
|
||||
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
|
||||
session lock, load or create the authoritative session manifest, compose only
|
||||
the collaborators needed by the selected range, execute each selected stage in
|
||||
order, and then return the summary. Cleanup, when selected, is the ordinary
|
||||
final stage rather than runner finalization work.
|
||||
order, finalize terminal state, release resources, and return a possibly partial
|
||||
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
|
||||
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 |
|
||||
| --- | --- | --- |
|
||||
| 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. |
|
||||
| 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. |
|
||||
| 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) | 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. |
|
||||
| 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. |
|
||||
@@ -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. |
|
||||
| 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. |
|
||||
| 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
|
||||
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
|
||||
ordering is protected by `internal/app/planner_test.go`. Cross-invocation skip,
|
||||
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`.
|
||||
|
||||
@@ -53,7 +53,7 @@ Supported source families:
|
||||
manifest record and durable output pass the configured-artifact evidence
|
||||
contract; an incidental or stale canonical file is unavailable.
|
||||
- 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
|
||||
evidence do not infer a second graph from inputs.
|
||||
- resolves required/optional inputs per artifact source definition into an
|
||||
|
||||
@@ -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,
|
||||
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
|
||||
`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.
|
||||
|
||||
## Implementation And Tests
|
||||
|
||||
@@ -129,7 +129,7 @@ evidence does not replace those safety checks.
|
||||
The commit boundary and cleanup authorization are normative architecture invariants; see
|
||||
[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.
|
||||
|
||||
## Related Contracts And Tests
|
||||
|
||||
@@ -72,7 +72,7 @@ The canonical cleanup stage:
|
||||
republishing.
|
||||
|
||||
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).
|
||||
|
||||
## Invariants
|
||||
|
||||
@@ -6,17 +6,13 @@ For command syntax, see [docs/cli.md](./cli.md). For field-level config, see [do
|
||||
|
||||
## Campaign and Session Selection
|
||||
|
||||
Campaign selection priority:
|
||||
|
||||
- `--campaign-file`
|
||||
- `--campaign`
|
||||
- `pipeline.campaigns.default_campaign_id`
|
||||
|
||||
Session source priority:
|
||||
|
||||
- `--session`
|
||||
- local default search paths
|
||||
- remote session object (S3) when local session file is not found and storage is configured
|
||||
Identity and exact-file selection are complementary: a selected file supplies
|
||||
configuration and an explicit ID asserts its effective identity. Session domain
|
||||
commands take positional identity; `--session-file` selects its source. An
|
||||
explicit `--party-file` supplies the roster consistently across consumers.
|
||||
See [CLI selectors](cli.md#configuration-selectors) and
|
||||
[configuration discovery](config.md#discovery-and-selection) for selection rules.
|
||||
Existing scripts should follow the [CLI migration table](cli.md#migration-from-the-previous-cli).
|
||||
|
||||
## Session Initialization
|
||||
|
||||
@@ -70,21 +66,19 @@ narratio run 2026-04-04
|
||||
narratio session status 2026-04-04
|
||||
```
|
||||
|
||||
Run, plan, and status output identify the resolved pipeline overlay (or `none`)
|
||||
and effective configuration digest. Status distinguishes the current resolved
|
||||
value from the last value persisted in the session manifest, which helps
|
||||
diagnose overlay switches without changing resume authority.
|
||||
Status distinguishes currently resolved configuration provenance from the last
|
||||
persisted configuration, helping diagnose overlay switches without changing
|
||||
semantic resume authority. Run and plan reports describe execution and decisions;
|
||||
see the [report fields](cli.md#public-domain-report-fields).
|
||||
|
||||
Before switching an operational overlay, compare its effective meaning with the
|
||||
production base through `narratio config diff default <overlay>`.
|
||||
The command is read-only and succeeds whether it finds differences or not. Its
|
||||
sorted records describe defaulted, expanded concrete configuration—not source
|
||||
file layout—so it can be used to review model, artifact, and publish changes
|
||||
without creating a session or run. Use `narratio config artifacts` to review the
|
||||
concrete artifact identities, definitions, outputs, and dependencies. Select the
|
||||
same campaign explicitly when overlays could resolve different campaign paths;
|
||||
see the [CLI reference](cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff)
|
||||
for syntax and record format.
|
||||
Before switching an operational overlay, compare its effective configuration
|
||||
with the base through `narratio config diff --against-overlay NAME`. When using an
|
||||
explicit root, supply it with both `--config` and `--against-config`. Each side
|
||||
loads independently using its own defaults. Native inspection retains authored
|
||||
family declarations; use `narratio artifacts list` to review concrete identities,
|
||||
outputs, dependencies, and selected-party members. See
|
||||
[configuration inspection](cli.md#configuration-inspection) for selection and
|
||||
comparison details.
|
||||
|
||||
## Stage Execution and Continuation Behavior
|
||||
|
||||
@@ -148,7 +142,7 @@ the stage self-skip.
|
||||
Single-stage execution:
|
||||
|
||||
```bash
|
||||
narratio run-stage normalize 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage normalize --force
|
||||
```
|
||||
|
||||
Contiguous bounded execution uses inclusive canonical endpoints:
|
||||
@@ -199,7 +193,7 @@ canonical `transcripts/raw/<speaker>.json` files remain durable, however.
|
||||
After correcting the underlying problem, retry normally:
|
||||
|
||||
```bash
|
||||
narratio run-stage transcribe 2026-04-04
|
||||
narratio run 2026-04-04 --stage transcribe
|
||||
```
|
||||
|
||||
Narratio hashes the current prepared audio, validates recorded transcript JSON,
|
||||
@@ -213,7 +207,7 @@ a WhisperX model or private server-side configuration changes behind the same
|
||||
URL and language:
|
||||
|
||||
```bash
|
||||
narratio run-stage transcribe 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage transcribe --force
|
||||
```
|
||||
|
||||
Force durably clears the reusable collection before sending requests. If that
|
||||
@@ -242,21 +236,21 @@ Choose the narrowest workflow that matches the intended replacement:
|
||||
|
||||
| Intent | Command | Preserved and rebuilt state |
|
||||
| --- | --- | --- |
|
||||
| Rebuild analysis only | [`narratio analyze 2026-04-04`](./cli.md#analyze) | Preserves transcripts and the current extraction bundle; force-runs selected analysis artifacts and their required analysis prerequisites. |
|
||||
| Rebuild extraction and analysis | [`narratio regenerate-artifacts 2026-04-04`](./cli.md#regenerate-artifacts) | Preserves transcripts; force-runs the complete configured extraction bundle, then selected analysis. `--artifacts` narrows analysis only. |
|
||||
| Rebuild analysis only | [`narratio run 2026-04-04 --stage analyze --force`](./cli.md#run) | Preserves transcripts and the current extraction bundle; force-runs selected analysis artifacts and their required analysis prerequisites. |
|
||||
| Rebuild extraction and analysis | [`narratio artifacts regenerate 2026-04-04`](./cli.md#artifacts-regenerate) | Preserves transcripts; force-runs the complete configured extraction bundle, then selected analysis. `--artifacts` narrows analysis only. |
|
||||
| Continue bounded work normally | [`narratio run 2026-04-04 --from extract --through analyze`](./cli.md#run) | Uses ordinary resume decisions: current extraction and analysis can be skipped, while incomplete or obsolete work runs. |
|
||||
|
||||
All three stop before publication. Inspect the results and run
|
||||
[`narratio publish`](./cli.md#publish) separately when delivery is intended.
|
||||
[`narratio run SESSION --stage publish --force`](./cli.md#run) separately when delivery is intended.
|
||||
|
||||
For the extraction-plus-analysis development loop, use:
|
||||
|
||||
```bash
|
||||
narratio regenerate-artifacts 2026-04-04
|
||||
narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout
|
||||
narratio artifacts regenerate 2026-04-04
|
||||
narratio artifacts regenerate 2026-04-04 --artifacts session_recap,player_handout
|
||||
```
|
||||
|
||||
This command is a transparent expansion to a forced bounded `run` from
|
||||
This command shares the forced bounded execution operation from
|
||||
`extract` through `analyze`. Extraction always rebuilds its complete configured
|
||||
bundle. Analysis rebuilds the selected targets and their required analysis
|
||||
prerequisites, or uses the normal default selection when no artifact names are
|
||||
@@ -268,7 +262,7 @@ set is ready:
|
||||
|
||||
```bash
|
||||
narratio session artifacts 2026-04-04
|
||||
narratio publish 2026-04-04
|
||||
narratio run 2026-04-04 --stage publish --force
|
||||
```
|
||||
|
||||
If planning or execution reports stale, missing, failed, or tampered
|
||||
@@ -352,8 +346,9 @@ not create a separate workspace or retain a separate current extraction result.
|
||||
|
||||
Narratio cannot observe edits inside Notarius configuration behind an unchanged
|
||||
selector. Force extraction after such an edit when a replacement is intended.
|
||||
Use `regenerate-artifacts` when both extraction and analysis must be rebuilt;
|
||||
use `analyze` when the existing extraction bundle should be preserved. Field
|
||||
Use `artifacts regenerate` when both extraction and analysis must be rebuilt;
|
||||
use `run SESSION --stage analyze --force` when the existing extraction bundle
|
||||
should be preserved. Field
|
||||
semantics belong in [Configuration](./config.md#notarius-configuration-overlay),
|
||||
with Audita selectors covered under
|
||||
[Audita selection and credentials](./config.md#audita-selection-and-credentials).
|
||||
@@ -367,13 +362,13 @@ concrete character artifact. Select a concrete generated key to operate on one
|
||||
member only. Manifests and plan output retain the concrete key as the durable
|
||||
identity and include the family and character ID as optional provenance.
|
||||
|
||||
`--artifacts` can be used on `run`, `session plan`, `run-stage`, `analyze`, and
|
||||
`publish`. For a bounded run or plan, the selected range must contain `analyze`
|
||||
`--artifacts` can be used on `run`, `session plan`, and
|
||||
`artifacts regenerate`. For a bounded run or plan, the selected range must contain `analyze`
|
||||
or `publish`.
|
||||
|
||||
Selection behavior:
|
||||
|
||||
- validates names against `pipeline.scriptorium.artifacts`;
|
||||
- validates names against the derived concrete catalog and family selections;
|
||||
- selects explicit analyze targets and permits their required configured
|
||||
prerequisites to be reused or rebuilt first;
|
||||
- filters publish rules for `narratio.artifact.<name>` sources only;
|
||||
@@ -429,7 +424,7 @@ prepared file is missing or inconsistent with its manifest checksum, repair
|
||||
the source configuration and refresh prepared state first:
|
||||
|
||||
```bash
|
||||
narratio run-stage prepare 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage prepare --force
|
||||
```
|
||||
|
||||
Starting a replacement clears the previous extraction payload from the current
|
||||
@@ -538,7 +533,7 @@ contract](./integrations/audita.md) for report placement and limits.
|
||||
Narratio's polish resume evidence tracks selected config path, Audita overlay,
|
||||
profiles, ordered modules, description, schema, and output identity. Editing
|
||||
Audita-owned files behind unchanged selectors is invisible to Narratio; force
|
||||
polish with `narratio run-stage polish <session-id> --force` after such edits.
|
||||
polish with `narratio run <session-id> --stage polish --force` after such edits.
|
||||
|
||||
## External Command Lifecycle
|
||||
|
||||
@@ -581,7 +576,7 @@ the committed manifest and declared transcript/artifact objects.
|
||||
To intentionally replace the current extraction result, run:
|
||||
|
||||
```bash
|
||||
narratio run-stage extract 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage extract --force
|
||||
```
|
||||
|
||||
Narratio automatically reruns extraction when its recorded invocation contract,
|
||||
@@ -610,16 +605,10 @@ before commit selection.
|
||||
Run publish only:
|
||||
|
||||
```bash
|
||||
narratio publish 2026-04-04
|
||||
narratio run 2026-04-04 --stage publish --force
|
||||
```
|
||||
|
||||
Equivalent:
|
||||
|
||||
```bash
|
||||
narratio run-stage publish 2026-04-04 --force
|
||||
```
|
||||
|
||||
This standalone command stops after publish and does not invoke cleanup. A
|
||||
This selection stops after publish and does not invoke cleanup. A
|
||||
default full `run` continues through notify and cleanup.
|
||||
|
||||
Publish commit model:
|
||||
@@ -689,7 +678,7 @@ Operational rules:
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
narratio session locks 2026-04-04
|
||||
narratio session locks list 2026-04-04
|
||||
narratio session locks add 2026-04-04 narratio.artifact.session_recap --reason "manual edits" --force
|
||||
narratio session locks remove 2026-04-04 narratio.artifact.session_recap
|
||||
```
|
||||
@@ -847,20 +836,20 @@ the session workload.
|
||||
Session-scoped cleanup:
|
||||
|
||||
```bash
|
||||
narratio clean 2026-04-04
|
||||
narratio session clean 2026-04-04
|
||||
```
|
||||
|
||||
Global cleanup:
|
||||
|
||||
```bash
|
||||
narratio clean --all
|
||||
narratio session clean --all
|
||||
```
|
||||
|
||||
Dry-run and cache variants:
|
||||
|
||||
```bash
|
||||
narratio clean 2026-04-04 --dry-run --clear-cache
|
||||
narratio clean --all --dry-run --clear-cache
|
||||
narratio session clean 2026-04-04 --dry-run --clear-cache
|
||||
narratio session clean --all --dry-run --clear-cache
|
||||
```
|
||||
|
||||
Rules:
|
||||
@@ -879,9 +868,9 @@ Cleanup derives only the configured run-scoped spool and workspace targets,
|
||||
uses root-confined deletion, and does not read or mutate object storage. A
|
||||
failure leaves publish succeeded and the remote committed snapshot current.
|
||||
Retry with a normal full run: valid upstream work, including publish and notify,
|
||||
is skipped while the failed cleanup stage runs again. `run-stage cleanup` is
|
||||
is skipped while the failed cleanup stage runs again. `run SESSION --stage cleanup` is
|
||||
also available when the manifest has valid publish evidence. A range ending at
|
||||
`notify` or earlier and the standalone `publish` command never delete local
|
||||
`notify` or earlier and `run SESSION --stage publish` never delete local
|
||||
state.
|
||||
|
||||
Older local manifests that contain the retired cleanup-obligation field are
|
||||
@@ -900,3 +889,9 @@ normal migration path.
|
||||
- Restore requires configured object storage and committed remote current state.
|
||||
- Pipeline-loading commands bootstrap filesystem secrets once before configuration
|
||||
resolution and object-store initialization.
|
||||
|
||||
Console progress and informational diagnostics use native invocation visibility.
|
||||
`--progress` shows work without requiring verbose mode; `--verbose` adds source
|
||||
and decision context. Console `--debug` does not enable downstream debug capture
|
||||
or change retention. Downstream streams stay in captured logs. See
|
||||
[CLI reporting](cli.md#reporting-and-visibility) for mode combinations and formats.
|
||||
|
||||
@@ -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
|
||||
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
|
||||
contains valid successful publication evidence.
|
||||
|
||||
|
||||
@@ -792,6 +792,16 @@ contracts, deliberate migration guidance, or immutable historical records.
|
||||
|
||||
## 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
|
||||
CLI/config/operations/internal owners, maintained examples, and release scripts.
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ Likely cause:
|
||||
Diagnostics:
|
||||
|
||||
```bash
|
||||
narratio session validate 2026-04-04 --session /path/session.yml
|
||||
narratio session validate 2026-04-04 --session-file /path/session.yml
|
||||
```
|
||||
|
||||
Safe fix:
|
||||
@@ -62,7 +62,7 @@ Likely cause:
|
||||
Diagnostics:
|
||||
|
||||
```bash
|
||||
narratio session plan 2026-04-04 --config /path/pipeline.yml --campaign-file /path/campaign.yml --session /path/session.yml
|
||||
narratio session plan 2026-04-04 --config /path/pipeline.yml --campaign-file /path/campaign.yml --session-file /path/session.yml
|
||||
```
|
||||
|
||||
Safe fix:
|
||||
@@ -115,23 +115,27 @@ Diagnostics:
|
||||
narratio config sources --config /path/pipeline.yml --overlay testing
|
||||
```
|
||||
|
||||
Add `--campaign` or `--campaign-file` when the pipeline has party-driven
|
||||
artifact families. The output identifies each effective logical field's root,
|
||||
import, overlay, default, campaign, party, or family source without printing
|
||||
the field value or credential contents. Empty optional import selections are
|
||||
reported separately; selected invalid files still fail.
|
||||
Native sources list the actual files and import evidence for the selected
|
||||
scope. To trace a value, use `config explain --path POINTER`, or discover paths
|
||||
with `config explain --list`. App inspection keeps family declarations;
|
||||
`artifacts list` derives concrete members from the selected campaign/party.
|
||||
|
||||
Safe fix:
|
||||
|
||||
- move a duplicated base field so it has one owner;
|
||||
- correct the selected overlay; or
|
||||
- correct the campaign party/family declaration that owns generated values.
|
||||
- inspect the field's effective origin and history;
|
||||
- correct the selected source or overlay; or
|
||||
- select the intended roster when reviewing family members.
|
||||
|
||||
To review what would actually change before switching overlays, run `config
|
||||
diff` with the same pipeline and campaign selectors. It compares normalized
|
||||
effective values rather than YAML formatting or source-file layout.
|
||||
To compare an explicit pipeline root with its testing overlay, select the root
|
||||
on both sides:
|
||||
|
||||
Relevant reference: [Configuration inspection](./config.md#read-only-effective-pipeline-inspection).
|
||||
```sh
|
||||
narratio config diff --config /path/pipeline.yml --against-config /path/pipeline.yml --against-overlay testing --details
|
||||
```
|
||||
|
||||
The sides use independent defaults. Comparison concerns effective native values,
|
||||
including declarations, rather than generated domain objects or YAML layout.
|
||||
See [configuration inspection](./cli.md#configuration-inspection).
|
||||
|
||||
## Audio mode conflict
|
||||
|
||||
@@ -165,7 +169,7 @@ Likely causes:
|
||||
|
||||
- key not defined in `pipeline.scriptorium.artifacts`;
|
||||
- empty list entry (for example trailing comma);
|
||||
- `run-stage` used with non-`analyze`/`publish` target.
|
||||
- selected run/plan range contains neither `analyze` nor `publish`.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
@@ -202,7 +206,7 @@ narratio session plan 2026-04-04 --from render --through analyze
|
||||
Safe fix:
|
||||
|
||||
- widen the bounded range to include the first reported stage, or recover that
|
||||
stage explicitly with `run-stage` before retrying. The failed check does not
|
||||
stage explicitly with `run --stage` before retrying. The failed check does not
|
||||
create a run-local directory or modify the manifest. Narratio does not
|
||||
resume-validate excluded prefix stages, and stages after `--through` are not
|
||||
prerequisites.
|
||||
@@ -243,7 +247,7 @@ Safe fix:
|
||||
for a successful checkpoint.
|
||||
|
||||
```bash
|
||||
narratio run-stage transcribe 2026-04-04
|
||||
narratio run 2026-04-04 --stage transcribe
|
||||
```
|
||||
|
||||
Valid earlier speaker checkpoints remain reusable even while aggregate
|
||||
@@ -271,7 +275,7 @@ Safe fix:
|
||||
retry if the replacement attempt is interrupted.
|
||||
|
||||
```bash
|
||||
narratio run-stage transcribe 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage transcribe --force
|
||||
```
|
||||
|
||||
Transport replay and application retries do not provide an exactly-once remote
|
||||
@@ -375,7 +379,7 @@ Safe fix:
|
||||
An exit-zero polish with a valid transcript succeeds even when Audita reports
|
||||
recoverable errors or no corrections. Missing reports are allowed when Audita
|
||||
reporting is disabled externally. Edits to Audita-owned files behind unchanged
|
||||
selectors require `narratio run-stage polish <session-id> --force` to replace a
|
||||
selectors require `narratio run <session-id> --stage polish --force` to replace a
|
||||
previously successful result. See the [Audita integration contract](./integrations/audita.md).
|
||||
|
||||
## Notarius executable missing
|
||||
@@ -447,7 +451,7 @@ Safe fix:
|
||||
evidence before extraction:
|
||||
|
||||
```bash
|
||||
narratio run-stage prepare 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage prepare --force
|
||||
```
|
||||
|
||||
Do not point Notarius directly at the original source path or edit the manifest
|
||||
@@ -607,7 +611,7 @@ Symptom:
|
||||
Safe fix:
|
||||
|
||||
```bash
|
||||
narratio run-stage extract 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage extract --force
|
||||
```
|
||||
|
||||
Narratio fingerprints its invocation contract and prepared Narratio reference
|
||||
@@ -650,7 +654,7 @@ Safe fix:
|
||||
the canonical path as a substitute for current evidence.
|
||||
|
||||
```bash
|
||||
narratio analyze 2026-04-04 --artifacts session_recap
|
||||
narratio run 2026-04-04 --stage analyze --force --artifacts session_recap
|
||||
```
|
||||
|
||||
Relevant references: [Operations: Artifact Selection](./operations.md#artifact-selection)
|
||||
@@ -730,7 +734,7 @@ Safe fix:
|
||||
|
||||
```bash
|
||||
narratio run 2026-04-04
|
||||
narratio publish 2026-04-04
|
||||
narratio run 2026-04-04 --stage publish --force
|
||||
```
|
||||
|
||||
After current records exist, inspect them and publish explicitly. Do not copy
|
||||
@@ -775,7 +779,7 @@ Safe fix:
|
||||
reusable unless selected themselves.
|
||||
|
||||
```bash
|
||||
narratio analyze 2026-04-04 --artifacts session_recap
|
||||
narratio run 2026-04-04 --stage analyze --force --artifacts session_recap
|
||||
```
|
||||
|
||||
Relevant reference: [Analyze Internals](./internal/stage-analyze.md#invariants).
|
||||
@@ -809,7 +813,7 @@ narratio session restore 2026-04-04
|
||||
or rerun prepare after correcting session config:
|
||||
|
||||
```bash
|
||||
narratio run-stage prepare 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage prepare --force
|
||||
```
|
||||
|
||||
Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow).
|
||||
@@ -911,7 +915,7 @@ Diagnostics:
|
||||
```bash
|
||||
narratio session artifacts 2026-04-04 --remote
|
||||
narratio session status 2026-04-04
|
||||
narratio run-stage publish 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage publish --force
|
||||
```
|
||||
|
||||
Safe fix:
|
||||
@@ -944,8 +948,8 @@ Safe fix:
|
||||
- rerun render and then retry downstream stage(s):
|
||||
|
||||
```bash
|
||||
narratio run-stage render 2026-04-04 --force
|
||||
narratio run-stage analyze 2026-04-04 --force
|
||||
narratio run 2026-04-04 --stage render --force
|
||||
narratio run 2026-04-04 --stage analyze --force
|
||||
```
|
||||
|
||||
Relevant reference: [Operations: Stage Execution](./operations.md#stage-execution-and-continuation-behavior).
|
||||
|
||||
Reference in New Issue
Block a user