diff --git a/.claude/README.md b/.claude/README.md
new file mode 100644
index 000000000000..ac93612b1963
--- /dev/null
+++ b/.claude/README.md
@@ -0,0 +1,21 @@
+# `.claude/`
+
+Project-level Claude Code configuration for aztec-packages. This file documents layout decisions; the filesystem describes the contents.
+
+## Layout rules
+
+1. Universal content lives at repository root: `CLAUDE.md`, `.claude/agents/`, `.claude/scripts/`, and the root `settings.json` hooks.
+2. Subdirectory `.claude/` directories hold only component-specific skills, permission allowlists, and settings. Content is not merged upward.
+3. A subdirectory that has its own `.claude/` must symlink `agents/` to the repository root's `.claude/agents/`. Claude Code's ancestor walk stops at the nearest `.claude/` and does not merge ancestors, so subdirectories otherwise shadow the root agents. Subdirectories without their own `.claude/` inherit the root automatically. `skills/` is intentionally *not* symlinked — skills are scoped to their subdir (root skills are repo-wide workflows; `yarn-project/.claude/skills/` are TS-specific; etc.).
+4. Prefer XML-tagged sections inside `CLAUDE.md` for prose guidance. A `.claude/rules/` directory is only warranted when a rule needs YAML frontmatter (e.g. path-scoped `paths:` metadata) that `CLAUDE.md` cannot express. `.claude/rules/` without frontmatter does not auto-load when Claude Code is started from a subdirectory, so plain rules files are strictly worse than inlining into `CLAUDE.md`.
+
+## Tests
+
+`tests/format_file_test` exercises each dispatch branch: hygiene (malformed hook input), C++, Rust, Solidity, TypeScript with plugin. Invocation via `./.claude/bootstrap.sh test_cmds` follows the same convention as `ci3/bootstrap.sh`.
+
+## Adding new files
+
+- A new agent used repository-wide: `.claude/agents/` at root.
+- A new skill scoped to one component: `component/.claude/skills/`.
+- A new hook: add a script to `.claude/scripts/`, register it in `.claude/settings.json` via `git rev-parse --show-toplevel` so the path resolves from any cwd, and add a test in `.claude/tests/`. You need to add it to each subdirectory where you want the hook active.
+- A new `.claude/` subdirectory: symlink `agents/` back to the repository root's `.claude/agents/`.
diff --git a/.claude/agents/retrospective.md b/.claude/agents/retrospective.md
deleted file mode 100644
index a40479671606..000000000000
--- a/.claude/agents/retrospective.md
+++ /dev/null
@@ -1,179 +0,0 @@
----
-name: retrospective
-description: |
-  Analyze the current session to extract learnings for self-improvement. Use at the end of a session to:
-  - Capture user corrections and guidelines that can be generalized
-  - Document failed approaches and what worked instead
-  - Identify permissions that should be pre-approved
-  - Extract patterns and conventions learned during the session
-
-  Best used: At the end of a productive session, after debugging sessions where you learned something, or when the user taught you something new.
-
-  <example>
-  user: "Let's do a retrospective on this session"
-  assistant: "I'll analyze our conversation to extract learnings."
-  </example>
-model: opus
-color: magenta
----
-
-You are a Self-Improvement Analyst for Claude Code. Your mission is to analyze the current session transcript and extract learnings that can improve future interactions.
-
-## Core Responsibilities
-
-1. **Transcript Analysis**
-   - You have access to the full conversation history of this session through the current context
-   - Systematically review all exchanges between user and assistant
-   - Pay special attention to corrections, clarifications, and teaching moments
-
-2. **Pattern Recognition**
-   - Identify user corrections: "No, do X instead" or "That's not how we do it"
-   - Find failed attempts followed by successful retries
-   - Note style preferences: naming conventions, code patterns, formatting
-   - Recognize workflow shortcuts the user taught
-   - Spot permission requests that could be pre-approved
-
-3. **Location Discovery**
-   - Before suggesting where to add content, explore existing configuration:
-     * Read `.claude/rules/` for existing rules
-     * Read `.claude/skills/` for existing skills
-     * Read `CLAUDE.md` files for project instructions
-     * Read `.claude/settings.json` for existing permissions
-     * Read `.claude/agents/` for existing agents
-   - Suggest additions to existing files when the topic already has a home
-   - Only suggest new files for distinct, substantial topics
-
-4. **Suggestion Generation**
-   - Generate actionable suggestions with specific content
-   - Include rationale with references to session events
-   - Prioritize high-value learnings (frequent corrections > one-time fixes)
-   - Be concise—extract the essence, not verbose explanations
-
-## What to Look For
-
-### High-Priority Learnings
-
-1. **Direct Corrections**
-   - "No, you should..." / "Actually, we do it this way..."
-   - "Don't use X, use Y instead"
-   - Explanations of why something was wrong
-
-2. **Failed → Success Patterns**
-   - Command failed, then worked with different syntax
-   - Tool used incorrectly, then correctly
-   - Approach abandoned for better alternative
-
-3. **Project Conventions**
-   - File naming patterns
-   - Code organization rules
-   - Testing practices
-   - Build/deployment workflows
-
-4. **Permissions**
-   - Commands that required approval
-   - Patterns in approved commands (could become wildcards)
-
-### Lower-Priority (Include if Substantial)
-
-5. **Preferences**
-   - Formatting styles
-   - Communication preferences
-   - Tool preferences
-
-6. **Domain Knowledge**
-   - Project-specific terminology
-   - Architecture decisions
-   - Integration patterns
-
-## Output Format
-
-Present suggestions in this format:
-
----
-
-## Suggestion [N]: [Brief descriptive title]
-
-**Type**: `Rule` | `Skill` | `CLAUDE.md` | `Permission` | `Agent`
-**File**: `[exact file path]`
-**Action**: `Add` | `Modify` | `Create`
-
-**Rationale**:
-[1-2 sentences explaining what happened in the session that led to this suggestion]
-
-**Proposed Content**:
-```
-[Exact content to add, properly formatted for the target file]
-```
-
-**Location in file**: [Where to insert: "After section X" or "In permissions.allow array" or "New file"]
-
----
-
-## Workflow
-
-1. **Review Context**: Carefully read through the full session transcript
-2. **Identify Learnings**: Note all potential improvements as you read
-3. **Explore Config**: Use Glob and Read to examine existing Claude configuration
-4. **Deduplicate**: Check if learnings are already documented
-5. **Prioritize**: Focus on generalizable, high-impact learnings
-6. **Format**: Present suggestions in the structured format above
-7. **Await Approval**: Present all suggestions and wait for user to accept/reject each
-8. **Implement**: After approval, use Edit tool to make the changes
-
-## Key Principles
-
-- **Be selective**: Not every correction needs documentation—focus on generalizable learnings
-- **Be precise**: Include exact file paths and content, ready to apply
-- **Be concise**: Extract the essence, don't pad with unnecessary explanation
-- **Respect existing structure**: Add to existing files when appropriate
-- **Provide context**: Always explain WHY this should be added (reference session events)
-
-## Example Suggestions
-
-### Example 1: Rule Addition
-
-```markdown
-## Suggestion 1: Always use yarn workspace for tests
-
-**Type**: `Rule`
-**File**: `/path/to/yarn-project/.claude/rules/testing.md`
-**Action**: `Modify` (or `Create` if file doesn't exist)
-
-**Rationale**:
-User corrected me twice when I tried to cd into a package and run `yarn test`. They explained that `yarn workspace` is preferred.
-
-**Proposed Content**:
-## Test Execution
-
-Always use `yarn workspace` to run tests rather than changing directories:
-
-\`\`\`bash
-# Good
-yarn workspace @aztec/archiver test src/archiver.test.ts
-
-# Bad - don't do this
-cd archiver && yarn test src/archiver.test.ts
-\`\`\`
-
-**Location in file**: After "## Test Logging" section (or as new file)
-```
-
-### Example 2: Permission Addition
-
-```markdown
-## Suggestion 2: Pre-approve wc command
-
-**Type**: `Permission`
-**File**: `/path/to/yarn-project/.claude/settings.json`
-**Action**: `Modify`
-
-**Rationale**:
-I requested permission to run `wc -l` three times during log analysis. This is a safe, read-only command.
-
-**Proposed Content**:
-"Bash(wc:*)"
-
-**Location in file**: Add to `permissions.allow` array
-```
-
-Remember: Your goal is to help Claude Code get better over time by capturing the wisdom from each session. Focus on learnings that will help in future, similar situations.
diff --git a/.claude/bootstrap.sh b/.claude/bootstrap.sh
new file mode 100755
index 000000000000..021f5270f3fb
--- /dev/null
+++ b/.claude/bootstrap.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Bootstrap + test entry for the .claude/ tooling directory. Mirrors the shape
+# used by ci3/bootstrap.sh: emits test commands via `test_cmds`, runs them via
+# `test`. Keeps hook scripts and their tests as a self-contained component.
+source $(git rev-parse --show-toplevel)/ci3/source_bootstrap
+
+hash=$(cache_content_hash ^.claude)
+
+function test_cmds {
+  # source_base cd's us into .claude/, so glob relative-to-here, but emit paths
+  # relative to the git root (same convention used by ci3/bootstrap.sh).
+  for f in tests/*; do
+    [[ -x "$f" ]] || continue
+    echo "$hash ./.claude/$f"
+  done
+}
+
+function test {
+  echo_header ".claude tests"
+  test_cmds | filter_test_cmds | parallelize
+}
+
+case "$cmd" in
+  "")
+    test
+    ;;
+  *)
+    default_cmd_handler "$@"
+    ;;
+esac
diff --git a/.claude/scripts/format-file.sh b/.claude/scripts/format-file.sh
new file mode 100755
index 000000000000..37ff1b21519f
--- /dev/null
+++ b/.claude/scripts/format-file.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# PostToolUse hook: format files after Edit/Write by dispatching to the right
+# formatter based on extension. Reads Claude Code's hook JSON from stdin.
+#
+# Never fails the edit — prints hints to stderr on missing tools and exits 0.
+
+set -u
+
+input=$(cat)
+file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+
+[[ -z "$file" ]] && exit 0
+[[ ! -f "$file" ]] && exit 0
+
+hint() { printf 'format-file.sh: %s\n' "$*" >&2; }
+
+case "$file" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.json)
+    root=""
+    if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]] && [[ -f "$CLAUDE_PROJECT_DIR/yarn-project/package.json" ]]; then
+      root="$CLAUDE_PROJECT_DIR"
+    else
+      root=$(git -C "$(dirname "$file")" rev-parse --show-toplevel 2>/dev/null || true)
+    fi
+    if [[ -n "$root" && -x "$root/yarn-project/node_modules/.bin/prettier" ]]; then
+      "$root/yarn-project/node_modules/.bin/prettier" --write --log-level=warn "$file" \
+        || hint "prettier failed on $file"
+    else
+      hint "prettier not found — run yarn-project bootstrap to enable format-on-edit"
+    fi
+    ;;
+  *.cpp|*.cxx|*.cc|*.hpp|*.hxx|*.h)
+    cf=""
+    if command -v clang-format-20 >/dev/null 2>&1; then
+      cf=clang-format-20
+    elif [[ -x /opt/homebrew/opt/llvm/bin/clang-format ]] && /opt/homebrew/opt/llvm/bin/clang-format --version 2>/dev/null | grep -q 'version 20'; then
+      cf=/opt/homebrew/opt/llvm/bin/clang-format
+    elif [[ -x /usr/local/opt/llvm/bin/clang-format ]] && /usr/local/opt/llvm/bin/clang-format --version 2>/dev/null | grep -q 'version 20'; then
+      cf=/usr/local/opt/llvm/bin/clang-format
+    fi
+    if [[ -n "$cf" ]]; then
+      "$cf" -i "$file" || hint "$cf failed on $file"
+    else
+      hint "clang-format 20 not found — install via 'apt install clang-format-20' (Linux) or 'brew install llvm' (macOS)"
+    fi
+    ;;
+  *.rs)
+    # rustfmt walks up from the file path to find .rustfmt.toml, which pins
+    # edition and style. Don't pass --edition here; it would override that.
+    if command -v rustfmt >/dev/null 2>&1; then
+      rustfmt "$file" || hint "rustfmt failed on $file"
+    else
+      hint "rustfmt not found — install via 'rustup component add rustfmt'"
+    fi
+    ;;
+  *.sol)
+    if command -v forge >/dev/null 2>&1; then
+      (cd "$(dirname "$file")" && forge fmt "$file") || hint "forge fmt failed on $file"
+    else
+      hint "forge not found — install foundry via 'curl -L https://foundry.paradigm.xyz | bash && foundryup'"
+    fi
+    ;;
+  *.nr)
+    # nargo fmt operates on whole crates, not individual files.
+    hint "nargo fmt is crate-scoped — run 'nargo fmt' from the noir project directory before committing"
+    ;;
+esac
+
+exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
index 678f0a41a0d0..1cbb77f766c4 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -10,6 +10,17 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'GITROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; [ -n \"$GITROOT\" ] && exec \"$GITROOT/.claude/scripts/format-file.sh\"; exit 0'"
+          }
+        ]
+      }
     ]
   }
 }
diff --git a/.claude/tests/agents_symlink_test b/.claude/tests/agents_symlink_test
new file mode 100755
index 000000000000..3c0ef5f26540
--- /dev/null
+++ b/.claude/tests/agents_symlink_test
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Regression test for the layout rule: every subdir that owns its own .claude/
+# must symlink agents/ to the repository root's .claude/agents/. Without the
+# symlink, Claude Code's upward-walk stops at the subdir .claude/ and silently
+# shadows every root agent.
+#
+# Only agents/ is checked — not skills/. Skills are intentionally per-subdir
+# (the root has repo-wide workflow skills, yarn-project has TS-specific ones,
+# etc.), and letting a subdir shadow root skills/ is the designed behavior.
+# Agents, by contrast, are universal and need to be visible from every cwd.
+#
+# Runs from any cwd.
+
+set -uo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd -P)
+
+RED=$'\033[0;31m'
+GREEN=$'\033[0;32m'
+NC=$'\033[0m'
+
+FAIL=0
+CHECKED=0
+
+fail() { echo "${RED}✗${NC} $1"; ((FAIL++)) || true; }
+pass() { echo "${GREEN}✓${NC} $1"; ((CHECKED++)) || true; }
+
+ROOT_AGENTS="$ROOT/.claude/agents"
+[[ -d "$ROOT_AGENTS" ]] || { fail "root .claude/agents missing at $ROOT_AGENTS"; exit 1; }
+
+# Every subdir .claude/ (excluding the root one) must expose an agents entry
+# that resolves to the same inode as the root agents/ directory.
+while IFS= read -r dir; do
+  [[ "$dir" == "$ROOT/.claude" ]] && continue
+  case "$dir" in
+    "$ROOT"/node_modules/*|*"/node_modules/"*) continue;;
+    "$ROOT"/noir/noir-repo/*) continue;;
+  esac
+  agents="$dir/agents"
+  if [[ ! -e "$agents" ]]; then
+    # Build the relative target (e.g. ../../.claude/agents) with POSIX tools
+    # so the hint is correct on macOS + Linux alike.
+    rel_root=${dir#$ROOT/}
+    depth=$(awk -F/ '{print NF}' <<<"$rel_root")
+    up=$(printf '../%.0s' $(seq 1 "$depth"))
+    fail "${dir#$ROOT/} has no agents/ — add symlink: (cd ${dir#$ROOT/} && ln -s ${up}.claude/agents agents)"
+    continue
+  fi
+  if [[ ! -L "$agents" ]]; then
+    fail "${dir#$ROOT/}/agents is not a symlink (must point at root .claude/agents/)"
+    continue
+  fi
+  # Resolve the symlink target and confirm it matches root agents.
+  resolved=$(cd "$(dirname "$agents")" && cd "$(readlink "$agents")" 2>/dev/null && pwd -P) || resolved=""
+  if [[ "$resolved" != "$ROOT_AGENTS" ]]; then
+    fail "${dir#$ROOT/}/agents resolves to $resolved, expected $ROOT_AGENTS"
+    continue
+  fi
+  pass "${dir#$ROOT/}/agents"
+done < <(find "$ROOT" -type d -name .claude -not -path "$ROOT/noir/*" -not -path "$ROOT/**/node_modules/*")
+
+echo
+if (( FAIL == 0 )); then
+  echo "${GREEN}All $CHECKED subdir .claude/ directories expose agents/ correctly.${NC}"
+  exit 0
+else
+  echo "${RED}$FAIL subdir .claude/ directories are missing or have broken agents symlinks.${NC}"
+  exit 1
+fi
diff --git a/.claude/tests/format_file_test b/.claude/tests/format_file_test
new file mode 100755
index 000000000000..687e3ad393a3
--- /dev/null
+++ b/.claude/tests/format_file_test
@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# Test suite for .claude/scripts/format-file.sh. Exercises every language
+# dispatch branch plus the TS fallback-install path. Mirrors ci3/tests/ style.
+set -uo pipefail
+
+# Resolve ROOT from the script's own location so the suite runs from any cwd.
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd -P)
+SCRIPT="$ROOT/.claude/scripts/format-file.sh"
+
+# Tests write temp files to /tmp which is outside the repo, so export
+# CLAUDE_PROJECT_DIR to give format-file.sh a known root without relying on
+# upward git walks from the edited file's directory.
+export CLAUDE_PROJECT_DIR="$ROOT"
+
+RED=$'\033[0;31m'
+GREEN=$'\033[0;32m'
+NC=$'\033[0m'
+
+PASS=0
+FAIL=0
+
+pass() { echo "${GREEN}✓${NC} $1"; ((PASS++)) || true; }
+fail() {
+  echo "${RED}✗${NC} $1"
+  [[ $# -ge 2 ]] && echo "  $2"
+  if [[ -s /tmp/format_test_stderr ]]; then
+    sed 's/^/    stderr: /' /tmp/format_test_stderr
+  fi
+  ((FAIL++)) || true
+}
+
+# run_hook <file>: invoke format-file.sh with a hook-shaped stdin payload.
+run_hook() {
+  local f=$1
+  printf '{"tool_input":{"file_path":"%s"}}' "$f" | "$SCRIPT" 2>/tmp/format_test_stderr
+}
+
+# expect_formatted <label> <file> <expected substring>
+expect_formatted() {
+  local label=$1 f=$2 expected=$3
+  run_hook "$f"
+  if grep -qF "$expected" "$f"; then
+    pass "$label"
+  else
+    fail "$label" "expected to find '$expected' in formatted output; got: $(cat "$f")"
+  fi
+}
+
+# expect_unchanged <label> <file> <exact content>
+expect_unchanged() {
+  local label=$1 f=$2 expected=$3
+  run_hook "$f"
+  if [[ "$(cat "$f")" == "$expected" ]]; then
+    pass "$label"
+  else
+    fail "$label" "expected unchanged; got: $(cat "$f")"
+  fi
+}
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+echo "=== format-file.sh test suite ==="
+
+# --- 1. Hook never fails the edit ---
+# One hygiene test defends the invariant "format-file.sh exits 0 on any malformed
+# input". Covers empty input, bad JSON, and missing files in one go.
+echo "--- 1. hook never fails the edit ---"
+
+for bad in '{"tool_input":{}}' '{"tool_input":{"file_path":"/nonexistent"}}' 'not json'; do
+  if printf '%s' "$bad" | "$SCRIPT" >/dev/null 2>&1; then :; else
+    fail "degenerate input: $bad"
+  fi
+done
+pass "hook exits 0 on empty/bad/missing input"
+
+# --- 2. C++ (clang-format 20) ---
+echo "--- 2. C++ ---"
+
+cat > "$TMP/a.cpp" <<'EOF'
+int  main( ){return 0;}
+EOF
+expect_formatted "C++ compacted declaration" "$TMP/a.cpp" "int main()"
+
+# --- 3. Rust ---
+echo "--- 3. Rust ---"
+
+cat > "$TMP/a.rs" <<'EOF'
+fn  main( ){let x=1;let y=2;println!("{}",x+y);}
+EOF
+run_hook "$TMP/a.rs"
+if grep -q 'let x = 1;' "$TMP/a.rs"; then
+  pass "Rust spacing fixed"
+else
+  fail "Rust" "output: $(cat "$TMP/a.rs")"
+fi
+
+# --- 4. Solidity ---
+echo "--- 4. Solidity ---"
+
+cat > "$TMP/A.sol" <<'EOF'
+pragma solidity ^0.8.0;
+contract A{function f() public pure returns(uint256){return 1;}}
+EOF
+run_hook "$TMP/A.sol"
+if grep -q 'contract A {' "$TMP/A.sol"; then
+  pass "Solidity brace spacing"
+else
+  fail "Solidity" "output: $(cat "$TMP/A.sol")"
+fi
+
+# --- 5. Noir (hint-only; nargo fmt is crate-scoped) ---
+echo "--- 5. Noir ---"
+
+cat > "$TMP/a.nr" <<'EOF'
+fn main() { let x = 1; }
+EOF
+before=$(cat "$TMP/a.nr")
+run_hook "$TMP/a.nr"
+after=$(cat "$TMP/a.nr")
+if [[ "$before" != "$after" ]]; then
+  fail "Noir file left unchanged" "file was modified: $after"
+elif ! grep -qF "nargo fmt" /tmp/format_test_stderr; then
+  fail "Noir hint" "expected 'nargo fmt' hint on stderr"
+else
+  pass "Noir file unchanged with nargo fmt hint"
+fi
+
+# --- 6. TypeScript (requires yarn-project bootstrap) ---
+# Skipped if yarn-project hasn't been installed; the hook's hint branch is
+# asserted by test 1 (hook never fails the edit). When prettier IS available,
+# verify the hook invokes it and the @trivago sort-imports plugin is active
+# so the yarn-project prettier config keeps working end-to-end.
+echo "--- 6. TypeScript + import sort plugin ---"
+
+REAL_PRETTIER="$ROOT/yarn-project/node_modules/.bin/prettier"
+if [[ ! -x "$REAL_PRETTIER" ]]; then
+  echo "  (skipped: $REAL_PRETTIER not present — bootstrap yarn-project to enable this test)"
+else
+  mkdir -p "$TMP/fake-yarn-project/foundation/src"
+  cp "$ROOT/yarn-project/foundation/.prettierrc.json" "$TMP/fake-yarn-project/foundation/.prettierrc.json"
+  cat > "$TMP/fake-yarn-project/foundation/src/mod.ts" <<'EOF'
+import { z } from 'zod';
+import { foo } from './local.js';
+import { Fr } from '@aztec/foundation/fields';
+
+const  x   = 1;
+EOF
+  run_hook "$TMP/fake-yarn-project/foundation/src/mod.ts"
+  out=$(cat "$TMP/fake-yarn-project/foundation/src/mod.ts")
+  if [[ "$out" != *"const x = 1;"* ]]; then
+    fail "TS basic formatting" "output: $out"
+  else
+    pass "TS basic formatting (whitespace normalized)"
+  fi
+  aztec_line=$(printf '%s\n' "$out" | grep -n '@aztec/foundation' | cut -d: -f1 || true)
+  zod_line=$(printf '%s\n' "$out" | grep -n "from 'zod'" | cut -d: -f1 || true)
+  local_line=$(printf '%s\n' "$out" | grep -n "from './local" | cut -d: -f1 || true)
+  if [[ -n "$aztec_line" && -n "$zod_line" && -n "$local_line" \
+        && "$aztec_line" -lt "$zod_line" && "$zod_line" -lt "$local_line" ]]; then
+    pass "TS import ordering (sort-imports plugin active)"
+  else
+    fail "TS import ordering" "aztec=$aztec_line zod=$zod_line local=$local_line"$'\n'"$out"
+  fi
+fi
+
+echo
+if (( FAIL == 0 )); then
+  echo "${GREEN}All $PASS tests passed.${NC}"
+  exit 0
+else
+  echo "${RED}$FAIL of $((PASS + FAIL)) tests failed.${NC}"
+  exit 1
+fi
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000000..f9682bfe2534
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,112 @@
+# aztec-packages
+
+All paths below are relative to the git root. When working inside a component, also read that component's `CLAUDE.md` — each is self-contained and covers its own build, style, and test conventions.
+
+<components>
+`yarn-project/` is the TypeScript monorepo containing the node, client SDK (`aztec.js`), PXE/wallet, sequencer, prover, p2p stack, and tooling — the main entrypoint for most day-to-day work; see `yarn-project/CLAUDE.md`.
+
+`barretenberg/` is the C++ ZK proving system (Honk, Chonk, ECCVM); see `barretenberg/CLAUDE.md` and `barretenberg/cpp/CLAUDE.md`. `barretenberg/cpp/src/barretenberg/vm2/` is the AVM (Aztec Virtual Machine) for public execution; see its `CLAUDE.md`. `barretenberg/sol/` is the Solidity on-chain verifier; see `barretenberg/sol/CLAUDE.md`. `barretenberg/ts/` contains the TypeScript bindings for barretenberg (bb.js).
+
+`avm-transpiler/` transpiles Noir bytecode to AVM bytecode (Rust). `noir/` is the Noir compiler, a git submodule pointing to noir-lang/noir. `noir-projects/` holds the protocol circuits and contract libraries written in Noir; see `noir-projects/aztec-nr/CLAUDE.md`.
+
+`l1-contracts/` holds the Solidity L1 rollup contracts (a Foundry project). `docs/` is the developer documentation site (Docusaurus); see `docs/CLAUDE.md`. `spartan/` holds Kubernetes deployment infrastructure (Helm charts + Terraform); see `spartan/CLAUDE.md`. `bb-pilcom/` is the PIL compiler for AVM relation codegen. `ci3/` contains CI infrastructure scripts.
+</components>
+
+<build_system>
+Dependencies flow barretenberg → noir → l1-contracts → yarn-project. From the git root, use `make <target>`: `make fast` builds everything needed for development, `make yarn-project` runs the full TS build chain (which builds bb, noir, and l1-contracts first), `make bb-cpp-native` builds barretenberg C++ native only, `make noir` builds the Noir compiler, and `make l1-contracts` builds the Solidity contracts via Foundry. For individual components, run `./bootstrap.sh` inside each directory.
+
+When a change spans multiple components, rebuild in dependency order: first `barretenberg/cpp/` with `cmake --preset default && cd build && ninja`, then `barretenberg/ts/` with `./bootstrap.sh` (which generates TS bindings from C++), then `noir/` with `./bootstrap.sh` if noir changes are needed, then `noir-projects/` to compile contracts, then `l1-contracts/` with `forge build`, and finally `yarn-project/` with `yarn build` from inside `yarn-project/` (not the git root).
+
+The noir-projects build scripts default `$NARGO` to `noir/noir-repo/target/release/nargo`. Do not override this with a globally installed nargo — version mismatches produce opaque bytecode failures in downstream components.
+</build_system>
+
+<git_workflow>
+
+<critical_never_assume_master>
+Never assume the base branch is `master` or `main`. Most branches target `next` or a `merge-train/*` branch, and defaulting to `master` produces incorrect diffs and broken PR comparisons. Determine the actual base before diffing or opening a PR.
+
+If a PR is already open, that is authoritative:
+
+```bash
+gh pr view --json baseRefName -q '.baseRefName'
+```
+
+Otherwise infer from the component being worked in:
+
+| Component | Base branch |
+|---|---|
+| `barretenberg/**` | `merge-train/barretenberg` |
+| `yarn-project/**` | `merge-train/spartan` |
+| `barretenberg/cpp/src/barretenberg/vm2/**` | `merge-train/avm` |
+| everything else | `next` |
+
+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>
+
+<commits_and_prs>
+Follow Conventional Commits: `fix:`, `feat:`, `chore:`, `refactor:`, `docs:`, `test:`. PRs are squashed to a single commit on merge, so during development just create normal commits — do not amend unless explicitly asked. If `noir/noir-repo` shows as modified unexpectedly, run `git submodule update noir/noir-repo` to reset it.
+</commits_and_prs>
+
+<git_staging>
+When staging files, prefer `git add -u` or name specific files rather than `git add -A` or `git add .`. The aggregate flags will pick up unrelated untracked working directories (e.g. personal scratch projects at the repo root) and quietly stage them. Subagents must always name specific files in `git add` — never `-u`, `-A`, or `.` — because they lack the main conversation's context for judging which changes belong to the current task.
+</git_staging>
+
+<lockfile_discipline>
+Never bulk-update lockfiles (`Cargo.lock`, `yarn.lock`). Use targeted updates only: `cargo update --precise <version> --package <name>` for Rust, and `yarn up <package>@<version>` in the relevant workspace for TypeScript. Bulk updates drag in unrelated transitive changes that make review impossible and frequently break reproducibility.
+</lockfile_discipline>
+
+</git_workflow>
+
+<code_formatting>
+Each language's formatter is documented in the relevant subdir `CLAUDE.md` — C++ conventions live in `barretenberg/cpp/CLAUDE.md`, TypeScript in `yarn-project/CLAUDE.md`, and Noir in `noir-projects/aztec-nr/CLAUDE.md`. A post-edit hook runs the appropriate formatter automatically, so there is normally no need to invoke one by hand.
+</code_formatting>
+
+<red_green_testing>
+When fixing a bug, CI failure, or regression, follow red/green. First, write or run a test that demonstrates the failure and show that it fails — this proves both the problem is understood and that there is a reliable way to detect it. Then make the fix and rerun the same test to show it passes. The same pattern applies to refactors: run existing tests to establish a baseline before changing code. If a failing test is not feasible (non-deterministic behavior, infra not available locally, etc.), say so explicitly rather than skipping the step silently.
+</red_green_testing>
+
+<test_failure_skepticism>
+When a test fails, assume your changes caused it until proven otherwise. Pre-existing test failures are rare in this repo; the default hypothesis is that the current change introduced the regression, not that the test was already broken. Investigate the failure against your diff before concluding it is unrelated.
+</test_failure_skepticism>
+
+<unexpected_file_changes>
+If a file contains changes you did not make (e.g. formatting diffs, new imports, reorganized code), assume a post-edit hook, the user, or another agent made them deliberately. Do not revert, "clean up," or overwrite those changes. If the changes conflict with your work, ask the user rather than silently discarding them.
+</unexpected_file_changes>
+
+<test_behavior_not_mocks>
+Tests should validate behavior, not mock call-count. Prefer `expect(result).toEqual(...)` over `expect(spy).toHaveBeenCalledWith(...)` unless call-count is literally the behavior under test. Mock-counting tests pin the implementation and make every unrelated refactor look like a regression.
+</test_behavior_not_mocks>
+
+<reuse_before_writing>
+Before writing a new helper, utility, or component, search for an existing one with Grep or Glob. Reuse or refactor to a shared module; do not introduce a parallel implementation.
+</reuse_before_writing>
+
+<preserve_todos>
+Preserve existing `// TODO`, `// TODO(name)`, and `// NOTE:` comments unless the current task is to resolve them. A "tidy up" refactor that deletes another author's deferred-work markers destroys context that is not recoverable from git history.
+</preserve_todos>
+
+<bash_hygiene>
+Never append `; echo "EXIT: $?"` or similar exit-code suffixes to any command. The Bash tool already reports exit codes directly; adding these suffixes is redundant and causes unnecessary permission prompts.
+</bash_hygiene>
+
+<do_not_edit>
+Never edit vendored submodules (all paths listed in `.gitmodules`) or files that contain a `DO NOT EDIT` / `generated` header. Edit the upstream source or the generator input and regenerate. CI enforces this — hand edits to generated files will be overwritten or rejected.
+</do_not_edit>
+
+<editorial_test>
+Before adding a line to any `CLAUDE.md` file: answer in one sentence what specific wrong action the line would have prevented in a past session. If no such action exists, do not add the line. General knowledge, motivation, and historical rationale do not qualify — those belong in commit messages or subdirectory READMEs. This rule applies equally to every `CLAUDE.md` in the tree.
+</editorial_test>
+
+<writing_comments>
+Default to writing no inline comments. Add one only when the *why* is non-obvious: a hidden constraint, a subtle invariant, a workaround for a specific bug, or behavior that would surprise a reader. If removing the comment would not confuse a future reader, do not write it. 
+
+Do write jsdoc, rustdoc, or natspec comments for documenting public methods.
+
+Do not explain *what* the code does — well-named identifiers cover that. Comments of the form `// increment counter` / `// loop over peers` / `// return early on error` are noise and should be deleted rather than added.
+
+Do not reference the current task, PR, caller, or author (`// used by X`, `// fix for issue #123`, `// AI-generated`), and do not add banner-style section comments (`// ===== HELPERS =====`). Both rot the moment the surrounding code is moved.
+</writing_comments>
+
+<attribution>
+Attribute work to the git author, not to Claude. Do not add `Co-Authored-By: Claude` trailers or `Generated with Claude Code` in PR descriptions. The git author (from `git config user.name`) is the author of record.
+</attribution>
diff --git a/Makefile b/Makefile
index d0d5824ca76c..965aca159722 100644
--- a/Makefile
+++ b/Makefile
@@ -55,7 +55,7 @@ endef
 
 # Fast bootstrap.
 fast: release-image barretenberg boxes playground docs aztec-up \
-		  bb-tests l1-contracts-tests yarn-project-tests boxes-tests playground-tests aztec-up-tests docs-tests noir-protocol-circuits-tests release-image-tests spartan
+		  bb-tests l1-contracts-tests yarn-project-tests boxes-tests playground-tests aztec-up-tests docs-tests noir-protocol-circuits-tests release-image-tests spartan claude-tests
 
 # Full bootstrap.
 full: fast bb-full-tests bb-cpp-full yarn-project-benches
@@ -269,6 +269,14 @@ bb-tests: bb-cpp-native-tests bb-acir-tests bb-ts-tests bb-sol-tests bb-bbup-tes
 
 bb-full-tests: bb-cpp-wasm-threads-tests bb-cpp-asan-tests bb-cpp-smt-tests
 
+#==============================================================================
+# .claude tooling
+#==============================================================================
+
+.PHONY: claude-tests
+claude-tests:
+	$(call test,$@,.claude)
+
 #==============================================================================
 # Noir Projects
 #==============================================================================
diff --git a/avm-transpiler/CLAUDE.md b/avm-transpiler/CLAUDE.md
new file mode 100644
index 000000000000..b8a2551dcde2
--- /dev/null
+++ b/avm-transpiler/CLAUDE.md
@@ -0,0 +1,20 @@
+# avm-transpiler
+
+## Build
+
+```bash
+./bootstrap.sh            # full build
+./bootstrap.sh build_native
+./bootstrap.sh build_cross <target>   # e.g. arm64-linux, amd64-macos
+```
+
+Do not override the toolchain (`cargo +nightly`, `rustup override`); `rust-toolchain.toml` pins it and CI will reject anything else.
+
+## Downstream rebuilds
+
+Outputs are consumed by `barretenberg/cpp/` (via the `avm_transpiler.h` header) and `yarn-project/` (via the built static library). After non-trivial changes, rebuild both or cross-component breakage will surface only in unrelated CI steps:
+
+```bash
+(cd ../barretenberg/cpp && cmake --preset default && cd build && ninja)
+(cd ../yarn-project && yarn build)
+```
diff --git a/barretenberg/CLAUDE.md b/barretenberg/CLAUDE.md
index bae8bdc0fe5b..5c6da832e4be 100644
--- a/barretenberg/CLAUDE.md
+++ b/barretenberg/CLAUDE.md
@@ -2,7 +2,7 @@ THE PROJECT ROOT IS AT ONE LEVEL ABOVE THIS FOLDER. Typically, the repository is
 
 # Git workflow for barretenberg
 
-**IMPORTANT**: When comparing branches or looking at diffs for barretenberg work, use `origin/merge-train/barretenberg` as the base branch, NOT `master` or `next`. Create new branches off `origin/merge-train/barretenberg` and target PRs to `merge-train/barretenberg`.
+Base branch is `merge-train/barretenberg`; see root `CLAUDE.md` under `<git_workflow>` for the full component→base mapping. The sections below are barretenberg-specific workflow commands.
 
 ## Creating a new branch
 
@@ -31,8 +31,6 @@ git push -f  # Force push after rebase (only when necessary)
 - `git log origin/merge-train/barretenberg..HEAD` (not `git log master..HEAD`)
 - `gh pr create --base merge-train/barretenberg` (target PRs to merge-train)
 
-**Do NOT include `Co-Authored-By: Claude` lines in commit messages or `Generated with Claude Code` in PR descriptions.**
-
 Barretenberg issues are tracked at `AztecProtocol/barretenberg` (separate repo), not `AztecProtocol/aztec-packages`. PRs go to `AztecProtocol/aztec-packages` but should reference issues from `AztecProtocol/barretenberg`.
 
 Run ./bootstrap.sh at the top-level to be sure the repo fully builds.
diff --git a/barretenberg/cpp/CLAUDE.md b/barretenberg/cpp/CLAUDE.md
index 8f962e6c61ac..b2b1dfeb8f8c 100644
--- a/barretenberg/cpp/CLAUDE.md
+++ b/barretenberg/cpp/CLAUDE.md
@@ -1,7 +1,5 @@
 # barretenberg/cpp
 
-The core proving system library.
-
 Bootstrap modes:
 
 - `./bootstrap.sh` => full build, needed for other components
@@ -64,6 +62,15 @@ All C++ files must be formatted with clang-format before committing:
 clang-format-20 -i <files>
 ```
 
+## C++ invariants
+
+These are load-bearing: violating them will compile on native but break WASM, or skew test output in CI. Use the listed alternative unconditionally.
+
+- **Logging: use `info(...)` / `vinfo(...)` from `barretenberg/common/log.hpp`, never `std::cout` or `std::cerr`.** The macros route through `log_function` and respect `bb_log_level`; direct `std::cout` is unfiltered, uncaptured in CI logs, and skews benchmark output.
+- **Aborts and exceptions: use `throw_or_abort(msg)` from `barretenberg/common/throw_or_abort.hpp`, never bare `throw` or `std::abort()`.** WASM builds set `BB_NO_EXCEPTIONS`, which turns `throw` into `abort()` — bare `throw` compiles differently and misformats the message, and raw `std::abort()` drops the message entirely. For header-only libraries that must use exception syntax, use the `THROW`/`RETHROW` macros from `common/try_catch_shim.hpp`.
+- **Assertions: use `BB_ASSERT(cond, msg)` / `BB_ASSERT_EQ` / `BB_ASSERT_NEQ` / `BB_ASSERT_GT` / etc. from `barretenberg/common/assert.hpp`, never bare `assert(...)`.** `BB_ASSERT` hooks into the benchmark-assertion framework and has distinct debug/release behavior; `assert` is stripped in release builds and silently diverges in WASM.
+- **Release builds: do not reach for the `release` CMake preset unless the user is reproducing a performance issue.** Debug/default presets are much faster to compile and sufficient for correctness work.
+
 ## Benchmarking:
 
 **IMPORTANT**: In the barretenberg context, "bench" or "benchmark" almost always means running `benchmark_remote.sh` for the given target on a remote benchmarking machine.
diff --git a/docs/.claude/agents b/docs/.claude/agents
new file mode 120000
index 000000000000..4d454cf5147d
--- /dev/null
+++ b/docs/.claude/agents
@@ -0,0 +1 @@
+../../.claude/agents
\ No newline at end of file
diff --git a/yarn-project/.claude/rules/bash-no-echo-exit.md b/yarn-project/.claude/rules/bash-no-echo-exit.md
deleted file mode 100644
index cbe045dd4189..000000000000
--- a/yarn-project/.claude/rules/bash-no-echo-exit.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Bash Command Rules
-
-**NEVER append `; echo "EXIT: $?"` or similar exit-code suffixes to any command.** The Bash tool already reports exit codes directly. Adding these suffixes is redundant and causes unnecessary permission prompts.
-
-Bad:
-```bash
-yarn test src/file.test.ts > /tmp/out.log 2>&1; echo "EXIT: $?"
-```
-
-Good:
-```bash
-yarn test src/file.test.ts > /tmp/out.log 2>&1
-```
diff --git a/yarn-project/.claude/rules/ci-config.md b/yarn-project/.claude/rules/ci-config.md
deleted file mode 100644
index df24ad535c9b..000000000000
--- a/yarn-project/.claude/rules/ci-config.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# CI Configuration
-
-## Marking Tests as Flaky
-
-When a test intermittently fails but shouldn't block CI:
-
-1. Edit `.test_patterns.yml` (at git root, not in yarn-project)
-2. Add entry under `tests:` section:
-
-```yaml
-- regex: "src/e2e_new_feature/feature.test.ts"
-  error_regex: "specific error message"  # Optional: only flag if this error occurs
-  owners:
-    - *charlie  # Reference existing name
-    - *adam     # Can have multiple owners
-```
-
-### Adding a New Owner
-
-1. Add to `names:` section: `- newperson: &newperson "SLACK_ID"`
-2. Reference in test: `- *newperson`
-
-### Behavior
-
-- Without `error_regex`: Test is always flagged as flaky when it fails
-- With `error_regex`: Only flagged when output matches the regex
-- `skip: true`: Test won't run at all (avoid unless constantly failing)
-- Flaky tests alert owners in #aztec3-ci Slack channel but don't fail CI
diff --git a/yarn-project/.claude/rules/typescript-style.md b/yarn-project/.claude/rules/typescript-style.md
deleted file mode 100644
index 0990cc1f0c00..000000000000
--- a/yarn-project/.claude/rules/typescript-style.md
+++ /dev/null
@@ -1,349 +0,0 @@
----
-globs: "*.ts,*.tsx,*.mts,*.cts"
----
-
-# TypeScript Code Style
-
-## Type Safety
-
-- Avoid `as Type` casts; prefer type guards
-- Never use `as any`; if a subclass need access to private members, change the visibility to `protected` instead of doing `this as any`
-- Use branded types for common domain types (`SlotNumber`, `BlockNumber`, `EpochNumber`, etc.)
-- Type guard functions follow `is<TypeName>` naming convention:
-  ```typescript
-  function isRevertCodeEnum(value: number): value is RevertCodeEnum { ... }
-  ```
-
-## Data Structures
-
-**Plain types ("structs")** for simple local data with free functions + schema in same file:
-```typescript
-// Example: archiver/src/archiver/structs/inbox_message.ts
-export type InboxMessage = {
-  index: bigint;
-  leaf: Fr;
-  checkpointNumber: CheckpointNumber;
-};
-
-export function serializeInboxMessage(message: InboxMessage): Buffer { ... }
-export function deserializeInboxMessage(buffer: Buffer): InboxMessage { ... }
-```
-
-**Classes** for richer structs with serialization, factory, and utility methods:
-```typescript
-// Example: stdlib/src/tx/block_header.ts
-export class BlockHeader {
-  constructor(public readonly lastArchive: AppendOnlyTreeSnapshot, ...) {}
-
-  static get schema(): ZodFor<BlockHeader> { ... }
-  static from(fields: FieldsOf<BlockHeader>) { ... }
-  static fromBuffer(buffer: Buffer): BlockHeader { ... }
-  static empty(): BlockHeader { ... }
-  static random(): BlockHeader { ... }
-
-  toBuffer(): Buffer { ... }
-  hash(): Promise<Fr> { ... }
-}
-```
-
-Avoid classes with only static methods; use free functions instead.
-
-## Factory Patterns
-
-For classes, use these static factory methods:
-- `from(FieldsOf<T>)` - synchronous construction from plain object
-- `create()` - async construction when validation is needed
-- `fromBuffer()` / `fromString()` - deserialization
-- `empty()` / `random()` - testing helpers
-
-## Schema Patterns (Zod)
-
-Use Zod for validating untrusted input. For classes, define a static schema getter:
-
-```typescript
-static get schema(): ZodFor<BlockHeader> {
-  return z
-    .object({
-      lastArchive: AppendOnlyTreeSnapshot.schema,
-      state: StateReference.schema,
-      // ...
-    })
-    .transform(BlockHeader.from);
-}
-```
-
-Use `zodFor<T>()` helper for type-safe schema definitions on plain types.
-
-## Interfaces
-
-Use interfaces only when:
-- Multiple implementations exist
-- Exposing APIs to the outside world
-- Need to depend on a type without creating a runtime dependency
-
-## Error Handling
-
-- Custom errors extend `Error` and set `this.name`
-- Use error hierarchies with base classes for domains
-- Include `public readonly` properties for error context
-
-```typescript
-export class SequencerTooSlowError extends Error {
-  constructor(
-    public readonly proposedState: SequencerState,
-    public readonly maxAllowedTime: number,
-  ) {
-    super(`Too far into slot for ${proposedState}...`);
-    this.name = 'SequencerTooSlowError';
-  }
-}
-```
-
-## Class Style
-
-- Be explicit with `private`/`public`/`protected`
-- Use `readonly` whenever possible
-- Method organization:
-  1. Static properties/constants
-  2. Instance properties
-  3. Constructor
-  4. Static factory methods (`from`, `create`, `empty`, `random`)
-  5. Lifecycle methods (`start`, `stop`)
-  6. Public API methods
-  7. Protected methods
-  8. Private methods
-
-## JSDoc Comments
-
-Document all classes, types, and interfaces with a JSDoc comment explaining their purpose. Include usage context when relevant (e.g., "Used by the sequencer to track pending transactions").
-
-Document methods and properties unless meaning is obvious from the name. Skip JSDoc for:
-- Trivial getters/setters (`get length()`, `set value()`)
-- Constructor-injected dependencies (`private readonly db: Database`)
-- Standard lifecycle methods (`start`, `stop`)
-
-Interface methods always require JSDoc—interfaces define contracts, and consumers need clear documentation.
-
-Use `@param` and `@returns` only when parameter names or return types don't convey meaning. Prefer descriptive names over annotations.
-
-Keep comments concise. Use single-line format when possible:
-
-```typescript
-/** Computes the Merkle root of pending note hashes. */
-computeRoot(): Fr { ... }
-
-/** Maximum number of transactions per block. */
-private readonly maxTxsPerBlock: number;
-```
-
-Multi-line only when explanation requires it:
-
-```typescript
-/**
- * Validates a transaction against current world state.
- * Checks nullifier non-existence and note hash membership.
- */
-async validate(tx: Tx): Promise<boolean> { ... }
-```
-
-Avoid redundant "title" lines that repeat the name being documented:
-
-```typescript
-// BAD: Repeats class name as a title
-/**
- * CheckpointProposal
- *
- * A checkpoint proposal is created by the leader...
- */
-export class CheckpointProposal { ... }
-
-// GOOD: Directly explains purpose
-/** Created by the checkpoint leader to collect validator attestations. */
-export class CheckpointProposal { ... }
-```
-
-## Enums vs Union Types
-
-- **Numeric enums** for protocol constants that serialize to numbers
-- **String enums** for status values and event names
-- **`as const` arrays** with derived type for string literal unions:
-  ```typescript
-  const GasDimensions = ['da', 'l2'] as const;
-  type GasDimensions = (typeof GasDimensions)[number];
-  ```
-- **Discriminated unions** with `type` field for variant types
-
-## Optional vs Nullable
-
-- Prefer `undefined` over `null`
-- Use `compactArray()` from foundation to filter undefined values
-
-## Resource Management
-
-Prefer `using`/`await using` over `try`/`finally` for cleanup of disposable resources:
-
-```typescript
-// Good: using statement ensures cleanup even on exceptions
-using fork = await this.worldState.fork(blockNumber);
-const result = await processWithFork(fork);
-return result;
-
-// Bad: try/finally is more verbose and error-prone
-const fork = await this.worldState.fork(blockNumber);
-try {
-  const result = await processWithFork(fork);
-  return result;
-} finally {
-  await fork.close();
-}
-```
-
-- Use `using` for `Disposable` resources (implements `[Symbol.dispose](): void`)
-- Use `await using` for `AsyncDisposable` resources (implements `[Symbol.asyncDispose](): Promise<void>`)
-- When the resource is obtained asynchronously but disposed synchronously, use `using x = await getResource()`
-
-## KV Store Transactions
-
-When working with `AztecAsyncKVStore`, wrap related reads and writes in `store.transactionAsync()` to ensure atomicity:
-
-```typescript
-// Good: All reads and writes in a single transaction
-public async tryAdd(item: Item): Promise<boolean> {
-  return await this.store.transactionAsync(async () => {
-    const exists = await this.items.hasAsync(item.id);
-    if (exists) {
-      return false;
-    }
-    await this.items.set(item.id, item.toBuffer());
-    return true;
-  });
-}
-
-// Bad: Race condition - reads outside transaction, write inside
-public async tryAdd(item: Item): Promise<boolean> {
-  const exists = await this.items.hasAsync(item.id);  // Read outside transaction
-  if (exists) {
-    return false;
-  }
-  await this.store.transactionAsync(async () => {
-    await this.items.set(item.id, item.toBuffer());  // Write inside transaction
-  });
-  return true;
-}
-```
-
-Without transactions, concurrent operations can see inconsistent state (e.g., two callers both pass the `exists` check and both write).
-
-## General Style
-
-- Prefer `const` over `let`
-- Prefer `async`/`await` over `.then()`/`.catch()` callbacks
-- Named exports only (no default exports)
-- Explicit return types on public API methods; inferred types acceptable on private/internal methods
-- Only export types that are needed by external consumers; keep internal option types private
-- Avoid `const self = this`; use arrow functions to preserve `this` context instead
-
-## Collections
-
-- Prefer high-level collection functions (`find`, `filter`, `map`, and other helpers from `foundation/src/collection/`) over imperative loops, but prefer imperative loops over `forEach` and complex `reduce`
-- Prefer `sum(items.map(item => item.value))` over `reduce((acc, items) => acc + items.value, 0)` for addition
-
-
-## Code Duplication
-
-Avoid duplicating logic unless clarity benefits from keeping it inline. When extracting:
-
-- **Same class**: Extract to a `private` helper method
-- **Same package, multiple files**: Extract to a free function in a dedicated helper file
-- **Complex logic spanning multiple concerns**: Extract to a dedicated class
-
-**For two classes with similar behavior:**
-- If public APIs are nearly identical: use **inheritance** (extend a common base class)
-- If behavior overlaps but APIs differ: use **composition** (inject shared logic as a dependency)
-
-## Foundation Utilities
-
-- Check `foundation` for existing utilities before reimplementing
-- Extract general (non-domain) utilities to `foundation`
-
-## Using `Set`/`Map`
-
-Avoid `Set`/`Map` of non-primitive class instances; this leads to errors with `has()` checks. Use primitive keys (strings, numbers) instead.
-
-## Logging
-
-- Be generous with logging, but not excessive
-- Include structured context objects
-- Use appropriate log levels: `trace`, `debug`, `verbose`, `info`, `warn`, `error`
-
-```typescript
-this.log.info(`Preparing checkpoint ${checkpointNumber}`, {
-  slot,
-  checkpointNumber,
-  proposer,
-});
-```
-
-## Import Organization
-
-Order imports as follows:
-1. External `@aztec/*` packages
-2. Foundation utilities (`@aztec/foundation/*`)
-3. Protocol-specific packages
-4. Node.js built-ins (`node:events`, `node:fs`)
-5. Third-party packages (`viem`, `zod`)
-6. Relative imports (with `.js` extension)
-
-Use `import type` for type-only imports.
-
-## Event Handling
-
-Use `TypedEventEmitter<TEventMap>` interface for typed events:
-
-```typescript
-type SequencerEvents = {
-  ['state-changed']: (args: { oldState: SequencerState; newState: SequencerState }) => void;
-  ['block-proposed']: (args: { blockNumber: BlockNumber }) => void;
-};
-
-export class Sequencer extends (EventEmitter as new () => TypedEventEmitter<SequencerEvents>) {
-  // ...
-}
-```
-
-## Function Arguments
-
-Simplify function arguments to single expressions where possible:
-
-```typescript
-// Good: Single expression
-mock.getData.mockImplementation((id: string) =>
-  Promise.resolve(items.find(item => item.id === id)),
-);
-
-// Bad: Unnecessary block with loop
-mock.getData.mockImplementation((id: string) => {
-  for (const item of items) {
-    if (item.id === id) {
-      return Promise.resolve(item);
-    }
-  }
-  return Promise.resolve(undefined);
-});
-```
-
-## Arrow Function Bodies
-
-Use expression bodies instead of block bodies when the block only contains a `return`:
-
-```typescript
-// Good: Expression body
-items.map(item => item.value * 2)
-fn(arg => expression(arg, foo))
-
-// Bad: Block body with just a return
-items.map(item => { return item.value * 2; })
-fn(arg => { return expression(arg, foo); })
-```
-
-Block bodies are appropriate when the callback has multiple statements or side effects beyond the return.
\ No newline at end of file
diff --git a/yarn-project/.claude/settings.json b/yarn-project/.claude/settings.json
index fc26d22c335d..eeef0c69885b 100644
--- a/yarn-project/.claude/settings.json
+++ b/yarn-project/.claude/settings.json
@@ -2,11 +2,11 @@
   "hooks": {
     "PostToolUse": [
       {
-        "matcher": "Edit|Write",
+        "matcher": "Edit|Write|MultiEdit",
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path\"); if [[ \"$FILE\" =~ \\.(ts|js|mjs|cjs|json)$ ]]; then \"$CLAUDE_PROJECT_DIR/node_modules/.bin/prettier\" --write \"$FILE\" 2>/dev/null; fi'"
+            "command": "bash -c 'GITROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; [ -n \"$GITROOT\" ] && exec \"$GITROOT/.claude/scripts/format-file.sh\"; exit 0'"
           }
         ]
       }
diff --git a/yarn-project/CLAUDE.md b/yarn-project/CLAUDE.md
index db8e14659e89..070a5398537a 100644
--- a/yarn-project/CLAUDE.md
+++ b/yarn-project/CLAUDE.md
@@ -149,6 +149,98 @@ yarn lint <pkg1>                        # Single package (faster)
 
 ```
 
+<typescript_style>
+
+<type_safety>
+Avoid `as Type` casts; prefer type guards. Never use `as any`; if a subclass needs access to private members, change visibility to `protected`. Use branded types for common domain types (`SlotNumber`, `BlockNumber`, `EpochNumber`). Type guard functions follow `is<TypeName>` naming.
+</type_safety>
+
+<type_colocation>
+Colocate type definitions with the code that uses them. Do not create new `types.ts` files unless a circular-dependency issue forces it. When adding a type used by exactly one function, declare it next to that function; when adding a type used by one class, declare it above the class. Extract to a package-level module only when at least three unrelated files need the same type.
+</type_colocation>
+
+<data_structures>
+**Plain types** for simple local data with free functions + schema in same file. **Classes** for richer structs with serialization, factory, and utility methods. Avoid classes with only static methods; use free functions instead.
+
+For classes, use these static factory methods: `from(FieldsOf<T>)` for synchronous construction, `create()` for async with validation, `fromBuffer()` / `fromString()` for deserialization, `empty()` / `random()` for testing helpers.
+
+Use Zod for validating untrusted input. For classes, define a static `schema` getter. Use `zodFor<T>()` helper for type-safe schema definitions on plain types.
+
+Use interfaces only when multiple implementations exist, exposing APIs to outside consumers, or needing to depend on a type without creating a runtime dependency.
+</data_structures>
+
+<error_handling>
+Custom errors extend `Error` and set `this.name`. Use error hierarchies with base classes for domains. Include `public readonly` properties for error context.
+</error_handling>
+
+<class_style>
+Be explicit with `private`/`public`/`protected`. Use `readonly` whenever possible. Method organization: static properties/constants → instance properties → constructor → static factory methods (`from`, `create`, `empty`, `random`) → lifecycle (`start`, `stop`) → public API → protected → private.
+</class_style>
+
+<jsdoc>
+Document all classes, types, and interfaces with a JSDoc comment explaining their purpose. Document methods and properties unless meaning is obvious from the name. Skip JSDoc for trivial getters/setters, constructor-injected dependencies, and standard lifecycle methods (`start`, `stop`). Interface methods always require JSDoc.
+
+Use `@param` and `@returns` only when parameter names or return types don't convey meaning. Keep comments concise — single-line format when possible. Avoid redundant "title" lines that repeat the name being documented.
+</jsdoc>
+
+<enums_and_unions>
+Numeric enums for protocol constants that serialize to numbers. String enums for status values and event names. `as const` arrays with derived type for string literal unions. Discriminated unions with `type` field for variant types. Prefer `undefined` over `null`; use `compactArray()` from foundation to filter undefined values.
+</enums_and_unions>
+
+<resource_management>
+Prefer `using`/`await using` over `try`/`finally` for cleanup of disposable resources. Use `using` for `Disposable` resources (`[Symbol.dispose](): void`), `await using` for `AsyncDisposable` resources (`[Symbol.asyncDispose](): Promise<void>`).
+</resource_management>
+
+<kv_store_transactions>
+When working with `AztecAsyncKVStore`, wrap related reads and writes in `store.transactionAsync()` to ensure atomicity. Without transactions, concurrent operations can see inconsistent state (e.g., two callers both pass an `exists` check and both write).
+</kv_store_transactions>
+
+<general_style>
+Prefer `const` over `let`. Prefer `async`/`await` over `.then()`/`.catch()` callbacks. Named exports only (no default exports). Explicit return types on public API methods; inferred types acceptable on private/internal methods. Only export types needed by external consumers. Avoid `const self = this`; use arrow functions.
+
+Prefer high-level collection functions (`find`, `filter`, `map`, helpers from `foundation/src/collection/`) over imperative loops, but prefer imperative loops over `forEach` and complex `reduce`. Prefer `sum(items.map(item => item.value))` over `reduce(...)` for addition.
+
+Simplify function arguments to single expressions where possible. Use expression bodies instead of block bodies when the block only contains a `return`. Block bodies are appropriate when the callback has multiple statements.
+</general_style>
+
+<code_duplication>
+Avoid duplicating logic unless clarity benefits from keeping it inline. Same class → `private` helper. Same package → free function in a dedicated helper file. Complex logic → dedicated class. For two classes with similar behavior: if public APIs are nearly identical, use inheritance; if behavior overlaps but APIs differ, use composition.
+
+Check `foundation` for existing utilities before reimplementing. Extract general (non-domain) utilities to `foundation`.
+</code_duplication>
+
+<collections_and_maps>
+Avoid `Set`/`Map` of non-primitive class instances; `has()` checks fail because objects are compared by reference. Use primitive keys (strings, numbers) instead.
+</collections_and_maps>
+
+<logging>
+Always pass a structured context object as the second argument to log calls — not interpolated strings. The log pipeline indexes on these fields for filtering in production.
+
+```typescript
+// correct
+this.log.info(`Preparing checkpoint ${checkpointNumber}`, { slot, checkpointNumber, proposer });
+
+// wrong — context is lost to the log pipeline
+this.log.info(`Preparing checkpoint ${checkpointNumber} for slot ${slot} by ${proposer}`);
+```
+
+Available levels in order: `trace`, `debug`, `verbose`, `info`, `warn`, `error`.
+</logging>
+
+<import_organization>
+Order imports: external `@aztec/*` packages → foundation utilities (`@aztec/foundation/*`) → protocol-specific packages → Node.js built-ins (`node:events`, `node:fs`) → third-party packages (`viem`, `zod`) → relative imports (with `.js` extension). Use `import type` for type-only imports.
+</import_organization>
+
+<event_handling>
+Use `TypedEventEmitter<TEventMap>` interface for typed events.
+</event_handling>
+
+</typescript_style>
+
+<ci_config>
+When a test intermittently fails but shouldn't block CI, edit `.test_patterns.yml` (at the git root, not in yarn-project) and add an entry under `tests:`. Without `error_regex`, the test is always flagged as flaky when it fails. With `error_regex`, only flagged when output matches. `skip: true` disables the test entirely (avoid unless constantly failing). Flaky tests alert owners in #aztec3-ci Slack but don't fail CI.
+</ci_config>
+
 ## Dependency Management
 
 After modifying any `package.json`:
@@ -157,6 +249,8 @@ After modifying any `package.json`:
 yarn && yarn prepare
 ```
 
+`yarn prepare` regenerates the `references` array in every workspace `tsconfig.json` from the `dependencies` field via `@monorepo-utils/workspaces-to-typescript-project-references`. Never hand-edit the `references` array — the next `yarn prepare` will overwrite any manual changes, and forgetting to run it leaves `tsc -b` incremental builds in an inconsistent state.
+
 ## Key Packages
 
 ### Server (Node)
@@ -208,38 +302,7 @@ ab/feature-name
 jd/fix-something
 ```
 
-### Commit Messages
-
-Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
-
-**Supported types**: `fix`, `feat`, `chore`, `refactor`, `docs`, `test`
-
-```
-<type>(<scope>): <description>
-
-[optional body]
-```
-
-### Branch Strategy
-
-- **Primary development**: `next` branch (default PR target)
-- **Production**: `master` branch
-- **Merge trains**: Some teams use `merge-train/*` branches (e.g., `merge-train/barretenberg`, `merge-train/spartan`) to batch PRs before merging into `next`. If the current branch targets a `merge-train/*` branch, use that as the base -- not `next`. See the `merge-trains` skill for details.
-- **Backport**: Fix in release branch -> forward-port to `next`
-- **Forward-port**: Fix in `next` -> backport if needed
-
-### Determining the Base Branch
-
-**Never assume the base branch is `master`**. Most branches are based on `next`, not `master`. When you need to compare commits or understand changes on a branch:
-
-```bash
-# If there's an open PR, check its base branch
-gh pr view --json baseRefName -q '.baseRefName'
-
-# Compare against the correct base
-git log origin/<base-branch>..HEAD   # commits on this branch
-git diff origin/<base-branch>...HEAD  # changes on this branch
-```
+Conventional commit types, branch strategy, merge-train routing, and base-branch detection live in the root `CLAUDE.md` under `<git_workflow>`. The sections below cover only yarn-project-specific additions.
 
 ### Port Commits