Documentação

Todos os documentos estão disponíveis como Markdown puro para consumo por LLMs. Veja o llms.txt para o índice legível por máquina. O original em inglês é a versão de referência; cada documento em português abre com um link para ele. As páginas de referência hospedadas aqui são a edição para a JVM; cada runtime carrega a sua própria documentação no seu próprio repositório — comece por aí.

Por runtime

TypeScript — veja um trace em 60 segundos @narrativetrace/* — traceObject, o decorator @traced, a fixture do Vitest; 20 pacotes publicados no npm
Java — veja um trace em 60 segundos ai.narrativetrace no Maven Central — o plugin Gradle, o proxy, o JUnit 5
.NET — veja um trace em 60 segundos NarrativeTrace.* no nuget.org — NarrativeTraceProxy.Create, AddNarrativeTracing, a fixture do xUnit
Python — veja um trace em 60 segundos narrativetrace no PyPI — trace_object, o decorator @narrated, a fixture do pytest

Primeiros passos

Primeiros passos Escolha um runtime, veja um trace em 60 segundos, depois encontre os guias de instalação e de recursos

Conceitos centrais

Referência de anotações Referência de @Narrated, @OnError, @NotTraced e @NarrativeSummary
Níveis de captura Cinco níveis de OFF a DETAIL — a arquitetura de duas portas
Formatos de saída Markdown, JSON e prosa renderizados a partir de um único trace
Traces de aprovação narrativa Traces .nt sem valores, o delta desde o último verde, linhas de base de aprovação que quebram o build — 0.2.0
Diagnóstico de clareza Pontuação de qualidade de código a partir da narrativa de execução, com uma observação por elemento
Glossário de domínio e traces traduzidos Linguagem ubíqua colhida de execuções reais, aplicada no CI, traces no idioma do seu time — 0.2.0
Geração de diagramas Diagramas de sequência Mermaid e PlantUML

Integrações

TypeScript

Fixture do Vitest Fixture narrativeTest por teste — arquivos de trace automáticos, relatório de clareza e falhas por teste
Middleware Express Middleware que abre um contexto de trace a cada requisição, com extratores à prova de falhas
NestJS AutoProxyModule envolve automaticamente cada provider de DI — tracing sem código
Pino Envia os eventos de chamada para um logger Pino, com a identidade do trace também nas suas linhas de log
OpenTelemetry Converte as narrativas de chamada capturadas em spans do OpenTelemetry, ao vivo ou em lote

Java

Spring Boot @EnableNarrativeTrace, suporte a async, integração com Spring Boot
JUnit 5 Arquivos de trace por teste, delta desde o último verde, modo de aprovação, relatório de clareza
JUnit 4 Integração via @Rule para suítes de teste legadas
Ponte SLF4J Campos MDC, convivência com o logging existente
Agente Java Instrumentação de bytecode sem código; jar standalone para servidores de aplicação e WARs sem modificação
Micrometer Propagação de contexto entre threads para @Async e CompletableFuture
Plugin Gradle Configuração em um bloco; tarefas clarityCheck, glossaryScan e approveNarratives — 0.2.0

.NET

Microsoft.Extensions.Logging Encaminha os eventos de trace pelo seu ILogger, via decorator, exporter ou listener de DI
Middleware ASP.NET Core Contexto de trace por requisição com escopo próprio, exporters configuráveis, exclusão de rotas
Auto-wrap por DI AddNarrativeTracing decora automaticamente cada serviço de DI por namespace — sem tocar no código
xUnit NarrativeFixture narra o trace capturado automaticamente quando um teste falha
NUnit NarrativeTestBase conecta o contexto de setup/teardown e narra as falhas via TestContext
OpenTelemetry Exporta os traces como spans Activity do OpenTelemetry, ao vivo ou em lote

Python

Plugin pytest Fixture narrative_trace por teste, relatórios de trace em falhas, resumo de clareza da suíte
Middleware FastAPI / ASGI Uma árvore de trace por requisição HTTP; propaga os cabeçalhos W3C traceparent
structlog Um processor do structlog que injeta as mesmas chaves de correlação do trace em cada evento
OpenTelemetry Emite o trace capturado como spans do OpenTelemetry, ao vivo ou em lote

Análise, integração com IA e compliance

Visão geral Agregação, integração com IA, grafos de dependências e eventos de auditoria — acesso antecipado
Agregação de fluxos Resumos de fluxo, diffs de migração, análise de frequência de caminhos
Grafos de dependências Visualização de dependências de runtime como grafos Mermaid
Servidor MCP Servidor Model Context Protocol para agentes de IA — em breve
Auditoria e SecOps @AuditEvent, @SecurityEvent, políticas de compliance
Especificação de auditoria Inferência determinística, mascaramento de campos, classificação de dados

Arquitetura

Separação narrativa/valor Princípio central de design — separar a estrutura dos valores de runtime
Especificação de formatos de saída Especificações dos formatos JSON canônico, Markdown e prosa
Estrutura de módulos Organização, coordenadas e dependências dos módulos