feat(docs): fork a v6 docs line and serve it in previews

docs/.gitignore

@@ -38,3 +38,4 @@ static/aztec-nr-api/next
 
 # aztec-node checkout and binaries pinned by aztec-node.json (scripts/aztec_node.mts)
 /.aztec-node
+/lines/*/.aztec-node

docs/bootstrap.sh

@@ -9,7 +9,7 @@ repo_root=$(git rev-parse --show-toplevel)
 hash=$(
   cache_content_hash \
     .rebuild_patterns \
-    $(find docs docs-developers docs-operate docs-participate developer_versioned_docs network_versioned_docs -type f -name "*.md*" -exec grep '^#include_code' {} \; | \
+    $(find docs docs-developers docs-operate docs-participate developer_versioned_docs network_versioned_docs $([ -d lines ] && echo lines) -type f -name "*.md*" -exec grep '^#include_code' {} \; | \
       awk '{ gsub("^/", "", $3); if ($3 !~ /^labs\//) print "^" $3 }' | sort -u)
 )
 # A release build renders its own versions and links this repository's files at DOCS_COMMIT, so it
@@ -20,10 +20,15 @@ hash=$(hash_str "$hash" "$(git -C "$repo_root" rev-parse HEAD:docs)" \
 
 # Every function that reads aztec-node code fetches and checks the pinned checkout first, on a cache
 # hit too, since later steps read it (scripts/aztec_node.mts; a no-op without network when current).
+# The fetch covers every dev line (docs/lines/<line>/), each with its own pin.
 function fetch_aztec_node {
   node scripts/aztec_node.mts fetch
 }
 
+function lines {
+  node scripts/aztec_node.mts lines
+}
+
 function build_docs {
   if [ "${CI:-0}" -eq 1 ] && [ $(arch) == arm64 ]; then
     echo "Not building docs for arm64 in CI."
@@ -48,6 +53,9 @@ function check_generated_refs {
   echo_header "check generated aztec.js reference"
   fetch_aztec_node
   ./scripts/aztecjs_reference_generation/update_docs.sh --check
+  for line in $(lines); do
+    ./scripts/aztecjs_reference_generation/update_docs.sh --line "$line" --check
+  done
 }
 
 function test_cmds {
@@ -137,16 +145,28 @@ function check {
   ./scripts/check_warnings.sh --self-test
   ./scripts/check_cli_defaults.sh
   ./scripts/check_doc_references.sh docs
+  for line in $(lines); do
+    ./scripts/check_doc_references.sh "docs/lines/$line"
+  done
 }
 
 function build_examples {
   echo_header "Building examples"
   (cd examples && ./bootstrap.sh "$@")
 }
 
+# A dev line's examples compile and type-check here; they run against a network only at the line's cut.
+function build_line_examples {
+  for line in $(lines); do
+    echo_header "Building $line examples"
+    (cd examples && ./bootstrap.sh --line "$line")
+  done
+}
+
 case "$cmd" in
   "ci")
     build_examples
+    build_line_examples
     build_docs
     check_generated_refs
     test
@@ -155,6 +175,7 @@ case "$cmd" in
     ;;
   "")
     build_examples
+    build_line_examples
     build_docs
     check_generated_refs
     check_orphaned_urls

docs/docs-developers/docs/aztec-nr/api.mdx

@@ -6,13 +6,19 @@ aztec_nr_api_version: next
 ---
 
 import Link from "@docusaurus/Link";
-import { useActiveVersion } from "@docusaurus/plugin-content-docs/client";
+import { useActivePluginAndVersion } from "@docusaurus/plugin-content-docs/client";
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import { aztecNrApiFolder } from "@site/src/utils/aztecNrApi.mjs";
 
 export const useApiVersion = () => {
   const { siteConfig } = useDocusaurusContext();
-  return aztecNrApiFolder(useActiveVersion("developer"), siteConfig.customFields.aztecNrApiFolders);
+  const { activePlugin, activeVersion } = useActivePluginAndVersion() ?? {};
+  return aztecNrApiFolder(
+    activeVersion,
+    siteConfig.customFields.aztecNrApiFolders,
+    activePlugin?.pluginId,
+    siteConfig.customFields.lineApiFolders,
+  );
 };
 
 export const ModuleLink = ({ path, children }) => {

docs/docusaurus.config.js

@@ -22,9 +22,12 @@ const {
   aztecNrApiFolders,
   docsInstances,
   historicalVersions,
+  lineApiFolders,
+  lineInstances,
   llmsRoutes,
   syncVersionsFile,
 } = require("./src/network_docs.js");
+const { lineNames } = require("./src/preprocess/line.js");
 const { versionLabel } = require("./src/release_names");
 
 // Version config files are the source of truth for type→version mappings.
@@ -42,6 +45,8 @@ const [developerDocs, operatorDocs] = docsInstances(
   process.env.CONTEXT === "production"
 );
 const developerApiFolders = aztecNrApiFolders(developerDocs);
+// The dev lines (docs/lines/<line>/) serve in previews only, each beside the dev docs.
+const lines = lineInstances(lineNames(path.join(__dirname, "..")), process.env.CONTEXT === "production");
 
 const NETWORK_LABELS = { mainnet: "Alpha", testnet: "Testnet" };
 // Docs versions track release lines, so each label carries the line name and
@@ -374,6 +379,20 @@ const config = {
         rehypePlugins,
       },
     ],
+    ...lines.map(({ line, id, source, routeBasePath, sidebar }) => [
+      "@docusaurus/plugin-content-docs",
+      {
+        id,
+        path: `processed-docs/${source}`,
+        routeBasePath,
+        sidebarPath: `./${sidebar}`,
+        editUrl: (params) =>
+          `https://github.com/AztecProtocol/aztec-packages/edit/next/docs/${source}/` + params.docPath,
+        versions: { current: { label: `${line} dev`, noIndex: true, banner: "unreleased" } },
+        remarkPlugins,
+        rehypePlugins,
+      },
+    ]),
     // Participate docs instance - NOT versioned (educational content)
     [
       "@docusaurus/plugin-content-docs",
@@ -456,6 +475,7 @@ const config = {
             "/aztec-nr-api/**",
             "/typescript-api/**",
             ...llmsInstances.flatMap((l) => l.excludeRoutes),
+            ...lines.flatMap(({ routeBasePath }) => [`/${routeBasePath}`, `/${routeBasePath}/**`]),
           ],
         },
       },
@@ -484,6 +504,7 @@ const config = {
     websiteId: WEBSITE_ID,
     // Read by the Aztec.nr API page (src/utils/aztecNrApi.mjs); labels carry names, not networks.
     aztecNrApiFolders: developerApiFolders,
+    lineApiFolders: lineApiFolders(developerVersionConfig, [...new Set(lines.map(({ line }) => line))]),
   },
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */

