accreta: Instructions file for Claude Code

CLAUDE.md — accreta

You are working on accreta: a knowledge base that an AI agent writes and maintains, with provenance back to the sources and drift detection when those sources change.

This file is the operating manual for working on accreta itself. It is not the constitution that accreta generates for its users — that lives in templates/constitution/ and is a product artifact.

---

1. What this project is

Most systems that give an agent knowledge of a large corpus use RAG: embed everything, retrieve chunks per query, rebuild context every time. accreta takes the other path, from Karpathy's LLM wiki pattern: the agent compiles knowledge into interlinked markdown once and then keeps it current.

Three properties follow, and they are the whole point:

1. Provenance — every non-trivial claim cites source, path, line range, revision.
2. Drift detection — each page records the revision it was verified against, so when a source moves the system names the pages now in doubt.
3. Refusal to over-synthesize — when sources disagree, record the contradiction; never silently pick a winner.

Anything that erodes one of these three is a regression, even when it makes the tool more convenient.

2. Origin, and what it means for the code

accreta is extracted from a system that documented a 17-repository backend and runs in production. Much of the code arrives already proven. Two consequences:

• Comments that explain a failure are load-bearing. The original carries remarks like "a read-only connection cannot create the -shm file a WAL database needs". Each encodes an incident. Port them; do not tidy them away.
• Generalizing is the work. The original assumed git repositories and code-shaped page types. Removing those assumptions without losing the mechanics is the actual task. When in doubt, keep the mechanism and lift the assumption.

3. Architecture