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.

Skill Files: Thin Pointers to Canonical Prompts#

Agent tooling lives in .claude/skills/. Each skill is a YAML-frontmatter file with a name, a description that controls when the IDE surfaces it, and a short body. The body itself stays thin and defers to the canonical prompt in docs/prompts/.

The two skills that exist cover the work "most likely to go wrong" 3:

• new-source-parser (.claude/skills/new-source-parser/SKILL.md) — triggered when adding a new session format, modifying existing parsers, or debugging incorrect ingest. The skill body summarizes the key invariants (no throwing, no printing, synthetic fixtures only) and delegates the full multi-stage workflow to docs/prompts/add-source.md.
• new-migration (.claude/skills/new-migration/SKILL.md) — triggered when touching src/db.ts, src/schema.sql, or src/schema-manifest.ts. Contains the self-contained rule set (freeze-on-commit, guarded migrations, schema.sql alignment) because the migration workflow doesn't have a separate canonical prompt.

This pattern means a reader or agent consulting a skill file gets just enough context to act correctly, while the full authoritative detail stays in one place and is updated once.

Canonical Prompt: docs/prompts/add-source.md#

docs/prompts/add-source.md is the authoritative, agent-executable workflow for adding a new source parser. It is structured as a top-to-bottom procedural document with hard-requirement callouts (privacy rules) before any steps. CONTRIBUTING.md points to it directly: "Adding support for a new agent CLI? Follow the agent-executable prompt in docs/prompts/add-source.md" 4.

The prompt's multi-stage structure covers 5:

1. Discovery — file location resolution and sidecar exclusion (src/ingest.ts: discover())
2. Parser — src/sources/<tool>.ts exporting a pure, print-free parse<Tool>Session() function
3. Tool ID — wire string added to TOOLS in src/model.ts (snake_case, stored in SQLite)
4. Watch root — extend watchDirs() in src/watch.ts for serve mode
5. Capability report — a required PR-description table declaring what token/cost data the source exposes
6. 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
7. Tests — parser tests, synthetic fixtures, ingest tests, golden updates
8. Definition of done — bun test && bunx tsc --noEmit && bunx biome check . green plus an aggregate-only parity run against a real store

Privacy Rules as First-Class Documentation#

Privacy constraints appear before any technical steps in docs/prompts/add-source.md 6 and are repeated in AGENTS.md 7 and the new-source-parser skill 8. The duplication is intentional: these rules are hard requirements and must be visible regardless of which entry point the contributor reaches first.

Other docs/ Reference Files#

2

Key Relationships#