Documentation Architecture#

Decant's documentation is organized around a single canonical source of truth principle: one authoritative document per topic, with all other entry points staying thin and deferring to it.

The Canonical Hub: AGENTS.md / CLAUDE.md#

AGENTS.md is the primary reference for commands, conventions, and project invariants for both human contributors and AI coding agents. CLAUDE.md is a symlink to this file — tool-specific files stay thin and defer here 1. CONTRIBUTING.md is explicitly the "shorter on-ramp," directing readers to AGENTS.md for the canonical content.

Layout pointers live in AGENTS.md: entry point (src/cli.ts), parsers (src/sources/), and the docs/ subdirectories for the API contract, serve semantics, distribution, and release operations 2.

Source Parser Contribution Guide#

docs/adding-a-source.md is the canonical checklist for adding a new source parser. It is structured as a top-to-bottom procedural document with privacy rules before any technical steps. CONTRIBUTING.md points contributors there: "New source parser, following Add a source" 3.

The guide covers:

1. Privacy rules — synthetic fixtures only, aggregate shapes only, no real transcript content
2. Discovery — file location resolution and sidecar exclusion (src/ingest.ts: discover())
3. Parser — src/sources/<tool>.ts exporting a pure, print-free parser function
4. Tool ID — wire string added to TOOLS in src/model.ts (snake_case, stored in SQLite)
5. Watch root — extend watchDirs() in src/watch.ts for serve mode
6. Capability report — a required PR-description table declaring what token/cost data the source exposes
7. Parser rules — error accumulation (never throw), unknown-record-type tracking as a format-drift sensor, normalization to NormalizedSession, MCP tool-name normalization, one session per file
8. Tests — parser tests, synthetic fixtures, ingest tests, golden updates
9. Definition of done — just check green plus an aggregate-only parity run against a real store

This guide is the single entry point for parser contributions, ensuring privacy rules, capability reporting, and testing standards are visible from the start.

Other docs/ Reference Files#

2

Key Relationships#