eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Consolidate the D&D configuration examples

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-25 15:48:48 +00:00
parent 29ee68824d
commit 9614469b45
27 changed files with 296 additions and 313 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/cli.md
View File

@@ -88,7 +88,7 @@ Use `slot=path` when the selected targets declare the slot unambiguously:
```sh
go run ./cmd/notarius run dnd-session \
--config examples/dnd-spells.config.yml \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json \
--reference roster=./campaign-roster.txt
```
@@ -98,7 +98,7 @@ when you want to target a specific target:
```sh
go run ./cmd/notarius run dnd-session \
--config examples/dnd-spells.config.yml \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json \
--reference spells.extract.glossary=./campaign-glossary.txt
```
@@ -109,8 +109,8 @@ it in memory and fans it out to spell extraction, combat extraction, and combat
normalization:
```sh
go run ./cmd/notarius run dnd-npc-grounded \
--config examples/dnd-npc-grounded.config.yml \
go run ./cmd/notarius run dnd-session \
--config examples/dnd-complete.config.yml \
--input examples/seriatim-minimal-transcript.json \
--output-dir ./npc-grounded-output
```
@@ -135,7 +135,7 @@ Use `--without-reference` to remove a configured optional binding for a run:
```sh
go run ./cmd/notarius run dnd-session \
--config examples/dnd-spells.config.yml \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json \
--without-reference glossary
```
@@ -145,7 +145,7 @@ run to share an identifier:
```sh
go run ./cmd/notarius run dnd-session \
--config examples/dnd-spells.config.yml \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json \
--session-id campaign-17-session-04
```
@@ -156,7 +156,7 @@ recorded work; using it while checkpoint recording is disabled is an error:
```sh
go run ./cmd/notarius run dnd-session \
--config examples/dnd-spells.config.yml \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json \
--resume
```
@@ -166,10 +166,10 @@ from the configuration. The selected step and dependents are reported as
`forced_recompute`; reusable predecessors are reported as `reused`:
```sh
go run ./cmd/notarius run dnd-npc-grounded \
--config examples/dnd-npc-grounded.config.yml \
go run ./cmd/notarius run dnd-session \
--config examples/dnd-complete.config.yml \
--input examples/seriatim-minimal-transcript.json \
--resume --recompute-step grounded-events
--resume --recompute-step extract-events
```
Checkpoint decisions use these categories: `reused`, `executed`,
@@ -187,7 +187,7 @@ code `1`.
```sh
go run ./cmd/notarius run dnd-session \
--config examples/dnd-spells.config.yml \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json \
--debug --debug-dir ./notarius-debug
```
@@ -196,7 +196,7 @@ Use `refresh` when intentionally replacing the cached plan for the same source:
```sh
go run ./cmd/notarius run dnd-session \
--config examples/dnd-spells.config.yml \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json \
--chunk_cache refresh
```
@@ -205,7 +205,7 @@ Use `bypass` for a one-off run that must not inspect or create plan-cache state:
```sh
go run ./cmd/notarius run dnd-session \
--config examples/dnd-spells.config.yml \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json \
--chunk_cache bypass
```
@@ -230,10 +230,10 @@ Examples:
```sh
go run ./cmd/notarius config validate \
--config examples/dnd-spells.config.yml
--config examples/dnd-minimal.config.yml
go run ./cmd/notarius config validate \
--config examples/dnd-spells.config.yml \
--config examples/dnd-minimal.config.yml \
--pipeline dnd-session \
--only spells
```
@@ -252,10 +252,10 @@ Examples:
```sh
go run ./cmd/notarius pipelines list \
--config examples/dnd-spells.config.yml
--config examples/dnd-minimal.config.yml
go run ./cmd/notarius pipelines list \
--config examples/dnd-spells.config.yml \
--config examples/dnd-minimal.config.yml \
--json
```

31
docs/config.md
View File

