fix: backport v4 next staging

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.1.0"
+  ".": "4.2.0"
 }

aztec-up/bin/0.0.1/aztec-install

@@ -28,6 +28,32 @@ VERSION="${VERSION:-nightly}"
 # Install URI (root, not version-specific)
 INSTALL_URI="${INSTALL_URI:-https://install.aztec-labs.com}"
 
+# Check if version string is valid semver
+function is_semver {
+  local version="$1"
+  local semver_regex='^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.]+)?$'
+  [[ "$version" =~ $semver_regex ]]
+}
+
+# Resolve alias (like "nightly") to actual version number.
+function resolve_version {
+  local version="$1"
+  # Strip leading v from semver-like inputs (v0.85.0 -> 0.85.0), but not aliases (v4-nightly)
+  local stripped="${version#v}"
+  if is_semver "$stripped"; then
+    echo "$stripped"
+  else
+    local resolved
+    if ! resolved=$(curl -fsSL "$INSTALL_URI/aliases/$version" 2>/dev/null); then
+      echo "Error: Could not resolve alias '$version'" >&2
+      exit 1
+    fi
+    echo "$resolved"
+  fi
+}
+
+VERSION=$(resolve_version "$VERSION")
+
 # Add color to the AZTEC ascii art.
 function print_colored() {
   local b=$'\033[34m' # Blue
@@ -166,7 +192,7 @@ function update_path_env_var {
   if grep -q '\.aztec' "$shell_profile" 2>/dev/null; then
     # Remove old aztec PATH entries.
     local tmp_file=$(mktemp)
-    grep -Ev 'export PATH=.*/\.aztec/' "$shell_profile" > "$tmp_file" || true
+    grep -Ev 'export PATH="\$(HOME/\.aztec/|PATH:.*\.aztec/)' "$shell_profile" > "$tmp_file" || true
     mv "$tmp_file" "$shell_profile"
   fi
 

aztec-up/bin/0.0.1/aztec-up

@@ -102,8 +102,10 @@ function is_semver {
 # Resolve alias (like "nightly") to actual version number
 function resolve_version {
   local version="$1"
-  if is_semver "$version"; then
-    echo "$version"
+  # Strip leading v from semver-like inputs (v0.85.0 -> 0.85.0), but not aliases (v4-nightly)
+  local stripped="${version#v}"
+  if is_semver "$stripped"; then
+    echo "$stripped"
   else
     # Fetch alias file to get actual version
     local resolved

barretenberg/cpp/src/barretenberg/crypto/merkle_tree/node_store/cached_content_addressed_tree_store.hpp

@@ -867,17 +867,17 @@ void ContentAddressedCachedTreeStore<LeafValueType>::advance_finalized_block(con
         ReadTransactionPtr readTx = create_read_transaction();
         get_meta(uncommittedMeta);
         get_meta(committedMeta, *readTx, false);
+        // do nothing if the block is already finalized
+        if (committedMeta.finalizedBlockHeight >= blockNumber) {
+            return;
+        }
         if (!dataStore_->read_block_data(blockNumber, blockPayload, *readTx)) {
             throw std::runtime_error(format("Unable to advance finalized block: ",
                                             blockNumber,
                                             ". Failed to read block data. Tree name: ",
                                             forkConstantData_.name_));
         }
     }
-    // do nothing if the block is already finalized
-    if (committedMeta.finalizedBlockHeight >= blockNumber) {
-        return;
-    }
 
     // can currently only finalize up to the unfinalized block height
     if (committedMeta.finalizedBlockHeight > committedMeta.unfinalizedBlockHeight) {

docs/.gitignore

@@ -34,3 +34,4 @@ test-results
 
 target
 static/aztec-nr-api/next
+static/typescript-api/next

docs/CLAUDE.md

@@ -110,14 +110,17 @@ Default content
 - `static/img/` - Static images and assets
 - `static/aztec-nr-api/` - Auto-generated Aztec.nr API documentation (HTML)
 - `static/typescript-api/` - Auto-generated TypeScript API documentation (markdown)
+- `examples/` - Code examples (Noir circuits, Noir contracts, Solidity, TypeScript)
+- `examples/ts/` - TypeScript aztec.js examples with `docker-compose.yml` for CI execution
+- `examples/ts/aztecjs_runner/` - Runner script that executes examples against a live network
 - `scripts/` - Build and utility scripts
 - `scripts/typescript_api_generation/` - TypeScript API doc generation scripts and config
 
 ### Content Structure
 
 This site uses **Docusaurus multi-instance docs** with independent versioning:
 
-- **Developer Guides** (`/developers/`) - Getting started, tutorials, references (devnet + nightly versions)
+- **Developer Guides** (`/developers/`) - Getting started, tutorials, references (testnet + devnet + nightly versions)
 - **Network Guides** (`/network/`) - Node operation and network participation (testnet + ignition versions)
 
 ### Auto-Generated API Documentation
@@ -142,6 +145,23 @@ Uses Docusaurus multi-instance versioning with separate version tracks:
 - Preprocessing macros (`#include_code`, `#release_version`, conditionals, etc.) only work in source folders, not in versioned copies
 - Create new versions with: `yarn docusaurus docs:version:<instance-id> <version>`
 
+### Code Examples Pipeline
+
+The `examples/` directory contains runnable code examples that are included in documentation via `#include_code` markers. The examples pipeline has two stages:
+
+**Validation (type-checking)**: `examples/bootstrap.sh` compiles Noir circuits, Noir contracts, Solidity, and type-checks TypeScript examples. This runs on every PR.
+
+**Execution (runtime testing)**: TypeScript examples in `examples/ts/` are executed against a live Aztec network via Docker Compose. The `examples/ts/docker-compose.yml` spins up Anvil (L1 fork), an Aztec local network, and a runner service that executes the examples.
+
+- **CI**: `docs/bootstrap.sh ci` calls `examples/bootstrap.sh execute`, which uses `run_compose_test` from `ci3/`
+- **Local**: Start a sandbox manually, then run `examples/ts/aztecjs_runner/run.sh`
+- **`AZTEC_NODE_URL`**: All example `index.ts` files and `run.sh` use this env var (defaults to `http://localhost:8080`). In Docker Compose, it points to `http://local-network:8080`.
+
+When adding new TypeScript examples:
+1. Create a directory under `examples/ts/` with `index.ts`, `config.yaml`, and empty `yarn.lock`
+2. Use `process.env.AZTEC_NODE_URL ?? "http://localhost:8080"` for the node URL
+3. Add the example to the list in `examples/ts/aztecjs_runner/run.sh` if it should be executed at runtime
+
 ## Documentation Review Standards
 
 ## Primary Review Objectives
@@ -274,6 +294,7 @@ The description should:
 - ❌ Legal disclaimers or license text
 - ❌ Direct quotes from external sources
 - ❌ API endpoint URLs or configuration values
+- ❌ Existing migration notes in `resources/migration_notes.md` — never modify already-published migration entries. Instead, add new migration notes to the `## TBD` section at the top of the file.
 
 ## Review Output Format
 
@@ -329,5 +350,5 @@ Approved external documentation sources:
 - Suggest improvements even if they go beyond pure editing
 - When making changes to documentation processes or tooling, remember to check and update READMEs, project documentation (like this file), and code comments
 
-Last updated: 2026-02-04
-Version: 1.4
+Last updated: 2026-02-23
+Version: 1.5

docs/Nargo.toml

@@ -1,5 +1,6 @@
 [workspace]
 members = [
+    "examples/circuits/hello_circuit",
     "examples/contracts/counter_contract",
     "examples/contracts/bob_token_contract",
     "examples/contracts/nft",

docs/README.md

@@ -20,11 +20,12 @@ Here are the most relevant files you should be aware of:
 - `.env.template` - Template for environment variables required for Netlify functions (copy to `.env` and update with your API keys).
 - `netlify.toml` - Configuration for Netlify deployment and functions.
 
-This site uses **Docusaurus multi-instance docs** with two separate documentation areas:
+This site uses **Docusaurus multi-instance docs** with separate documentation areas:
 
 - `docs/` - Root-level documentation (landing page, shared content)
 - `docs-developers/` - Developer documentation source files (tutorials, references, guides)
-- `docs-network/` - Network/node operator documentation source files
+- `docs-operate/` - Operator documentation source files
+- `docs-participate/` - Participation / educational documentation source files
 
 See the [Docusaurus website](https://docusaurus.io/docs/docs-introduction) for the full documentation on how to create docs and to manage the metadata.
 
@@ -37,10 +38,11 @@ Aztec Docs use **multi-instance versioning** with separate version tracks for de
 
 Each versioned docs folder is a complete copy of the documentation at that point in time, which allows you to hot-fix previous versions.
 
-When you look at the published docs site, you will see version dropdowns for each docs instance. Developer docs show versions like `nightly` and `devnet`, while network docs show versions like `testnet` and `ignition`.
+When you look at the published docs site, you will see version dropdowns for each docs instance. Developer docs show versions like `testnet`, `devnet`, and `nightly`, while network docs show versions like `testnet` and `ignition`.
 
 - Updating files in `docs-developers/` updates the "next" developer version
-- Updating files in `docs-network/` updates the "next" network version
+- Updating files in `docs-operate/` updates the "next" operate version
+- Updating files in `docs-participate/` updates the unversioned participate docs
 - Updating files in versioned folders like `developer_versioned_docs/version-v3.0.0-devnet.5/` updates that specific version
 
 Note that you cannot use the macros (`#include_aztec_version` and `#include_code`) in versioned folders, since those docs have already been processed and built. Instead, drop the code snippets, version numbers or links directly in the docs as you'd like them to be rendered.
@@ -93,6 +95,7 @@ Each docs instance has its own version file and lookup logic:
 ```javascript
 const nightlyVersion = developerVersions.find((v) => v.includes("nightly"));
 const devnetVersion = developerVersions.find((v) => v.includes("devnet"));
+const developerTestnetVersion = developerVersions.find((v) => v.includes("rc") || v.includes("testnet"));
 ```
 
 **Network docs** (from `network_versions.json`):
@@ -107,7 +110,7 @@ This ensures that:
 - When nightly versions are removed by the cleanup script, the build doesn't break
 - Version configurations are conditionally included only if they exist
 - Array index shifts don't cause mismatched version configurations
-- The llms.txt plugin always points to the correct version (devnet)
+- The llms.txt plugin always points to the correct version (testnet)
 
 **Why this matters:** The [nightly docs workflow](../.github/workflows/nightly-docs-release.yml) runs `cleanup_nightly_versions.sh` before creating new versioned docs. Without dynamic lookup, removing versions would cause array indices to point to wrong versions, breaking the build.
 
@@ -570,28 +573,17 @@ Building on the DevRel review automation, the docs CI can analyze PRs and notify
 - `SLACK_DOC_UPDATE_CHANNEL` - Slack channel for notifications (default: `#devrel`)
 - `DRY_RUN=1` - Skip Slack notification, just print what would be sent
 
-**Implementation**: The automation is handled by `scripts/update_doc_references.sh`, which runs as part of the docs CI pipeline after `check_doc_references.sh`.
+**Implementation**: The automation is handled by `scripts/check_doc_references.sh`, which detects changed references, requests devrel review, sends a Slack notification, and dispatches ClaudeBox — all in a single pass.
 
 **Script Architecture**:
 
-- `scripts/update_doc_references.sh` - Main script that orchestrates the workflow
+- `scripts/check_doc_references.sh` - Main script that handles detection, review requests, Slack, and ClaudeBox dispatch
 - `scripts/lib/extract_doc_references.sh` - Shared library for parsing frontmatter references
 - `scripts/lib/create_doc_update_pr.sh` - (Reserved for future use) PR creation logic
-- `scripts/test_update_doc_references.sh` - Local testing helper
-
-**Local Testing**:
-
-```bash
-# Find a PR with referenced file changes and test
-./scripts/test_update_doc_references.sh
-
-# Test against a specific PR
-LOCAL_TEST=1 DRY_RUN=1 ./scripts/update_doc_references.sh 19803
-```
 
 **Limitations**:
 
-- Only analyzes documentation in the source folders (`docs-developers/`, `docs-network/`), not versioned docs
+- Only analyzes documentation in the source folders (`docs-developers/`, `docs-operate/`, `docs-participate/`), not versioned docs
 - Suggested changes should always be reviewed by a human before applying
 - The AI may occasionally suggest unnecessary or incorrect changes
 

docs/bootstrap.sh

@@ -52,19 +52,12 @@ function test {
 }
 
 function check_references {
-  echo_header "Check doc references"
-  ./scripts/check_doc_references.sh docs
-}
-
-function update_doc_references {
-  echo_header "Auto-update doc references"
-  # Only run if Claude Code CLI is available
-  if command -v claude &> /dev/null; then
-    ./scripts/update_doc_references.sh docs
-  else
-    echo "Claude Code CLI not available. Skipping automatic doc updates."
-    echo "To enable automatic doc updates, install Claude Code: npm install -g @anthropic-ai/claude-code"
+  if [[ "${GITHUB_EVENT_NAME:-}" != "merge_group" ]]; then
+    echo "Skipping doc reference check (only runs in merge queue)."
+    return
   fi
+  echo_header "Check doc references"
+  ./scripts/check_doc_references.sh docs || true
 }
 
 function build_examples {
@@ -78,7 +71,6 @@ case "$cmd" in
     build_docs
     test
     check_references
-    update_doc_references
     ;;
   "")
     build_examples