Files-first: run Metatron with no server at all

Two kinds of teams

Since the OKF mirror shipped, I've watched teams split cleanly into two camps. One camp is happy with the default setup: decisions live in a local database, agents query them over MCP, retrieval is ranked and feedback-tuned, and curation happens in the CLI or the web UI. The other camp keeps asking a sharper version of the question that produced the mirror in the first place: if the files are readable, reviewable, and portable — why isn't the repo the source of truth?

For that camp, a mirror isn't enough. A mirror means the database is still the boss and the files are a projection. They want the opposite: conventions curated the way everything else in their engineering culture is curated — as text, in git, through pull requests — with no extra server in the loop. Files-first mode is exactly that, and it's a first-class way to run Metatron, not a downgrade.

The inversion

In files-first mode the roles flip. The git-tracked bundle under context/ is authoritative: the directory is the status — proposals live in context/candidate/, canonical conventions in context/decisions/ — and the database becomes a derived, rebuildable serving index you can regenerate at any time with metatron mirror import. Delete it and nothing is lost; the truth is in your repo's history.

The invariant Metatron is built around survives the inversion untouched: nothing becomes canonical without a human. Here the curation act is the most git-native gesture there is:

git mv context/candidate/use-repo-pattern.md context/decisions/
git commit && gh pr create     # reviewed and merged like any other change

Approving that pull request is the promotion. It's recorded as a commit, attributable with git blame, revertible with git revert. No agent, no score, no CI job can cross that line on its own.

One command, no API key

Onboarding a repo is a single command from any installed Metatron:

metatron context setup

It's additive and idempotent, and it installs three things: a consult-first rule the agent sees every turn, the context/ scaffold, and — the part I like most — two skills in .roo/skills/. The context-okf-llm-ingest skill teaches whatever LLM your organization already uses to extract your codebase's real decisions and write them as candidate files. No Anthropic key, no metatron ingest run — the skill is the extractor, and every output lands in candidate/ awaiting your review. Its companion, context-okf-promote-candidates, handles the mechanical side of promotion while refusing, by design, to decide what deserves promoting.

The onboarding directive itself goes into AGENTS.md — the tool-agnostic convention — appended to whatever you already have there, never overwriting it.

We dogfooded it — and it bit us, usefully

It would be embarrassing to ship a files-first mode without running Metatron on Metatron. So the repo now carries its own context/ knowledge base, onboarded by its own setup command.

The dogfooding paid for itself within the hour. The first real import run created eleven decisions from ten files. The eleventh was index.md — a generated directory listing that one subsystem writes into decisions/ and another subsystem, the importer, happily swallowed as a decision. An empty one. At canonical status. With no human involved. The exact invariant this whole product preaches, violated by our own tooling on machine-generated noise.

The fix shipped before the feature announcement did: the importer now skips generated artifacts and refuses to create a decision from any file that doesn't explicitly declare itself an OKF concept. A stray note dropped into decisions/ gets a warning, not a promotion. That's the kind of bug you only find by being your own first user — and the kind of guarantee you want tested before your conventions ride on it.

Why the directory is called context/

Dogfooding also forced a naming reckoning. The bundle used to live under metatron/ — which collided head-on with our own Python package of the same name, and put a product name where a neutral term belongs. Your conventions aren't "Metatron files"; they're your repository's context. So the default is now context/, which also matches the framing of the Repository Context Layer — the proposed standard for git-native, agent-maintained project context (the manifesto makes the full argument) — of which Metatron is a reference implementation.

And because a name that collides once will collide again: it's configurable. Set context_dir in metatron.toml, export METATRON_CONTEXT_DIR, or pass --dir at setup. Repos onboarded before the rename keep working — a legacy metatron/ bundle is recognized automatically.

Which mode is for you?

Both are first-class, and they share the same records, the same OKF format, and the same human-gated boundary. Run MCP mode when you want ranked retrieval, the feedback loop tuning what gets served first, and a curation UI. Run files-first when you want zero servers, PR-native curation, and any LLM as the extractor. You can even move between them — mirror sync and mirror import are the bridge in each direction.

---

Files-first mode is live. Install Metatron, run metatron context setup in a repo, and let your agent propose its first candidates — the docs have the full reference. Your conventions, in your repo, promoted by your review. The way it should have worked all along.