@@ -19,15 +19,14 @@ The explicit-path option is defined in the [CLI reference](cli.md).
## Maintained Examples
- [Minimal D&D spell configuration](../examples/dnd-spells.config.yml)
- [Production-oriented D&D spell configuration](../examples/dnd-spells-production.config.yml)
- [D&D NPC configuration](../examples/dnd-npcs.config.yml)
- [D&D combat-turn configuration](../examples/dnd-combat-turns.config.yml)
- [D&D NPC-grounded spell and combat configuration](../examples/dnd-npc-grounded.config.yml)
- [D&D NPC interaction configuration](../examples/dnd-npc-interactions.config.yml)
- [D&D scene chunk-map configuration](../examples/dnd-scene-chunk-map.config.yml)
- [Minimal D&D configuration](../examples/dnd-minimal.config.yml) shows the
shortest useful single-step, single-lane pipeline.
- [Complete D&D configuration](../examples/dnd-complete.config.yml) shows scene
chunking, ordered steps, all five D&D artifact lanes, a generated NPC
handoff, campaign and spell-catalog references, checkpoint storage, and
chunk-map output.
All are complete version 3 files. The fragments below illustrate individual
Both are complete version 3 files. The fragments below illustrate individual
fields and are not alternate complete configurations.
## Top-Level Fields
@@ -347,9 +346,9 @@ output:
```
The payload and index descriptor are defined by the
[Accepted Chunk Map contract](integrations/chunk-map.md). See the complete
[D&D scene chunk-map configuration](../examples/dnd-scene-chunk-map.config.yml)
for a copyable pipeline.
[Accepted Chunk Map contract](integrations/chunk-map.md). See the
[complete D&D configuration](../examples/dnd-complete.config.yml) for a
copyable pipeline that enables this option.
Validator bindings use the same shorthand or object module-binding form, but
only these fields are supported:
@@ -563,17 +562,17 @@ bound.
The `dnd/npcs` extractor declares the same optional campaign slots as the spell
extractor, but it does not declare the `npcs` registry slot. Its normalizer
accepts no references. The maintained
[NPC-grounded example](../examples/dnd-npc-grounded.config.yml) binds its
accepted normalized output to the later spell and combat targets through an
explicit ordered step.
accepts no references. The
[complete D&D example](../examples/dnd-complete.config.yml) binds its accepted
normalized output to later spell, combat-turn, and NPC-interaction targets
through an explicit ordered step.
The `dnd/scene-descriptions` extractor accepts only the optional `players`,
`party`, and `glossary` campaign slots. They can disambiguate terms in the
model-facing title and summary but are never source evidence. Its normalizer
accepts no references. No NPC registry or generated artifact is required. See
the [D&D scene-description artifact contract](integrations/dnd-scene-description-artifacts.md)
and the copyable [scene-description configuration](../examples/dnd-scene-descriptions.config.yml).
and the copyable [complete D&D configuration](../examples/dnd-complete.config.yml).
The `dnd/combat-turns` extractor declares the optional campaign slots and the
structured `npcs` slot. Campaign references guide only the LLM extraction

2
docs/integrations/dnd-npc-interaction-artifacts.md
View File

@@ -145,4 +145,4 @@ framework provenance and dependency fingerprints.
See [Configuration](../config.md#implemented-production-modules) for selectable
keys and chains, [the NPC artifact contract](dnd-npc-artifacts.md) for the
registry boundary, and the copyable
[maintained example](../../examples/dnd-npc-interactions.config.yml).
[complete D&D example](../../examples/dnd-complete.config.yml).

6
docs/integrations/dnd-scene-description-artifacts.md
View File

@@ -115,6 +115,6 @@ bounded and do not copy transcript or campaign-reference content.
Use `dnd/scenes` to form accepted scene chunks, then select
`dnd/scene-descriptions` for extraction and normalization. The maintained
[scene-description configuration](../../examples/dnd-scene-descriptions.config.yml)
is a copyable minimal lane. Selectable keys and default validator chains are
defined in [Configuration](../config.md).
[complete D&D configuration](../../examples/dnd-complete.config.yml) includes
this lane alongside the other D&D artifacts. Selectable keys and default
validator chains are defined in [Configuration](../config.md).

13
docs/operations.md
View File

@@ -48,15 +48,16 @@ needed. This is data deletion, not cache cleanup.
## Ordered D&D Workflow
The maintained [NPC-grounded configuration](../examples/dnd-npc-grounded.config.yml)
The maintained [complete D&D configuration](../examples/dnd-complete.config.yml)
contains one pipeline with two ordered steps. The first step extracts and
normalizes NPCs. Only after that lane reaches an accepted terminal result does
the second step begin; its generated NPC reference is supplied in memory to
spell extraction, combat extraction, and combat normalization.
normalizes NPCs and scene descriptions. Only after those lanes reach accepted
terminal results does the second step begin; its generated NPC reference is
supplied in memory to spell, combat-turn, and NPC-interaction extraction and
the applicable normalizers.
```sh
go run ./cmd/notarius run dnd-npc-grounded \
--config examples/dnd-npc-grounded.config.yml \
go run ./cmd/notarius run dnd-session \
--config examples/dnd-complete.config.yml \
--input examples/seriatim-minimal-transcript.json \
--output-dir ./npc-grounded-output
```