narrative

What It Does

narrative reads selected snapshot history, commit-bound documents, artifact records, and event data, then writes a self-contained HTML narrative report. The report is designed for a new contributor or agent that needs to understand the project's intent, decisions, and timeline without replaying the entire collaboration history.

The canonical face of that report is the Recovery View: Recover Now, What To Trust, and How We Got Here.

Operationally, treat the command in two layers:

The HTML file is the canonical report.
--emit-model is optional and exists only to feed the separate experimental OpenTUI viewer.

When To Use / When Not To Use

When to use it

You want a compact handoff view of how a project decision evolved.
You want to explain project knowledge as a narrative instead of as raw logs.
You want a standalone HTML artifact that can be opened outside the CLI.

When not to use it

You need the current repository summary only. Use status.
You need snapshot semantic deltas. Use log.
You need append-only operational events. Use timeline.
You need retrieval hits or live question answering. Use query.

Operating Procedure

Use narrative in this order:

Generate the canonical HTML report.
Add --emit-model only when you also need local terminal exploration.
Open the isolated viewer from tools/narrative-tui/ only after the model file exists.

The operational success rule is simple:

If the HTML report was generated, the main task succeeded.
If the viewer later fails, treat that as an explorer failure, not as a narrative generation failure.

Syntax

pnpm ragit narrative [revRange] [--max-commits <n>] \
  [--output <path>] [--emit-model <path>] \
  [--open] [--dry-run] \
  [--format text|json|both] [--cwd <path>]

Arguments And Options

[revRange]: Optional git revision range to scan. If omitted, HEAD is used.
--max-commits <n>: Limit the number of selected snapshot commits. The default is 10.
--output <path>: Write the HTML report to a specific path instead of the default .ragit/reports/narrative/<anchorSha>.html.
--emit-model <path>: Write the versioned viewer-safe narrative JSON model for a separate viewer. This is intended only for the isolated experimental OpenTUI explorer under tools/narrative-tui/.
--open: Open the generated report in the default browser after writing it.
--dry-run: Compute the report plan and summary without writing files.
--format text|json|both: Choose human text, JSON, or both.
--cwd <path>: Run against another repository.

Input And Output Contract

There is no JSON payload input.
JSON output includes dryRun, reportPath, modelPath, schemaVersion, projectionPolicyVersion, projectionMode, headSha, window, summary, and warnings.
window includes revRange, maxCommits, selectedSnapshotShas, and missingSnapshotCommits.
summary.freshnessCounts includes fresh, suspect, and stale counts derived from ragit drift.
--dry-run still returns the planned report path, planned model path, and summary, but writes neither file.
--open is ignored during dry-run and reported only as a warning.
If no manifest-backed snapshots are found, narrative still generates an empty-state report.

Canonical HTML vs Experimental Viewer

The self-contained HTML report is the canonical narrative artifact.
The canonical narrative face is the Recovery View, organized as Recover Now, What To Trust, and How We Got Here.
--emit-model exists only to support a separate local OpenTUI explorer.
The emitted model is versioned and viewer-safe.
schemaVersion is the structural compatibility key.
projectionPolicyVersion is the public projection governance key.
projectionMode is currently fixed to viewer-safe.
producerVersion is producer metadata only.
Current ragit narrative --emit-model writes a versioned model with a versioned projection policy. Legacy unversioned models exist only for backward-compatible viewer reads.
The viewer is intentionally isolated under tools/narrative-tui/ and does not read .ragit or git state directly.
If you only need a shareable report, generate HTML and stop there.

Recovery View

Recover Now shows the current goal, active constraints, open loops, the next action, and the shortest re-entry path.
What To Trust shows freshness, validation, and trust badges from the projected memory state.
How We Got Here compresses lineage, formation steps, drift or repair, and the evidence that shaped the current state.
The Recovery View reuses the same projected memory model that powers the rest of ragit; it does not introduce a new store or a parallel memory system.
For the split between active and durable memory, see Memory Model Guide.

Freshness Overlay

The narrative report carries a separate freshness axis in addition to trust, sensitivity, and lineage.
Freshness is derived from ragit drift and uses fresh, suspect, and stale.
fresh means the item is currently aligned with the selected snapshot window.
suspect means the item has incomplete baseline, binding, or evidence context.
stale means the item is anchored to paths, bindings, or dependencies that have drifted.
Freshness applies to the projected narrative model and to the HTML report; the OpenTUI viewer only consumes the exported freshness state and does not recompute drift.

Validation Overlay

The narrative report also carries a separate validation axis in addition to freshness, trust, sensitivity, and lineage.
Validation is derived from harness/drift assets and uses verified, attention, and unverified to describe current validation posture.
verified means the item has supporting harness/evidence context and no current validation concern.
attention means the item has a validation warning, usually from drift or failure evidence.
unverified means the item does not yet have enough validation context to classify confidently.
Validation describes current posture, not the full verification chronology.
Validation applies to the projected narrative model and to the HTML report; the OpenTUI viewer only consumes the exported validation state and does not recompute it.
The HTML report includes a dedicated Validation Panel, and the OpenTUI right rail is Intent | Validation | Timeline.

Projection Governance

The emitted model includes only viewer-safe projected fields.
Binding metadata is exposed as counts, not as raw goal/session identifiers.
trust badges distinguish durable-doc, reviewed-artifact, promoted-artifact, and operational-event.
sensitivity badges distinguish standard, redacted, and restricted.
Freshness badges distinguish fresh, suspect, and stale as a separate axis derived from ragit drift.
restricted means the viewer receives only the safe projected summary of the hidden binding state.

Examples

Generate the default narrative report:

pnpm ragit narrative

Limit the report window and open the result:

pnpm ragit narrative HEAD~20..HEAD --max-commits 5 --open

Preview the report plan as JSON:

pnpm ragit narrative --dry-run --format json

Generate HTML plus a sanitized model, then open the experimental local explorer:

pnpm ragit narrative --emit-model .ragit/reports/narrative/current.model.json
cd tools/narrative-tui
bun run start -- --model ../../.ragit/reports/narrative/current.model.json

Failures And Cautions

--output writes a file, so make sure the parent directory is writable.
--emit-model also writes a file and should be treated as viewer input, not as a replacement for the canonical HTML report.
schemaVersion and projectionPolicyVersion are the compatibility keys for the emitted model. If a future viewer rejects either one, the HTML report is still the canonical successful output.
The report is derived from snapshot-backed knowledge, not from raw transcripts.
--open is best-effort and may be skipped if no opener exists on the current machine.
When no snapshot manifests exist in the selected window, the command still succeeds with an empty-state report.

narrative

On this page