feat(docs): integrate recursive verification tutorial into docs/examples (#20025)

## Summary

- Integrate the recursive verification tutorial code from aztec-examples
repo into `docs/examples/` so it can be validated by CI and won't go
stale
- Update the tutorial to use `#include_code` macros to pull code from
the example files
- Add support for vanilla Noir circuits in the docs examples bootstrap

## Changes

**New example files:**
- `docs/examples/circuits/hello_circuit/` - Vanilla Noir circuit that
proves x != y
- `docs/examples/contracts/recursive_verification_contract/` - Aztec
contract with proof verification
- `docs/examples/ts/recursive_verification/` - TypeScript files for
proof generation and deployment

**Infrastructure updates:**
- `docs/examples/bootstrap.sh` - Added `compile-circuits` function for
vanilla Noir circuits
- `docs/examples/ts/bootstrap.sh` - Added support for `link:`
dependencies (bb.js, noir-noir_js)
- `docs/Nargo.toml` - Added recursive_verification_contract to workspace

**Tutorial updates:**
- Updated `recursive_verification.md` to use `#include_code` macros for:
  - Circuit code and Nargo.toml
  - Full contract code
  - TypeScript generate_data.ts and sponsored_fpc.ts
- Updated links to point to docs/examples in the main repo

## Test plan

- [ ] Verify circuit compiles: `cd docs/examples/circuits && nargo
compile --workspace`
- [ ] Verify contract compiles: `cd docs && nargo compile` (for
recursive_verification_contract)
- [ ] Verify docs build with include_code macros
- [ ] Run full `docs/examples/bootstrap.sh` (note: may have pre-existing
issues with bob_token_contract)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: AztecBot

docs/Nargo.toml

@@ -3,5 +3,6 @@ members = [
     "examples/contracts/counter_contract",
     "examples/contracts/bob_token_contract",
     "examples/contracts/nft",
-    "examples/contracts/nft_bridge"
+    "examples/contracts/nft_bridge",
+    "examples/contracts/recursive_verification_contract"
 ]

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

@@ -12,7 +12,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 at [aztec-examples/recursive_verification](https://github.com/AztecProtocol/aztec-examples/tree/v3.0.0-devnet.6-patch.1/recursive_verification). Clone it to follow along or use it as a reference.
+The complete code for this tutorial is available in the [docs/examples](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/docs/examples) directory. Clone it to follow along or use it as a reference.
 :::
 
 ## Prerequisites
@@ -131,16 +131,7 @@ circuit/
 
 Replace the contents of `circuit/src/main.nr` with:
 
-```rust
-fn main(x: u64, y: pub u64) {
-    assert(x != y);
-}
-
-#[test]
-fn test_main() {
-    main(1, 2);
-}
-```
+#include_code circuit /docs/examples/circuits/hello_circuit/src/main.nr rust
 
 This is intentionally minimal to focus on the verification pattern. In production, you would replace `assert(x != y)` with meaningful computations like:
 
@@ -170,14 +161,7 @@ For example, you could create a zkpassport proof demonstrating that you are over
 
 Update `circuit/Nargo.toml` (see [Noir crates and packages](https://noir-lang.org/docs/noir/modules_packages_crates/crates_and_packages) for more details):
 
-```toml
-[package]
-name = "hello_circuit"
-type = "bin"
-authors = ["[YOUR_NAME]"]
-
-[dependencies]
-```
+#include_code circuit_nargo_toml /docs/examples/circuits/hello_circuit/Nargo.toml toml
 
 **Note**: This is a vanilla Noir circuit, not an Aztec contract. It has `type = "bin"` (binary) and no Aztec dependencies. The circuit is compiled with `nargo`, not `aztec compile`. This distinction is important—you can verify proofs from _any_ Noir circuit inside Aztec contracts.
 
@@ -267,70 +251,7 @@ bb_proof_verification = { git = "https://github.com/AztecProtocol/aztec-packages
 
 Replace the contents of `contract/src/main.nr` with:
 
-```rust
-use aztec::macros::aztec;
-
-#[aztec]
-pub contract ValueNotEqual {
-    use aztec::{
-        macros::{functions::{external, initializer, internal, only_self, view}, storage::storage},
-        oracle::debug_log::debug_log_format,
-        protocol::{address::AztecAddress, traits::ToField},
-        state_vars::{Map, PublicImmutable, PublicMutable},
-    };
-    use bb_proof_verification::{UltraHonkVerificationKey, UltraHonkZKProof, verify_honk_proof};
-
-    #[storage]
-    struct Storage<Context> {
-        counters: Map<AztecAddress, PublicMutable<Field, Context>, Context>,
-        vk_hash: PublicImmutable<Field, Context>,
-    }
-
-    #[initializer]
-    #[external("public")]
-    fn constructor(headstart: Field, owner: AztecAddress, vk_hash: Field) {
-        self.storage.counters.at(owner).write(headstart);
-        self.storage.vk_hash.initialize(vk_hash);
-    }
-
-    #[external("private")]
-    fn increment(
-        owner: AztecAddress,
-        verification_key: UltraHonkVerificationKey,
-        proof: UltraHonkZKProof,
-        public_inputs: [Field; 1],
-    ) {
-        debug_log_format("Incrementing counter for owner {0}", [owner.to_field()]);
-
-        // Read the stored VK hash - this is readable from private context
-        // because PublicImmutable values are committed at deployment
-        let vk_hash = self.storage.vk_hash.read();
-
-        // Verify the proof - this is the core operation
-        // The function checks:
-        // 1. The VK hashes to the stored vk_hash
-        // 2. The proof is valid for the given VK and public inputs
-        verify_honk_proof(verification_key, proof, public_inputs, vk_hash);
-
-        // If we reach here, the proof is valid
-        // Enqueue a public function call to update state
-        self.enqueue_self._increment_public(owner);
-    }
-
-    #[only_self]
-    #[external("public")]
-    fn _increment_public(owner: AztecAddress) {
-        let current = self.storage.counters.at(owner).read();
-        self.storage.counters.at(owner).write(current + 1);
-    }
-
-    #[view]
-    #[external("public")]
-    fn get_counter(owner: AztecAddress) -> Field {
-        self.storage.counters.at(owner).read()
-    }
-}
-```
+#include_code full_contract /docs/examples/contracts/recursive_verification_contract/src/main.nr rust
 
 ### Storage Variables Explained
 
@@ -539,80 +460,7 @@ The proof generation script executes the circuit offchain and produces the proof
 
 Create `scripts/generate_data.ts`:
 
-```typescript
-import { Noir } from "@aztec/noir-noir_js";
-import circuitJson from "../circuit/target/hello_circuit.json" with { type: "json" };
-import { Barretenberg, UltraHonkBackend, deflattenFields } from "@aztec/bb.js";
-import fs from "fs";
-import { exit } from "process";
-
-// Step 1: Initialize Barretenberg API (the proving system backend)
-// Barretenberg is the C++ library that implements UltraHonk
-// threads: 1 uses single-threaded mode (increase for faster proofs on multi-core machines)
-const barretenbergAPI = await Barretenberg.new({ threads: 1 });
-
-// Step 2: Create Noir circuit instance from compiled bytecode
-// This loads the circuit definition so we can execute it
-const helloWorld = new Noir(circuitJson as any);
-
-// Step 3: Execute circuit with inputs to generate witness
-// The witness is all intermediate values computed during circuit execution
-// x=1 (private), y=2 (public) - proves that 1 != 2
-const { witness: mainWitness } = await helloWorld.execute({ x: 1, y: 2 });
-
-// Step 4: Create UltraHonk backend with circuit bytecode
-// The backend handles proof generation and verification
-const mainBackend = new UltraHonkBackend(circuitJson.bytecode, barretenbergAPI);
-
-// Step 5: Generate proof targeting the noir-recursive verifier
-// verifierTarget: 'noir-recursive' creates a proof format suitable for
-// verification inside another Noir circuit (which is what Aztec contracts are)
-const mainProofData = await mainBackend.generateProof(mainWitness, {
-  verifierTarget: "noir-recursive",
-});
-
-// Step 6: Verify proof locally before saving
-// This catches errors early - if verification fails here, it will fail onchain too
-const isValid = await mainBackend.verifyProof(mainProofData, {
-  verifierTarget: "noir-recursive",
-});
-console.log(`Proof verification: ${isValid ? "SUCCESS" : "FAILED"}`);
-
-// Step 7: Generate recursive artifacts for onchain use
-// This converts the proof and VK into field element arrays that can be
-// passed to the Aztec contract
-const recursiveArtifacts = await mainBackend.generateRecursiveProofArtifacts(
-  mainProofData.proof,
-  mainProofData.publicInputs.length,
-);
-
-// Step 8: Convert proof to field elements if needed
-// Some versions return empty proofAsFields, requiring manual conversion
-let proofAsFields = recursiveArtifacts.proofAsFields;
-if (proofAsFields.length === 0) {
-  console.log("Using deflattenFields to convert proof...");
-  proofAsFields = deflattenFields(mainProofData.proof).map((f) => f.toString());
-}
-
-const vkAsFields = recursiveArtifacts.vkAsFields;
-
-console.log(`VK size: ${vkAsFields.length}`); // Should be 115
-console.log(`Proof size: ${proofAsFields.length}`); // Should be 508
-console.log(`Public inputs: ${mainProofData.publicInputs.length}`); // Should be 1
-
-// Step 9: Save all data to JSON for contract interaction
-const data = {
-  vkAsFields: vkAsFields, // 115 field elements - the verification key
-  vkHash: recursiveArtifacts.vkHash, // Hash of VK - stored in contract
-  proofAsFields: proofAsFields, // 508 field elements - the proof
-  publicInputs: mainProofData.publicInputs.map((p: string) => p.toString()),
-};
-
-fs.writeFileSync("data.json", JSON.stringify(data, null, 2));
-await barretenbergAPI.destroy();
-console.log("Done");
-exit();
-```
+#include_code generate_data /docs/examples/ts/recursive_verification/scripts/generate_data.ts typescript
 
 ### Understanding the Proof Generation Pipeline
 
@@ -900,22 +748,7 @@ This single line triggers a complex flow:
 
 Create `scripts/sponsored_fpc.ts`:
 
-```typescript
-import { getContractInstanceFromInstantiationParams } from "@aztec/aztec.js/contracts";
-import { Fr } from "@aztec/aztec.js/fields";
-import { SponsoredFPCContract } from "@aztec/noir-contracts.js/SponsoredFPC";
-
-const SPONSORED_FPC_SALT = new Fr(BigInt(0));
-
-export async function getSponsoredFPCInstance() {
-  return await getContractInstanceFromInstantiationParams(
-    SponsoredFPCContract.artifact,
-    {
-      salt: SPONSORED_FPC_SALT,
-    },
-  );
-}
-```
+#include_code sponsored_fpc /docs/examples/ts/recursive_verification/scripts/sponsored_fpc.ts typescript
 
 This utility computes the address of the pre-deployed sponsored FPC contract. The salt ensures we get the same address every time. For more information about fee payment options, see [Paying Fees](../../aztec-js/how_to_pay_fees.md).
 
@@ -955,7 +788,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 clone the [full working example](https://github.com/AztecProtocol/aztec-examples/tree/main/recursive_verification) to get started quickly.
+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/#include_aztec_version/docs/examples) in the main repository.
 
 ```bash
 # Install dependencies (after creating package.json and tsconfig.json)

docs/examples/bootstrap.sh

@@ -9,6 +9,28 @@ export NARGO=${NARGO:-"$REPO_ROOT/noir/noir-repo/target/release/nargo"}
 export TRANSPILER=${TRANSPILER:-"$REPO_ROOT/avm-transpiler/target/release/avm-transpiler"}
 export STRIP_AZTEC_NR_PREFIX=${STRIP_AZTEC_NR_PREFIX:-"$REPO_ROOT/noir-projects/noir-contracts/scripts/strip_aztec_nr_prefix.sh"}
 export BB_HASH=${BB_HASH:-$("$REPO_ROOT/barretenberg/cpp/bootstrap.sh" hash)}
+export NOIR_HASH=${NOIR_HASH:-$("$REPO_ROOT/noir/bootstrap.sh" hash)}
+
+function compile-circuits {
+  echo_header "Compiling vanilla Noir circuits"
+  local CIRCUITS_DIR="$REPO_ROOT/docs/examples/circuits"
+
+  if [ ! -d "$CIRCUITS_DIR" ]; then
+    echo_stderr "No circuits directory found at $CIRCUITS_DIR"
+    return 0
+  fi
+
+  if [ ! -f "$CIRCUITS_DIR/Nargo.toml" ]; then
+    echo_stderr "No workspace Nargo.toml found in $CIRCUITS_DIR"
+    return 0
+  fi
+
+  # Compile all circuits in the workspace
+  echo_stderr "Compiling circuits workspace..."
+  (cd "$CIRCUITS_DIR" && $NARGO compile --workspace)
+
+  echo_stderr "Vanilla circuits compiled"
+}
 
 function compile {
   echo_header "Compiling example contracts"
@@ -121,8 +143,11 @@ function run_step {
   local step_func=$2
   local output exit_code
 
+  # Disable errexit for command substitution to properly capture exit code
+  set +e
   output=$($step_func 2>&1)
   exit_code=$?
+  set -e
   echo "$output"
 
   if [[ $exit_code -ne 0 ]]; then
@@ -154,6 +179,7 @@ function post_failure_comment_for_steps {
 
 case "$cmd" in
   "")
+    run_step "Compile (Noir circuits)" compile-circuits
     run_step "Compile (Noir contracts)" compile
     run_step "Compile (Solidity)" compile-solidity
     run_step "TypeScript validation" validate-ts
@@ -167,6 +193,9 @@ case "$cmd" in
       fi
     fi
     ;;
+  compile-circuits)
+    compile-circuits
+    ;;
   compile-solidity)
     compile-solidity
     ;;

docs/examples/circuits/Nargo.toml

@@ -0,0 +1,4 @@
+[workspace]
+members = [
+    "hello_circuit"
+]

docs/examples/circuits/hello_circuit/Nargo.toml

@@ -0,0 +1,8 @@
+# docs:start:circuit_nargo_toml
+[package]
+name = "hello_circuit"
+type = "bin"
+authors = [""]
+
+[dependencies]
+# docs:end:circuit_nargo_toml

docs/examples/circuits/hello_circuit/src/main.nr

@@ -0,0 +1,10 @@
+// docs:start:circuit
+fn main(x: u64, y: pub u64) {
+    assert(x != y);
+}
+
+#[test]
+fn test_main() {
+    main(1, 2);
+}
+// docs:end:circuit

docs/examples/contracts/recursive_verification_contract/Nargo.toml

@@ -0,0 +1,11 @@
+# docs:start:nargo_toml
+[package]
+name = "recursive_verification_contract"
+type = "contract"
+authors = [""]
+compiler_version = ">=0.25.0"
+
+[dependencies]
+aztec = { path = "../../../../noir-projects/aztec-nr/aztec" }
+bb_proof_verification = { path = "../../../../barretenberg/noir/bb_proof_verification" }
+# docs:end:nargo_toml