# AGENTS.md

Guidance for coding agents and contributors working in this repository. Keep
changes small, tested, and consistent with the patterns already present.
`CLAUDE.md` is a symlink to this file so project guidance has one source of
truth.

## Project overview

Decant is a local-first Bun and TypeScript application that turns Claude Code,
Codex, Gemini CLI, and GitHub Copilot CLI JSONL session logs, OpenCode's
SQLite session store, Cursor CLI's per-chat SQLite stores, Copilot Chat in
VS Code's chat session files, and imported ATIF trajectory files into a
normalized, full-text-searchable SQLite archive. The `decant` CLI owns
parsing, ingest, reads, reports, distillation, recommendations, watch mode, and
the React UI served by `decant serve`.

Start with these files and guides:

- `src/cli.ts` and `src/cli/` handle command composition, output, and exit-code
  policy.
- `src/sources/` contains source parsers and the primary extension point.
- `src/db.ts`, `src/schema.sql`, and `src/schema-manifest.ts` manage storage
  and schema.
- `src/server.ts` and `src/ui/` serve the local API and web UI.
- `docs/architecture.md` maps module boundaries and data flow.
- `docs/analytics-methodology.md` details metric definitions.
- `docs/data-lifecycle.md` describes sync and local state.
- `docs/sources.md` lists each source's default location, overrides, and
  user-facing caveats.
- `docs/api/openapi.yaml` defines the local API contract.
- `docs/distribution.md` covers npm, installer, Homebrew, Docker, and source
  builds.
- `docs/adding-a-source.md` provides the parser contribution checklist.
- `docs/contribution-triage.md` is the procedure for triaging outside pull
  requests.

## Setup and commands

Run commands from the repository root. Bun 1.3 or newer is required. Docker is
only needed when validating the container image.

- `bun run dev` performs a frozen dependency install, startup sync, local UI,
  and source watcher.
- `bun run src/cli.ts --help` runs the CLI from source.
- `bun test` runs the test suite.
- `bunx tsc --noEmit` runs the type check.
- `bunx biome check .` runs the formatting and lint check.
- `just check` runs the full local gate, including the native distribution
  staging smoke. It needs network access because the smoke packs and installs
  the npm launcher packages.

The default archive is `~/.decant/decant.db`. Override it with `DECANT_DB` or
`--db`. Set `DECANT_NO_SYNC` or pass `--no-sync` whenever a command points at a
scratch archive, or automatic sync may populate it from the real Claude Code,
Codex, Gemini CLI, OpenCode, Cursor CLI, GitHub Copilot CLI, and VS Code
directories.

## Definition of done

A change is ready when:

- `bun test` passes.
- `bunx tsc --noEmit` passes.
- `bunx biome check .` passes.
- New behavior has focused tests. Do not weaken or delete tests to make a
  change pass.
- Distribution changes get a native binary smoke test. Docker changes also get
  a local `docker build` and `docker run --help` smoke when Docker is
  available.
- User-visible command, route, configuration, or metric changes update their
  corresponding public docs.

## Project invariants

1. **Core modules stay print-free.** Parsing, ingest, query, stats, distill,
   recommendations, and database helpers return data or structured errors.
   Human-readable CLI output and exit codes belong in `src/cli.ts` and `src/cli/`.
2. **One process owns SQLite.** The CLI process opens the archive directly. WAL
   mode allows reads and ingest to coexist, so do not add another process that
   opens the database behind a separate contract.
3. **Runtime stays local-first.** Do not add outbound network calls, hosted
   service dependencies, or LLM calls. The only runtime networking is the local
   UI and API served by `decant serve`, bound to loopback by default. The one
   exception lives in `src/update.ts`, a once-a-day npm registry version check
   that stays off until the user turns it on, and the release downloads
   `decant update` makes when the user runs it. Neither sends archive data.
4. **Costs reflect current pricing.** `estimateCost` in `src/cost.ts` is applied
   when a session is written. Every sync reconciles stored session and activity
   costs with current rates, preserving transcripts and user state.
