Document the native CLI and migration workflows
This commit is contained in:
@@ -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>`:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user