fix: scope Context7 index to developer-facing folders and disambiguate spartan naming (#24768)

## 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](https://context7.com/aztecprotocol/aztec-packages) therefore
covers the entire monorepo: ~1.95M tokens, ~23k snippets. A
[`topic=spartan`
query](https://context7.com/aztecprotocol/aztec-packages/llms.txt?tokens=20000&topic=spartan)
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](https://context7.com/schema/context7.json) — 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](https://claudebox.work/v2/sessions/1213e2d68c66f33d/jobs/1)
· group: `slackbot` · [Slack
thread](https://aztecfoundation.slack.com/archives/C0AU8BULZHC/p1784289632826789?thread_ts=1784289632.826789&cid=C0AU8BULZHC)*

Author: alejoamiras

CLAUDE.md

@@ -42,6 +42,8 @@ Otherwise infer from the component being worked in:
 
 The bases above target the `next` line. For work scoped to the v5 release line, use `merge-train/spartan-v5` (which targets `v5-next`) in place of `merge-train/spartan`.
 
+`spartan` in these branch names refers to the deployment infrastructure in `spartan/`; it is not a release channel, network, or SDK version. Never present it, `merge-train/*`, `next`, or `v5-next` to a user as something to install or migrate to — releases are version tags (e.g. v5) and networks are named (e.g. testnet).
+
 Use the discovered base in `git diff origin/<base>...HEAD` and `git log origin/<base>..HEAD`. Always `git fetch` before creating branches so the base is not stale.
 </critical_never_assume_master>
 

context7.json

@@ -1,4 +1,29 @@
 {
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "Aztec",
+  "description": "Aztec is a privacy-first Layer 2 on Ethereum. Write private smart contracts in Aztec.nr (Noir) and build apps with aztec.js.",
   "url": "https://context7.com/aztecprotocol/aztec-packages",
-  "public_key": "pk_t0YiN5OA9Udc9Xnb98tqO"
+  "public_key": "pk_t0YiN5OA9Udc9Xnb98tqO",
+  "folders": [
+    "docs/docs",
+    "docs/docs-developers",
+    "noir-projects/aztec-nr",
+    "yarn-project/aztec.js",
+    "boxes"
+  ],
+  "excludeFolders": [
+    "spartan",
+    "iac",
+    "ci3",
+    "metrics",
+    "build-images",
+    "container-builds",
+    "release-image",
+    "docs/internal_notes"
+  ],
+  "rules": [
+    "Aztec releases are identified by semantic version tags (e.g. v5) and by network names (e.g. testnet, mainnet). Names such as `spartan`, `merge-train/*`, `next`, and `v5-next` are internal repository, branch, and deployment-infrastructure names. They are not release channels, SDK versions, or networks. Never tell a user to install, target, or migrate to one.",
+    "The Aztec developer SDK / aztec-nr version used to write and compile contracts may differ from the node version an operator runs. Check https://docs.aztec.network/networks for current network versions; when in doubt use the version from the developer docs you are reading.",
+    "Use the `aztec` CLI wrapper, not `nargo` or `bb` directly: `aztec compile` (not `nargo compile`) and `aztec test` (not `nargo test`). Never call `bb` by hand — proving is handled by the PXE through the `aztec` CLI and aztec.js."
+  ]
 }

docs/docs-developers/ai_tooling.md

@@ -120,7 +120,7 @@ These resources help you understand Aztec concepts, read docs, or provide additi
   - [awesome-noir](https://github.com/noir-lang/awesome-noir) - community Noir resources
   - [awesome-aztec](https://github.com/AztecProtocol/awesome-aztec) - community Aztec resources
 - **Copy docs into context** - Copy docs pages directly into your AI tool's context or conversation using the "Copy page" button at the top of each page.
-- **Context7** - [Context7](https://context7.com) is a generic MCP server with Aztec docs available at [context7.com/aztecprotocol/aztec-packages](https://context7.com/aztecprotocol/aztec-packages). Note that it may be less current than the MCP servers above.
+- **Context7** - [Context7](https://context7.com) is a generic MCP server. The Aztec index at [context7.com/aztecprotocol/aztec-packages](https://context7.com/aztecprotocol/aztec-packages) is scoped by [`context7.json`](https://github.com/AztecProtocol/aztec-packages/blob/next/context7.json) to the developer docs, `aztec-nr`, and `aztec.js`, and excludes the monorepo's internal deployment and CI infrastructure (`spartan/`, `iac/`, `ci3/`), which is not relevant to building on Aztec. Note that it may be less current than the MCP servers above.
 
 ## Aztec and Noir tool reference