fix(docs): link tutorial examples in this repository at each line's commit

docs/CLAUDE.md

@@ -113,6 +113,7 @@ The preprocessing system uses these environment variables:
 **Foundation macro:**
 
 - `#include_foundation_version` - `v<installed @aztec-foundation/l1-artifacts version>`; use it for links and Nargo dependencies into aztec-packages' own code (`l1-contracts/`, `barretenberg/`). `#include_foundation_version_without_prefix` drops the `v` (npm versions)
+- `#docs_commit` - the commit the page's `docs/examples/` snippet links name (`DOCS_COMMIT`, else `HEAD`); use it for hand-written links into and clones of the examples, with the page's own line's path (`docs/lines/v6/examples/` on a v6 page). aztec-node has no `docs/` since its #619, so never link the examples there
 
 **Legacy macros:**
 

docs/README.md

@@ -477,6 +477,10 @@ import { AztecPackagesVersion } from "@site/src/components/Version";
 
 This macro will be replaced inline with `v<version>` of the installed `@aztec-foundation/l1-artifacts`, which `scripts/aztec_node.mts check` holds equal to the pinned aztec-node's `BB_VERSION`. Use it for links and Nargo `git` dependencies into this repository's own code, such as `l1-contracts/` and `barretenberg/`, in every build: it names the release the docs build against, which is also the tag that published Solidity snippets link to. `#include_foundation_version_without_prefix` renders the same version without the `v`, as npm wants it.
 
+### `#docs_commit`
+
+This macro will be replaced inline with the commit that `#include_code` snippets from this repository's files link to: `DOCS_COMMIT`, else `HEAD`. Use it for hand-written links into, and clones of, the docs examples (`docs/examples/`, or a line's `docs/lines/<line>/examples/`): `https://github.com/AztecProtocol/aztec-packages/blob/#docs_commit/docs/examples/...`. A line page names its own line's path. Like those snippets, it fails a build whose `RELEASE_TYPE` is set to anything but `nightly` without `DOCS_COMMIT`.
+
 ### `#include_testnet_version`
 
 This macro will be replaced inline with the provided testnet version. This value is sourced from the `TESTNET_TAG` environment variable when running `yarn build` (e.g. `TESTNET_TAG=0.87.5 yarn build`).

docs/developer_versioned_docs/version-v6.0.0/support.md