docs/lines/v6/Nargo.toml

@@ -0,0 +1,16 @@
+[workspace]
+members = [
+    "examples/circuits/hello_circuit",
+    "examples/contracts/counter_contract",
+    "examples/contracts/counter_contract_test",
+    "examples/contracts/bob_token_contract",
+    "examples/contracts/nft",
+    "examples/contracts/nft_bridge",
+    "examples/contracts/recursive_verification_contract",
+    "examples/contracts/example_uniswap",
+    "examples/webapp-tutorial/contracts",
+    "examples/contracts/aave_bridge",
+    "examples/contracts/logging_example",
+    "examples/contracts/logging_example_test",
+    "examples/contracts/packing_example"
+]

docs/lines/v6/aztec-node.json

@@ -0,0 +1,17 @@
+{
+  "repository": "https://github.com/aztec-labs-eng/aztec-node",
+  "ref": "v6.1.0-nightly.20261029",
+  "commit": "a6ca030427db42b5187ce983a92621c38b4380c0",
+  "toolchain": {
+    "aztec": "6.1.0-nightly.20261029",
+    "bb": "6.0.0-rc.7",
+    "noir": "1.0.0-rc.3",
+    "l1Artifacts": "6.0.0-rc.7"
+  },
+  "noirArchives": {
+    "x86_64-unknown-linux-gnu": "sha256:5792dd962afce1eed834570f95d9f72cc4a09d45cd846d3b80b7a57392732973",
+    "x86_64-apple-darwin": "sha256:9014ea4b7e88ab2441a949454f2b3dbc2920a82a9353a7a3649a444afed78910",
+    "aarch64-unknown-linux-gnu": "sha256:98be47cd6b2a81f3857c029acd8298fd590eebeb153ef51e1dc6f10c973e00e9",
+    "aarch64-apple-darwin": "sha256:44157443519c8ede9a2df7e6a4ee513b3d49ef9fdd5774c43311fe6f32887a59"
+  }
+}

docs/lines/v6/docs-developers/ai_tooling.md

