Documentation

All docs are available as raw Markdown for LLM consumption. See llms.txt for the machine-readable index. Most of the reference pages for the JVM edition are hosted here; a few (GitHub links below) link straight to their guide in the narrativetrace-java repository instead of a second copy. Every runtime carries its own documentation in its own repository — start there.

By runtime

TypeScript — see a trace in 60 seconds @narrativetrace/* — traceObject, the @traced decorator, the Vitest fixture; 20 packages live on npm
Java — see a trace in 60 seconds ai.narrativetrace on Maven Central — the Gradle plugin, the proxy, JUnit 5
.NET — see a trace in 60 seconds NarrativeTrace.* on nuget.org — NarrativeTraceProxy.Create, AddNarrativeTracing, the xUnit fixture
Python — see a trace in 60 seconds narrativetrace on PyPI — trace_object, the @narrated decorator, the pytest fixture

Getting Started

Getting Started Pick a runtime, see a trace in 60 seconds, then find the installation and feature guides for what comes after

Core Concepts

Annotations @Narrated, @OnError, @NotTraced, @NarrativeSummary reference
Capture Levels Five levels from OFF to DETAIL — two-gate architecture
Output Formats Markdown, JSON, and prose rendering from a single trace
Narrative Approval Traces Value-free .nt traces, the delta since last green, approval baselines that fail the build — 0.2.0
Clarity Diagnostics Code quality scoring from runtime narrative, with a note per element
Domain Glossary & Translated Traces Ubiquitous language harvested from real runs, enforced in CI, traces in your team's language — 0.2.0
Diagrams Mermaid and PlantUML sequence diagram generation

Integrations

TypeScript

Vitest fixture Per-test narrativeTest fixture — automatic trace files, per-test clarity and failure reporting
Express middleware Per-request middleware opening one trace context per request, with fail-safe extractors
NestJS AutoProxyModule auto-wraps every DI provider — zero-code tracing
Pino Streams call events into a Pino logger, trace identity stamped on your own log lines too
OpenTelemetry Maps captured call narratives onto OpenTelemetry spans, live or as a batch export

Java

Spring Boot @EnableNarrativeTrace, async support, Spring Boot starter
JUnit 5 Per-test trace files, delta since last green, approval mode, clarity reporting
JUnit 4 @Rule-based integration for legacy test suites
SLF4J Bridge MDC fields, coexistence with existing logging
Java Agent Zero-code bytecode transformation; standalone jar for app servers and unmodified WARs
Micrometer Cross-thread context propagation for @Async and CompletableFuture
Gradle Plugin One-block setup; clarityCheck, glossaryScan, and approveNarratives tasks — 0.2.0

.NET

Microsoft.Extensions.Logging Routes trace events through your existing ILogger via a decorator, exporter or DI listener
ASP.NET Core middleware Per-request scoped tracing context, pluggable exporters, path exclusion
DI auto-wrap AddNarrativeTracing decorates every DI-registered service by namespace — no code changes
xUnit NarrativeFixture narrates the captured trace automatically when a test fails
NUnit NarrativeTestBase wires setup/teardown context and narrates failures via TestContext
OpenTelemetry Exports traces as OpenTelemetry Activity spans, live or as a batch export

Python

pytest plugin Per-test narrative_trace fixture, failure trace reports, clarity-score suite summary
FastAPI / ASGI middleware One trace tree per HTTP request; propagates W3C traceparent headers
structlog Processor that injects the same trace correlation keys into every structlog event
OpenTelemetry Emits the captured trace as OpenTelemetry spans, live or as a batch export

Analysis, AI Integration & Compliance

Overview Aggregation, AI integration, dependency graphs and audit events — early access
Aggregation Flow summaries, migration diffs, path frequency analysis
Dependency Graphs Runtime dependency visualization as Mermaid graphs
MCP Server Model Context Protocol server for AI coding agents — coming soon
Audit & SecOps @AuditEvent, @SecurityEvent, compliance policies
Audit Specification Deterministic inference, field masking, data classification

Architecture

Narrative/Value Separation Core design principle — separating structure from runtime values
Output Format Specification Canonical JSON, Markdown, and prose format specs
Module Structure Module organization, coordinates and dependencies