@@ -80,7 +80,7 @@ If something in the docs is wrong, outdated, or missing, please **[open an issue
 
 This includes typos and small text issues: please file them as issues rather than opening single-line PRs. A maintainer can fix several at once, which is faster to review than a stream of one-line pull requests.
 
-For larger restructures or new pages, open an issue first so a maintainer can confirm the direction before you write the change. Every docs page in this site has an "Edit this page" link at the bottom that takes you to the right file in [`docs-developers/`](https://github.com/aztec-labs-eng/aztec-node/tree/next/docs/docs-developers) once the direction is agreed.
+For larger restructures or new pages, open an issue first so a maintainer can confirm the direction before you write the change. Every docs page in this site has an "Edit this page" link at the bottom that takes you to the right file in [`docs-developers/`](https://github.com/AztecProtocol/aztec-packages/tree/next/docs/docs-developers) once the direction is agreed.
 
 ## Operator and node issues
 

docs/docs-developers/docs/aztec-nr/framework-description/ethereum_aztec_messaging.md

@@ -91,7 +91,7 @@ const witness = await aztecNode.getL2ToL1MembershipWitness(
 
 ## Example implementations
 
-- [Token Portal (L1)](https://github.com/aztec-labs-eng/aztec-node/blob/#include_aztec_version/docs/examples/solidity/example_swap/ExampleTokenPortal.sol)
+- [Token Portal (L1)](https://github.com/AztecProtocol/aztec-packages/blob/#docs_commit/docs/examples/solidity/example_swap/ExampleTokenPortal.sol)
 - [Token Bridge (L2)](https://github.com/aztec-labs-eng/aztec-node/blob/#include_aztec_version/noir-projects/noir-contracts/contracts/app/token_bridge_contract/src/main.nr)
 
 ## Next steps

docs/docs-developers/docs/aztec-nr/index.md

@@ -60,7 +60,7 @@ and import dependencies from the Aztec.nr library.
 
 :::info
 
-You can see a complete example of a simple counter contract written with Aztec.nr [here](https://github.com/aztec-labs-eng/aztec-node/blob/#include_aztec_version/docs/examples/contracts/counter_contract/src/main.nr).
+You can see a complete example of a simple counter contract written with Aztec.nr [here](https://github.com/AztecProtocol/aztec-packages/blob/#docs_commit/docs/examples/contracts/counter_contract/src/main.nr).
 
 :::
 

docs/docs-developers/docs/tutorials/contract_tutorials/recursive_verification.md

@@ -13,7 +13,7 @@ This is called "recursive" verification because the proof is verified inside an
 :::
 
 :::tip Full Working Example
-The complete code for this tutorial is available in the [docs/examples](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples) directory. Clone it to follow along or use it as a reference.
+The complete code for this tutorial is in [`docs/examples/`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples): the circuit in [`circuits/hello_circuit`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/circuits/hello_circuit), the contract in [`contracts/recursive_verification_contract`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/contracts/recursive_verification_contract) and the scripts in [`ts/recursive_verification`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/ts/recursive_verification). Use it as a reference while you follow along.
 :::
 
 ## Prerequisites
@@ -675,7 +675,7 @@ The counter starts at 10 (set during deployment), and after successful proof ver
 
 ## Quick Reference
 
-If you want to run all commands at once, or if you're starting fresh, here's the complete workflow. You can also reference the [full working example](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples) in the main repository.
+If you want to run all commands at once, or if you're starting fresh, here's the complete workflow. You can also reference the [full working example](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples).
 
 ```bash
 # Install dependencies (after creating package.json and tsconfig.json)

docs/docs-developers/docs/tutorials/js_tutorials/wallet-extension/06-approval-ui.md

@@ -113,7 +113,7 @@ Utility for address truncation:
 
 The CSS provides a dark theme suited for wallet UIs:
 
-See the full stylesheet at [`popup/popup.css`](https://github.com/aztec-labs-eng/aztec-node/blob/#include_aztec_version/docs/examples/webapp-tutorial/test-extension/popup/popup.css).
+See the full stylesheet at [`popup/popup.css`](https://github.com/AztecProtocol/aztec-packages/blob/#docs_commit/docs/examples/webapp-tutorial/test-extension/popup/popup.css).
 
 Key design choices:
 - Dark background (`#1a1a2e`) for modern look

docs/docs-developers/docs/tutorials/js_tutorials/webapp/04-contract-interaction.md

@@ -13,7 +13,7 @@ Now that you have a wallet, you can deploy the Pod Racing contract and interact
 
 Before your PXE (Private eXecution Environment) can interact with a contract, it needs two pieces of information: the **artifact** (the compiled contract bytecode and ABI) and the **instance** (the deployed address and constructor parameters). Without these, PXE cannot construct proofs or route transactions to the correct contract.
 
-Open [`src/contract.ts`](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples/webapp-tutorial/src/contract.ts). This file imports the generated `PodRacingContract` class from the compiled artifacts and wraps each contract method in a simple async function that the UI components call. The key functions are described below.
+Open [`src/contract.ts`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/webapp-tutorial/src/contract.ts). This file imports the generated `PodRacingContract` class from the compiled artifacts and wraps each contract method in a simple async function that the UI components call. The key functions are described below.
 
 ### Deploying a new contract
 
@@ -55,7 +55,7 @@ The opponent pastes the contract address and game ID to join. Under the hood, th
 
 ## The game board component
 
-Open [`src/components/GameBoard.tsx`](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples/webapp-tutorial/src/components/GameBoard.tsx). The board lets you allocate points across 5 tracks each round. There is a constraint: your total points per round must sum to less than 10 (i.e., at most 9 points). This forces strategic trade-offs — you can't dominate every track.
+Open [`src/components/GameBoard.tsx`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/webapp-tutorial/src/components/GameBoard.tsx). The board lets you allocate points across 5 tracks each round. There is a constraint: your total points per round must sum to less than 10 (i.e., at most 9 points). This forces strategic trade-offs — you can't dominate every track.
 
 ### Submitting a round (private transaction)
 

docs/docs-developers/docs/tutorials/js_tutorials/webapp/06-putting-it-together.md

@@ -72,7 +72,7 @@ When you select "Local" network, the app renders a two-player split-screen on a
 
 ### With browser extension wallet
 
-1. Build and install the tutorial wallet extension (see [`test-extension/README.md`](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples/webapp-tutorial/test-extension) for build and install instructions)
+1. Build and install the tutorial wallet extension (see [`test-extension/README.md`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/webapp-tutorial/test-extension) for build and install instructions)
 2. Run `yarn dev`
 3. Select "Browser Wallet" → connect via the wallet extension → verify emojis match
 4. Play the same flow as above (share the contract address with your opponent)

docs/docs-developers/docs/tutorials/js_tutorials/webapp/index.md

@@ -86,7 +86,7 @@ cd docs/examples/webapp-tutorial
 
 ## Completed example
 
-The full working example including the contract source is available at [`docs/examples/webapp-tutorial/`](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples/webapp-tutorial).
+The full working example including the contract source is available at [`docs/examples/webapp-tutorial/`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/webapp-tutorial).
 
 The example also includes a **functional wallet extension** (`test-extension/`) that can deploy accounts and send real transactions using SponsoredFPC for fee payment. See the [Network & Wallet](./03-network-and-wallet.md#testing-with-the-tutorial-wallet-extension) section for setup instructions.
 

docs/docs-developers/docs/tutorials/js_tutorials/webapp/wallet-sdk/02-wallet-integration.md

@@ -7,7 +7,7 @@ references: ["docs/examples/webapp-tutorial/test-extension/src/background.ts", "
 
 # Wallet extension integration
 
-This page is a reference for wallet extension developers. It walks through each component of the SDK integration; you don't need to follow it step-by-step. For the full source, see the [`test-extension/`](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples/webapp-tutorial/test-extension) directory.
+This page is a reference for wallet extension developers. It walks through each component of the SDK integration; you don't need to follow it step-by-step. For the full source, see the [`test-extension/`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/webapp-tutorial/test-extension) directory.
 
 ## What you'll learn
 
@@ -29,19 +29,19 @@ A wallet extension has three components that use the SDK:
 
 ## Content script
 
-The content script is the simplest piece: it relays messages between the page and the background service worker, and never sees encryption keys. Create a `ContentScriptConnectionHandler` with a transport that provides `sendToBackground(message)` and `addBackgroundListener(handler)`, then call `handler.start()`. See [`test-extension/src/content-script.ts`](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples/webapp-tutorial/test-extension/src/content-script.ts) for the full implementation.
+The content script is the simplest piece: it relays messages between the page and the background service worker, and never sees encryption keys. Create a `ContentScriptConnectionHandler` with a transport that provides `sendToBackground(message)` and `addBackgroundListener(handler)`, then call `handler.start()`. See [`test-extension/src/content-script.ts`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/webapp-tutorial/test-extension/src/content-script.ts) for the full implementation.
 
 ## Background service worker
 
 The background script is where most of the SDK integration happens.
 
 ### Configuration
 
-Define your wallet's identity in a config object with `walletId`, `name`, `icon`, and `chainId`. See [`test-extension/src/config.ts`](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples/webapp-tutorial/test-extension/src/config.ts).
+Define your wallet's identity in a config object with `walletId`, `name`, `icon`, and `chainId`. See [`test-extension/src/config.ts`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/webapp-tutorial/test-extension/src/config.ts).
 
 ### Transport
 
-The background transport sends messages to content scripts via `chrome.tabs.sendMessage` and filters incoming messages. Only discovery, key exchange, and encrypted wallet messages reach the handler (popup and storage proxy messages are filtered out). See the transport setup in [`test-extension/src/background.ts`](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples/webapp-tutorial/test-extension/src/background.ts).
+The background transport sends messages to content scripts via `chrome.tabs.sendMessage` and filters incoming messages. Only discovery, key exchange, and encrypted wallet messages reach the handler (popup and storage proxy messages are filtered out). See the transport setup in [`test-extension/src/background.ts`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/webapp-tutorial/test-extension/src/background.ts).
 
 ### Handler initialization
 
@@ -140,7 +140,7 @@ The offscreen document hosts your wallet implementation. Extend `BaseWallet` to
 | `getAccounts()` | Return all accounts (with aliases) |
 
 :::tip Custom Fee Payment
-`completeFeeOptions` has a default implementation that uses the sender's fee juice balance. Override it to inject a custom fee payment strategy (e.g., `SponsoredFPC`). The tutorial wallet overrides this; see [`test-extension/src/offscreen/offscreen.ts`](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples/webapp-tutorial/test-extension/src/offscreen/offscreen.ts) for the implementation.
+`completeFeeOptions` has a default implementation that uses the sender's fee juice balance. Override it to inject a custom fee payment strategy (e.g., `SponsoredFPC`). The tutorial wallet overrides this; see [`test-extension/src/offscreen/offscreen.ts`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/webapp-tutorial/test-extension/src/offscreen/offscreen.ts) for the implementation.
 :::
 
 ### What BaseWallet provides
@@ -197,7 +197,7 @@ The `BackgroundConnectionHandler`'s internal state (active sessions, pending dis
 
 ## Extension lifecycle
 
-On install/update, clear pending state since sessions don't survive reloads. On startup, restore persisted state and preload the offscreen document to warm up WASM. See the lifecycle handlers in [`test-extension/src/background.ts`](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples/webapp-tutorial/test-extension/src/background.ts).
+On install/update, clear pending state since sessions don't survive reloads. On startup, restore persisted state and preload the offscreen document to warm up WASM. See the lifecycle handlers in [`test-extension/src/background.ts`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/examples/webapp-tutorial/test-extension/src/background.ts).
 
 ## Next steps
 

docs/lines/v6/docs-developers/docs/aztec-nr/framework-description/ethereum_aztec_messaging.md

@@ -91,7 +91,7 @@ const witness = await aztecNode.getL2ToL1MembershipWitness(
 
 ## Example implementations
 
-- [Token Portal (L1)](https://github.com/aztec-labs-eng/aztec-node/blob/#include_aztec_version/docs/examples/solidity/example_swap/ExampleTokenPortal.sol)
+- [Token Portal (L1)](https://github.com/AztecProtocol/aztec-packages/blob/#docs_commit/docs/lines/v6/examples/solidity/example_swap/ExampleTokenPortal.sol)
 - [Token Bridge (L2)](https://github.com/aztec-labs-eng/aztec-node/blob/#include_aztec_version/noir-projects/noir-contracts/contracts/app/token_bridge_contract/src/main.nr)
 
 ## Next steps

docs/lines/v6/docs-developers/docs/aztec-nr/index.md

@@ -60,7 +60,7 @@ and import dependencies from the Aztec.nr library.
 
 :::info
 
-You can see a complete example of a simple counter contract written with Aztec.nr [here](https://github.com/aztec-labs-eng/aztec-node/blob/#include_aztec_version/docs/examples/contracts/counter_contract/src/main.nr).
+You can see a complete example of a simple counter contract written with Aztec.nr [here](https://github.com/AztecProtocol/aztec-packages/blob/#docs_commit/docs/lines/v6/examples/contracts/counter_contract/src/main.nr).
 
 :::
 

docs/lines/v6/docs-developers/docs/tutorials/contract_tutorials/recursive_verification.md

@@ -13,7 +13,7 @@ This is called "recursive" verification because the proof is verified inside an
 :::
 
 :::tip Full Working Example
-The complete code for this tutorial is available in the [docs/examples](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples) directory. Clone it to follow along or use it as a reference.
+The complete code for this tutorial is in [`docs/lines/v6/examples/`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/lines/v6/examples): the circuit in [`circuits/hello_circuit`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/lines/v6/examples/circuits/hello_circuit), the contract in [`contracts/recursive_verification_contract`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/lines/v6/examples/contracts/recursive_verification_contract) and the scripts in [`ts/recursive_verification`](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/lines/v6/examples/ts/recursive_verification). Use it as a reference while you follow along.
 :::
 
 ## Prerequisites
@@ -675,7 +675,7 @@ The counter starts at 10 (set during deployment), and after successful proof ver
 
 ## Quick Reference
 
-If you want to run all commands at once, or if you're starting fresh, here's the complete workflow. You can also reference the [full working example](https://github.com/aztec-labs-eng/aztec-node/tree/#include_aztec_version/docs/examples) in the main repository.
+If you want to run all commands at once, or if you're starting fresh, here's the complete workflow. You can also reference the [full working example](https://github.com/AztecProtocol/aztec-packages/tree/#docs_commit/docs/lines/v6/examples).
 
 ```bash
 # Install dependencies (after creating package.json and tsconfig.json)

docs/lines/v6/docs-developers/docs/tutorials/js_tutorials/wallet-extension/06-approval-ui.md

@@ -113,7 +113,7 @@ Utility for address truncation:
 
 The CSS provides a dark theme suited for wallet UIs:
 
-See the full stylesheet at [`popup/popup.css`](https://github.com/aztec-labs-eng/aztec-node/blob/#include_aztec_version/docs/examples/webapp-tutorial/test-extension/popup/popup.css).
+See the full stylesheet at [`popup/popup.css`](https://github.com/AztecProtocol/aztec-packages/blob/#docs_commit/docs/lines/v6/examples/webapp-tutorial/test-extension/popup/popup.css).
 
 Key design choices:
 - Dark background (`#1a1a2e`) for modern look