From 0e9cbc9c2a627b1acb174c41bffaede4451f4c20 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 06:41:59 +0000 Subject: [PATCH] Document the native CLI and migration workflows --- README.md | 3 +- docs/cli.md | 820 ++++++++++++++++----------------- docs/config.md | 89 ++-- docs/internal/artifacts.md | 8 +- docs/internal/configuration.md | 156 +++---- docs/internal/manifest.md | 2 +- docs/internal/overview.md | 17 +- docs/internal/stage-analyze.md | 2 +- docs/internal/stage-cleanup.md | 4 +- docs/internal/stage-publish.md | 2 +- docs/internal/workspace.md | 2 +- docs/operations.md | 111 +++-- docs/policy/architecture.md | 2 +- docs/roadmap/implementation.md | 10 + docs/troubleshooting.md | 60 +-- examples/README.md | 17 +- 16 files changed, 633 insertions(+), 672 deletions(-) diff --git a/README.md b/README.md index 79995d0..dc4c627 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,8 @@ polished transcripts, validated Notarius extraction lanes, and generated artifacts. It runs a deterministic workflow with manifest-driven continuation, remote -publish, and restore support. +publish, and restore support. Its CommandKit CLI provides native configuration +inspection, structured operation reports, progress, and shell completion. ```sh narratio run 2026-04-04 diff --git a/docs/cli.md b/docs/cli.md index 5cbeb32..20f09ea 100644 --- a/docs/cli.md +++ b/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 `: run all or one contiguous range of the canonical stage order. -- `regenerate-artifacts `: force-run extraction through analysis. -- `run-stage `: run one stage. -- `analyze `: force-run analyze. -- `publish `: force-run publish. -- `clean ` or `clean --all`: remove local work/spool state. -- `session `: session helper commands. -- `config `: validate, display, source-trace, catalog, or compare resolved pipeline configuration. - -Session subcommands: - -- `session init ` -- `session plan ` -- `session validate ` -- `session status ` -- `session restore ` -- `session artifacts ` -- `session locks ` -- `session locks add ` -- `session locks remove ` - -## Common Config Flags - -Most session-aware commands accept: - -- `--config ` -- `--campaign ` -- `--campaign-file ` -- `--session ` -- `--session-id ` -- `--previous-session-id ` -- `--overlay ` -- `--secrets-dir ` - -Rules: - -- `--campaign` and `--campaign-file` are mutually exclusive. -- `--session` is not used by `session init`. -- if both positional `` 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/.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: `... ` -- compatibility flag: `... --session-id ` - -When both are present, command parsing requires an exact match. - -Commands with additional positionals keep their command-specific order: - -- `run-stage ` or `run-stage --session-id ` -- `session locks add ` or `session locks add --session-id ` -- `session locks remove ` or `session locks remove --session-id ` - -## Command Reference - -### `config validate`, `config show`, `config sources`, `config artifacts`, and `config diff` - -```bash -narratio config validate [--config ] [--campaign | --campaign-file ] [--overlay ] [--secrets-dir ] -narratio config show [--config ] [--campaign | --campaign-file ] [--overlay ] [--secrets-dir ] -narratio config sources [--config ] [--campaign | --campaign-file ] [--overlay ] [--secrets-dir ] -narratio config artifacts [--config ] [--campaign | --campaign-file ] [--overlay ] [--secrets-dir ] -narratio config diff [--config ] [--campaign | --campaign-file ] [--secrets-dir ] -``` - -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 -removed -changed +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 [--from ] [--through ] [--force] [--artifacts ] [...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 [--artifacts ] [...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 --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 [--force] [--artifacts ] [...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 [--artifacts ] [...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 --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 [--artifacts ] [...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 --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 [--dry-run] [--clear-cache] [...common config flags] -narratio clean --all [--dry-run] [--clear-cache] [--config ] +```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 [--from ] [--through ] [--force] [--artifacts ] [...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 [...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 [...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 --output ./session.yml [options] -narratio session init --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 ` - - `--remote` +## Migration from the previous CLI -Options: +Removed command paths have no compatibility aliases. -- `--config ` -- `--campaign ` or `--campaign-file ` -- `--secrets-dir ` -- `--previous-session-id ` -- `--date ` -- `--title ` -- `--audio-dir ` -- `--audio-s3-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 [--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 [--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 [...common config flags] -narratio session locks add [--reason ] [--force] [...common config flags] -narratio session locks remove [...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.`; -- does not filter built-in transcript/bounds or explicitly configured - `narratio.extraction.` 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. diff --git a/docs/config.md b/docs/config.md index b599a65..df3c58d 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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 ` 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.` 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.`: diff --git a/docs/internal/artifacts.md b/docs/internal/artifacts.md index 687b986..c335c97 100644 --- a/docs/internal/artifacts.md +++ b/docs/internal/artifacts.md @@ -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 diff --git a/docs/internal/configuration.md b/docs/internal/configuration.md index 46a8f14..639ef95 100644 --- a/docs/internal/configuration.md +++ b/docs/internal/configuration.md @@ -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.` 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. diff --git a/docs/internal/manifest.md b/docs/internal/manifest.md index 7292133..df52f1b 100644 --- a/docs/internal/manifest.md +++ b/docs/internal/manifest.md @@ -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` diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 1e7c55b..ebf97db 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -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`. diff --git a/docs/internal/stage-analyze.md b/docs/internal/stage-analyze.md index 698df95..d6327b8 100644 --- a/docs/internal/stage-analyze.md +++ b/docs/internal/stage-analyze.md @@ -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 diff --git a/docs/internal/stage-cleanup.md b/docs/internal/stage-cleanup.md index 2452e91..768e47f 100644 --- a/docs/internal/stage-cleanup.md +++ b/docs/internal/stage-cleanup.md @@ -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 ` directly; missing, failed, malformed, +`narratio run --stage cleanup` directly; missing, failed, malformed, or identity-mismatched publication evidence fails before deletion. ## Implementation And Tests diff --git a/docs/internal/stage-publish.md b/docs/internal/stage-publish.md index a8da561..4019a2d 100644 --- a/docs/internal/stage-publish.md +++ b/docs/internal/stage-publish.md @@ -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 diff --git a/docs/internal/workspace.md b/docs/internal/workspace.md index 7bdd1ff..4f8bb81 100644 --- a/docs/internal/workspace.md +++ b/docs/internal/workspace.md @@ -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 diff --git a/docs/operations.md b/docs/operations.md index aa20ef8..133c852 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -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 `. -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/.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.` 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 --force` after such edits. +polish with `narratio run --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. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index b44c41d..6c4e865 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 73fbfe9..2c7f690 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index cd60011..801f7cd 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -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 --force` to replace a +selectors require `narratio run --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). diff --git a/examples/README.md b/examples/README.md index b488207..50f1476 100644 --- a/examples/README.md +++ b/examples/README.md @@ -26,17 +26,22 @@ in the [configuration reference](../docs/config.md). Inspect it offline with: ```sh - narratio config validate --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml - narratio config show --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing - narratio config sources --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing - narratio config artifacts --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing - narratio config diff default testing --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml + narratio config validate --config examples/production-testing/pipeline.yml + narratio config show --config examples/production-testing/pipeline.yml --overlay testing + narratio config sources --config examples/production-testing/pipeline.yml --overlay testing + narratio artifacts list --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing + narratio config diff --against-config examples/production-testing/pipeline.yml --against-overlay testing --config examples/production-testing/pipeline.yml ``` These inspection commands load configuration and resolve explicit credential references, but do not load a session or create runtime state. This bundle is intentionally local-storage and credential-reference free so the walkthrough - needs no tools or cloud services. + needs no tools or cloud services. Native app inspection retains family + declarations; `artifacts list` derives their concrete members using the selected + campaign. Diff selects the example root on both sides because omitted + right-side selectors use their own discovery defaults. To isolate the + walkthrough from installed credential files, add `--secrets-dir` pointing to + an existing empty directory to each command. - [Full annotated pipeline](pipeline.full.annotated.yml): every implemented pipeline section with explanatory comments. - [Extraction subset pipeline](pipeline.extraction-subset.yml): a focused