5. **Schema constants are the source of truth.** Use `LATEST_SCHEMA_VERSION` in
   `src/db.ts` rather than copying the current number into documentation.
   Unsupported older archives are rebuild-only. A migration is frozen once
   committed because someone may already have opened an archive with that
   branch, so put later schema adjustments in a new migration. Bump
   `INGEST_PIPELINE_REVISION` whenever unchanged sources must be re-derived so
   the next sync backfills them once and later syncs stay idempotent.
6. **Parsers are the extension point.** A new source requires
   `src/sources/<tool>.ts`, hand-written synthetic fixtures, parser tests,
   ingest/query coverage, and reviewed golden updates. Follow
   `docs/adding-a-source.md`.
7. **Serve routes are a documented local API.**
   `docs/api/openapi.yaml` is the source contract and `/api/openapi.json` is its
   runtime representation. Keep the implementation, OpenAPI document, route
   guide, and contract tests in sync.

## Security and privacy

- Never commit secrets, API keys, tokens, `.env` files, private keys, real
  transcripts, exports from real sessions, or personal archive databases.
- `~/.claude`, `~/.codex`, `~/.copilot`, VS Code's `User` directory, and the
  other source directories
  contain private content. Fixtures must be written from scratch, and
  `test/golden/` must be generated only from those synthetic fixtures.
- Keep source parsing resilient, meaning malformed records should become
  diagnostics, not crashes or leaked transcript content.
- Non-loopback serving must require explicit trusted-peer configuration. Treat
  `Host` and browser-origin checks as defense in depth, not authentication.

## Conventions

- Use surrounding code style, narrow changes, and focused tests.
- Use Conventional Commit prefixes such as `feat:`, `fix:`, `docs:`, `test:`,
  and `chore:`. Sign commits when the environment supports it.
- Comments explain why a constraint exists, not what the code already says.
- Branch from `main`, open a pull request, and keep CI green.
- Do not edit unrelated user changes in a dirty worktree.

## Pull requests

- Open a pull request only when the developer asks for one.
- Fill in every heading of `.github/PULL_REQUEST_TEMPLATE.md`, including the
  schema and privacy checkboxes. Do not replace it with your own layout.
- Verification lists the focused commands or manual checks you ran and what
  they showed. "Tests pass" alone is not evidence.
- Upload screenshots and recordings with the pull request
  (`gh pr edit <n> --body-file <file> --attach <image>`). Never commit PR-only
  assets.
- End the description with the model and harness that wrote the change.
- `bun run scripts/pr-policy.ts` runs the same policy checks as CI: committed
  migrations unchanged, docs updated alongside rate and route-manifest
  changes, and a pattern scan of fixtures for real-looking home paths, emails,
  and credentials. Passing the scan does not prove a fixture is synthetic.
- When babysitting a pull request, wait for check and review events instead of
  polling. Check each bot finding against the source, fix the real ones, and
  answer false positives with a reason.

## Documentation expectations

Keep the public repository useful to users and outside contributors. Prefer
current behavior and durable constraints over migration history, private
runbooks, project-specific agent setup, or stale release notes. The README is
the product entry point, and detailed operational behavior belongs in `docs/`.
The skills in `.claude/skills/` are the one exception to the agent-setup rule:
each stays a thin pointer to the doc that owns its procedure, so update the doc
first and the skill only when a path or rule it names changes.

When changing:

- metrics or classification, update `docs/analytics-methodology.md`.
- archive state, sync, or migration behavior, update
  `docs/data-lifecycle.md`.
- a route, update `docs/api/openapi.yaml`, `docs/api/routes.md`, and contract
  tests.
- install or packaging behavior, update `docs/distribution.md` and the npm
  package README.
- model rates, update `docs/pricing.md` with dated first-party sources.

## When stuck

If a test fails in a way you cannot resolve, the plan appears wrong, or a
change would alter schema or route semantics beyond the request, stop and
report the exact failure before guessing.