Document the native CLI and migration workflows

This commit is contained in:
2026-11-20 06:41:59 +00:00
parent faa8cb5822
commit 0e9cbc9c2a
16 changed files with 633 additions and 672 deletions

View File

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