# D&D Subprocess Consumer Documentation

## Status

Completed. The target guide is `docs/consumers/dnd-pipeline.md`.

## Purpose

Provide one task-oriented guide for applications that run Notarius as a
subprocess to execute the maintained complete D&D pipeline and consume its
published artifacts. The initial concrete consumer is Narratio, but the guide
must describe the public Notarius workflow rather than depend on Narratio
internals.

The guide should make the safe integration path obvious without duplicating
the CLI, input, receipt, output-bundle, or individual artifact contracts that
already have canonical documentation.

## Current State

The public integration surface is documented accurately but is distributed
across several documents:

- `docs/consumers/subprocess.md` defines the generic subprocess workflow;
- `docs/cli.md` owns commands, flags, stream behavior, and exit statuses;
- `docs/integrations/seriatim.md` owns the accepted transcript input shape;
- `docs/integrations/run-result.md` owns the machine-readable successful-run
  receipt;
- `docs/integrations/json-output.md` owns bundle discovery and logical files;
- the D&D integration documents own the individual lane payload contracts;
- `examples/dnd-complete.config.yml` is the maintained complete pipeline.

A consumer can reconstruct the full workflow from those documents, but there
is no D&D-focused guide that connects the maintained example to its input,
invocation, complete artifact inventory, discovery procedure, and downstream
acceptance decisions.

## Target Documentation Set

### Create `docs/consumers/dnd-pipeline.md`

This document should own the end-to-end consumer workflow for the maintained
complete D&D configuration. It should be useful to Narratio and to another
subprocess orchestrator with the same needs.

The guide should contain the following sections.

#### Prerequisites And Deployment Configuration

- Link to `examples/dnd-complete.config.yml` rather than embedding a second
  complete configuration.
- Explain that a deployment must provide the configured PromptKit profile and
  campaign reference files.
- Recommend absolute paths for a service or orchestrator deployment.
- Call out the path-resolution distinction explicitly: YAML reference paths
  are relative to the Notarius configuration file, while
  `promptkit.profile_file` is relative to the Notarius process working
  directory.
- Recommend validating the selected configuration and `dnd-session` pipeline
  before processing sessions.

#### Transcript Input

- State that the complete pipeline consumes a Seriatim JSON document.
- Link to the canonical Seriatim contract for required fields and validation.
- Recommend the caller's final trimmed transcript when the caller maintains
  transcript tiers. For Narratio, identify the implemented source as
  `narratio.transcript.final_trimmed`, normally stored at
  `transcripts/final.trimmed.json`.
- Explain that segment IDs must remain stable because D&D source references
  cite those units.
- Explain that Notarius derives its default prompt session from the input
  module and exact input bytes and that ordinary callers should not supply
  `--session-id`.

#### Subprocess Invocation

- Show one concise invocation using `notarius run dnd-session`, explicit
  absolute `--config`, `--input`, and `--output-dir` paths, and `--json`.
- Direct callers to capture stdout and stderr separately, propagate
  cancellation, impose an operator-appropriate timeout, and wait for process
  completion before parsing stdout.
- State that only exit status zero permits receipt decoding and link to the CLI
  contract for the complete exit-status definition.
- Recommend retaining stderr and the invocation context for diagnosis without
  logging secrets or transcript content.

#### Receipt And Bundle Discovery

- Require callers to accept only supported run-result schema versions while
  tolerating unknown fields allowed by that version.
- Direct callers to obtain the exact run-specific bundle from the receipt's
  absolute `output_directory`; they must not scan for the newest run directory
  or construct a run ID.
- Require a confinement check when resolving `index_file` beneath the reported
  bundle root.
- Direct callers to discover lane payloads by `lane_id` in `index.json`, then
  verify descriptor media type and schema identity before decoding them.
- Explain that descriptor paths are untrusted relative paths and require the
  same confinement discipline.

#### Complete D&D Artifact Inventory

Include a compact table for the ten lane IDs selected by the maintained
complete configuration:

- `item-registry`;
- `npc-registry`;
- `location-registry`;
- `scene-descriptions`;
- `item-occurrences`;
- `spells`;
- `combat-turns`;
- `npc-occurrences`;
- `location-occurrences`;
- `enemy-events`.

