fix: scope Context7 index to developer-facing folders and disambiguate spartan naming

[AztecBot]

Problem

An external developer's LLM agent, migrating to v5, latched onto "spartan" and treated it as a release channel — something to install or migrate to. Alex tasked Codex with investigating why, and it traced a contamination path through the AI context we ourselves recommend. The published docs are clean; the context they point agents at is not scoped.

The concrete findings, each verified against this repo:

• context7.json had no folder restrictions — just a url and public_key. The Context7 Aztec index therefore covers the entire monorepo: ~1.95M tokens, ~23k snippets. A topic=spartan query returns deployment infrastructure prominently.
• spartan/ is pure infrastructure — 272 YAML/Terraform/shell files, and spartan/README.md opens with "The Spartan Kubernetes cluster is used to run Aztec's public-facing node infrastructure." None of it is relevant to building on Aztec, but it is all snippet fuel for the index.
• docs/docs-developers/ai_tooling.md described Context7 as having "Aztec docs" — which was not what the index actually contained, so we were pointing developers at the whole monorepo while telling them it was docs.
• CLAUDE.md teaches agents merge-train/spartan and merge-train/spartan-v5 without ever saying what spartan is not. An agent cloning the repo for v5 work reads "spartan-v5" next to "v5 release line" and the conflation is an easy step to take.

Changes

context7.json — scope the index to developer-facing surfaces via folders, which is what actually cuts the 1.95M-token surface down:

• docs/docs, docs/docs-developers, noir-projects/aztec-nr, yarn-project/aztec.js, boxes

excludeFolders additionally names the infrastructure directories explicitly. With the allow-list in place this is belt-and-braces, but it records the intent durably so a later widening of folders doesn't silently pull spartan/ back in — that being the specific thing Alex asked to have "entirely ignored". Drop it if you'd rather not carry redundant config.

Three rules are added. The first directly counteracts the observed failure — it tells agents that spartan, merge-train/*, next, and v5-next are internal repo/infrastructure names and must never be handed to a user as something to install or migrate to. The other two mirror the failure modes ai_tooling.md already calls out (version compatibility, aztec CLI over bare nargo/bb).

CLAUDE.md — one sentence after the merge-train table saying what spartan is and, more importantly, what it isn't. The branch table itself is needed by internal contributors and is unchanged. (AGENTS.md is a symlink to CLAUDE.md, so Codex picks this up too.)

docs/docs-developers/ai_tooling.md — the Context7 bullet now describes what the index actually contains and says the infrastructure is deliberately excluded, instead of claiming "Aztec docs".

Trade-offs and review questions

I'm not the owner here and Alex flagged that docs ownership is unclear, so the judgment calls are worth a look:

1. docs/docs-operate is not in the allow-list. It is curated, published operator documentation, so it's a much milder problem than raw Helm charts — but it is infrastructure-flavoured, and ai_tooling.md points app developers at Context7. I left it out to keep the index focused on the app-developer audience. Reasonable to add back if operators are meant to be served by this index.
2. Versioned docs (docs/developer_versioned_docs, 3.9M) are excluded by virtue of not being listed. That's deliberate — indexing several old versions alongside current ones invites exactly the version-confusion class of bug this PR is about — but it does mean Context7 won't serve older-version answers.
3. The allow-list is the aggressive half of this change. A deny-list alone would remove spartan/ but leave the whole of yarn-project/ and barretenberg/ indexed, which is still enormous and still not "docs". I went with the allow-list because it makes the ai_tooling.md description true; tell me if that's too sharp a cut.

Verification

context7.json validates against the published schema — every field used (folders, excludeFolders, rules, projectTitle, description, $schema) is real, and description (124 chars) and projectTitle are within their length bounds. Field semantics were confirmed against the schema rather than assumed.

Note that the index only shrinks once Context7 re-parses the repo — merging this does not retroactively clean the existing index. Worth confirming the re-index lands, and re-running the topic=spartan query above afterwards to check the infrastructure content is actually gone.

This addresses the contamination path but can't prove the original agent's behaviour is fixed; Codex's own conclusion was an inference ("likely conflated repository/merge-train terminology with a release channel"), and there was no evidence of "latest spartan" coming from beta documentation content. So this closes the plausible route rather than a confirmed one.

---

Created by claudebox · group: slackbot · Slack thread