@@ -0,0 +1,135 @@
+---
+title: AI Tooling
+description: Set up AI coding tools like Claude Code, Cursor, and Codex for Aztec and Noir development.
+sidebar_position: 2
+tags: [ai, tooling, getting_started]
+references: ["context7.json"]
+---
+
+Aztec is new, rapidly evolving, and spans novel concepts like private state, notes, and nullifiers. AI coding tools can accelerate your learning and development, but they need up-to-date context to be useful. This page shows you how to set that up.
+
+:::caution
+LLMs have limited training data for zero-knowledge circuit development. Noir and Aztec.nr are newer languages with smaller codebases than mainstream languages, so AI tools will make more mistakes than you might be used to. The tools on this page help by providing up-to-date context, but you should always verify generated code and test thoroughly.
+:::
+
+## Project-level instructions (CLAUDE.md / AGENTS.md files)
+
+MCP servers and skills provide context on demand, but AI tools don't always invoke them at the right time. The most reliable way to prevent common mistakes is to add **project-level instruction files** that your AI tool reads automatically at the start of every conversation. You can add to these files over time as you discover new gotchas or best practices. They ensure your AI tool always has the critical context it needs, without relying on you to remember to invoke the right skills or MCP servers.
+
+For Claude Code, create a `CLAUDE.md` file in your project root. For Codex, create an `AGENTS.md` file in your project root. For other tools, check their documentation for equivalent configuration.
+
+### Recommended CLAUDE.md / AGENTS.md
+
+```markdown
+# Aztec Project
+
+## Critical: Use the `aztec` CLI, not `nargo` or `bb` directly
+
+This is an Aztec smart contract project. Always use the `aztec` CLI wrapper instead of calling `nargo` or `bb` (the Barretenberg prover) directly:
+
+- **Compile**: `aztec compile` (NOT `nargo compile`). Using `nargo compile` alone produces incomplete artifacts.
+- **Test**: `aztec test` (NOT `nargo test`).
+- **Prove**: NEVER call `bb` directly. Proof generation is handled for you by the PXE through the `aztec` CLI and `aztec.js`. There is no contract-development workflow that runs `bb` by hand.
+- **Other nargo commands** like `aztec-nargo fmt` and `aztec-nargo doc` are fine to use directly. The Aztec installer exposes the bundled `nargo` as `aztec-nargo`; bare `nargo` resolves to your own install (if any), not the bundled one.
+
+## Error Handling
+
+- NEVER silently swallow errors or fall back to default values. If a value is required, throw if it's missing.
+- NEVER use fallback values like `AztecAddress.ZERO`, `"unknown"`, `0`, or `null` to mask missing data. These hide bugs and cause failures elsewhere that are harder to trace.
+- NEVER add retry/polling logic unless explicitly asked. Retry loops with long timeouts may brick application loops and mask the real error.
+- NEVER wrap calls in try/catch that returns null or a default. Let errors propagate.
+- If a precondition isn't met, throw immediately with a descriptive message — don't try to "work around" it.
+- Prefer `T` return types over `T | null` when null would indicate a bug rather than a valid state.
+- Do not add `.catch(() => defaultValue)` to promises. If something fails, the caller needs to know.
+
+## Version Compatibility
+
+The Aztec developer SDK/aztec-nr version (used for writing and compiling contracts) may differ from the node version (used by operators to run the network). Check the [Networks page](https://docs.aztec.network/networks) for current network versions. When in doubt, use the version from the developer docs you are reading, it is the correct SDK version for contract development on that network.
+
+## Hashing: Default to Poseidon2
+
+When writing Aztec.nr contract code that requires hashing, **always use Poseidon2** unless a specific protocol or interoperability requirement calls for a different hash.
+
+- **Default**: `use aztec::protocol::hash::poseidon2_hash;`
+- **Do NOT** default to Pedersen (`pedersen_hash`). Pedersen is available but Poseidon2 is cheaper in circuits and is the standard across Aztec.
+- If you are unsure which hash to use, use Poseidon2.
+```
+
+This prevents the two most common AI mistakes: using `nargo compile`/`nargo test` instead of their Aztec wrappers, and defaulting to Pedersen hashes instead of Poseidon2.
+
+### Why this matters
+
+LLMs have extensive training data for `nargo` (the standalone Noir compiler) and `bb` (the Barretenberg prover CLI) but limited exposure to the `aztec` CLI wrapper. Without explicit instructions, they default to `nargo compile` (which produces artifacts missing the AVM transpilation step) or reach for `bb` to generate proofs. In an Aztec project, compilation and proving both go through the `aztec` tooling.
+
+## MCP servers
+
+The highest-leverage tools are the Aztec and Noir MCP servers. They clone reference repositories locally and give your AI tool code search, documentation search, and example discovery across the Aztec and Noir ecosystems. They work with any AI coding tool that supports MCP (Claude Code, Cursor, Windsurf, Codex, and others).
+
+The MCP servers help manage the problem of focusing LLMs on the correct Aztec versions for your project. Aztec is under active development and there may be multiple versions in use at any given time (e.g. mainnet, devnet and testnet may be on different versions). They make it easy to switch between versions if needed, and to keep your context up to date as the repos evolve.
+
+Start here if you're unsure what to set up.
+
+### Claude Code
+
+Add the MCP servers directly:
+
+```bash
+claude mcp add aztec -- npx @aztec/mcp-server@latest
+claude mcp add noir -- npx noir-mcp-server@latest
+```
+
+### Cursor / Windsurf / other MCP clients
+
+Add the servers to your MCP configuration JSON:
+
+```json
+{
+  "mcpServers": {
+    "aztec": {
+      "command": "npx",
+      "args": ["-y", "@aztec/mcp-server@latest"]
+    },
+    "noir": {
+      "command": "npx",
+      "args": ["-y", "noir-mcp-server@latest"]
+    }
+  }
+}
+```
+
+### OpenAI Codex
+
+Use the same MCP configuration format, pointing at `@aztec/mcp-server` and `noir-mcp-server`.
+
+## For learning and exploration
+
+These resources help you understand Aztec concepts, read docs, or provide additional context to your AI tool.
+
+- **API reference docs** - The docs site publishes auto-generated API references that are useful to feed to AI tools:
+  - [Aztec.nr API reference](./docs/aztec-nr/api.mdx) - generated from aztec-nr source with `nargo doc`
+  - [TypeScript API reference](./docs/aztec-js/typescript_api_reference.mdx) - generated from yarn-project packages with TypeDoc
+
+  These are especially useful as context for code generation since they reflect the current API surface. Agents can read both as markdown: the [Aztec.nr index](https://docs.aztec.network/aztec-nr-api/mainnet/llms.txt) links a page per module and item, and the [TypeScript index](https://docs.aztec.network/typescript-api/mainnet/llms.txt) a page per exported name.
+
+- **llms.txt** - The docs site publishes [llms.txt](https://docs.aztec.network/llms.txt), a navigational index of every page following the [llmstxt.org](https://llmstxt.org) standard, and [llms-full.txt](https://docs.aztec.network/llms-full.txt), the complete documentation in a single file. Many AI tools can consume these files directly to index documentation.
+- **Markdown for any page** - Append `.md` to any page URL (for example `https://docs.aztec.network/developers/overview.md`), or request the normal URL with an `Accept: text/markdown` header, to get the page as clean markdown instead of HTML. This is the best format to hand to an agent.
+- **Reference repositories** - Point your AI tool at these repos for additional context:
+  - [AztecProtocol/aztec-packages](https://github.com/AztecProtocol/aztec-packages) - main monorepo, best general reference
+  - [AztecProtocol/aztec-starter](https://github.com/AztecProtocol/aztec-starter) - smaller starter project, easier for onboarding
+  - [AztecProtocol/aztec-examples](https://github.com/AztecProtocol/aztec-examples) - official contract examples
+  - [noir-lang/noir](https://github.com/noir-lang/noir) - Noir language source of truth
+  - [noir-lang/noir-examples](https://github.com/noir-lang/noir-examples) - common Noir patterns
+  - [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** - The "Copy page" button at the top of each page copies the page as markdown. Its menu also opens the page in ChatGPT or Claude so you can ask questions about it, and links to the markdown version of the page.
+- **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 and operator docs of the version the networks run, and excludes the repository's build and CI infrastructure. Note that it may be less current than the MCP servers above.
+
+## Aztec and Noir tool reference
+
+| Tool                                                                        | Works with                                            | Description                                                                         |
+| --------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| [@aztec/mcp-server](https://github.com/AztecProtocol/mcp-server)            | Any MCP client (Claude Code, Cursor, Windsurf, Codex) | Clones Aztec repos locally, provides code search, doc search, and example discovery |
+| [noir-claude-plugin](https://github.com/critesjosh/noir-claude-plugin)      | Claude Code                                           | Skills and commands for Noir circuit development                                    |
+| [noir-mcp-server](https://github.com/critesjosh/noir-mcp-server)            | Any MCP client                                        | Clones Noir repos, stdlib, and community libraries; provides search and examples    |
+| [aztec-skills](https://github.com/NethermindEth/aztec-skills)               | Claude Code, Codex                                    | Installable skills for Aztec contracts, deployment, Aztec.js, and testing           |
+| [noir skills](https://github.com/noir-lang/noir/tree/master/.claude/skills) | Claude Code, Codex                                    | Skills for Noir compiler development, SSA debugging, fuzzing, and ACIR optimization |

docs/lines/v6/docs-developers/docs/aztec-js/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Aztec.js",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true
+}