For each row, give a one-line purpose and link to the corresponding canonical
D&D artifact contract. Do not copy its fields or schema rules into the
consumer guide.

Document the four always-published bundle files—`index.json`, `manifest.json`,
`rejected.json`, and `warnings.json`—and the complete example's configured
`chunk-map.json` and `evidence-context.json` pipeline-wide artifacts. Link to
their canonical contracts and distinguish pipeline-wide artifacts from lane
outputs.

The inventory must say that a file is available only when its corresponding
artifact was accepted and published. It must not imply that process success
guarantees every configured lane.

#### Downstream Acceptance And Retention

- Explain that exit status zero can coexist with rejected outputs, warnings,
  or absent lane descriptors.
- Require the consumer to define its required lane set explicitly. Recommend
  treating all ten lanes as required when the caller claims to consume the
  complete D&D workflow, while allowing another consumer to adopt a narrower
  documented policy.
- Recommend retaining the receipt, the complete published bundle, and captured
  diagnostic streams long enough to support provenance and failure analysis.
- Explain that `evidence-context.json` is a reading excerpt; authoritative
  citations remain in lane payloads.
- Treat transcripts, lane artifacts, evidence context, manifests, and logs as
  sensitive campaign data.

#### Compatibility Checklist

End with a concise checklist covering process exit, receipt schema, path
confinement, pipeline identity, index decoding, required descriptors,
descriptor schema/media compatibility, warnings and rejections, checksums or
retention, and secure handling. Compatibility should be based on published
receipt and artifact contracts rather than parsing a human version string.

### Update Existing Navigation

- Add a short link from `docs/consumers/subprocess.md` to the D&D-specific
  workflow. Keep generic subprocess policy in the existing document.
- Add the guide to the documentation links in `README.md`.
- Extend the subprocess-consumer row in `docs/development.md` so maintainers
  working on the D&D workflow are routed to the new guide and the canonical
  contracts.

### Verify Canonical Contract Documents

Review the linked integration documents and the complete example while writing
the guide. Correct an integration document only if repository inspection finds
an actual stale contract. Do not move schema definitions, field tables, CLI
flags, or configuration semantics into the new guide.

## Narratio Alignment

The guide may name Narratio as the motivating consumer and identify its current
final-trimmed transcript source. It must not claim that Narratio already has a
Notarius adapter or extraction stage. Until that feature is implemented,
Narratio-specific architecture, configuration, stage behavior, manifest
records, and artifact source IDs belong in Narratio's roadmap.

Once Narratio implements the integration, its own integration documentation
should link to this guide and the durable Notarius contracts instead of
repeating them.

## Validation

Documentation implementation should include:

```sh
go run ./cmd/notarius config validate \
  --config examples/dnd-complete.config.yml \
  --pipeline dnd-session
go test ./...
```

Also verify all new and changed relative Markdown links, compare the artifact
inventory directly with the maintained complete configuration, and confirm
that commands and path semantics match the CLI and configuration references.
If the repository still has no automated link checker, record that fact and
perform a focused manual link review.

## Acceptance Criteria

- A subprocess integrator can follow one D&D-focused guide from a Seriatim
  transcript through safe discovery of every artifact configured by the
  complete example.
- The guide makes stdout, stderr, exit-status, receipt, and path-confinement
  responsibilities unambiguous.
- The ten configured D&D lanes and both configured pipeline-wide artifacts are
  listed and linked to their canonical contracts.
- The guide distinguishes process success from the caller's required-artifact
  policy.
- The profile-path and reference-path resolution rules are clearly stated.
- Existing navigation makes the guide discoverable.
- No volatile contract is defined in two places, and no unimplemented Narratio
  behavior is presented as current.

## Non-Goals

- Implementing or documenting Narratio's future adapter or stage as current
  Notarius behavior.
- Adding a new Notarius command, receipt version, output format, or artifact
  schema.
- Duplicating the complete configuration or individual D&D payload schemas in
  prose.
- Defining a universal partial-result policy for every Notarius consumer.
