diff --git a/.claude/rules/attribution.md b/.claude/rules/attribution.md
new file mode 100644
index 000000000000..5468140b44d2
--- /dev/null
+++ b/.claude/rules/attribution.md
@@ -0,0 +1,10 @@
+# Attribution
+
+When writing commit messages, PR descriptions, or code comments:
+
+- Attribute work to the git author, not to Claude
+- Do NOT add `Co-Authored-By: Claude` trailers to commits
+- Do NOT add `Generated with Claude Code` to PR descriptions
+- Do NOT write comments like `// Added by Claude` or `// AI-generated`
+
+The git author (from `git config user.name`) is the author of record. Claude is a tool, like a compiler or IDE — the human using it owns the output.
diff --git a/.claude/rules/common-mistakes.md b/.claude/rules/common-mistakes.md
new file mode 100644
index 000000000000..55f103d96386
--- /dev/null
+++ b/.claude/rules/common-mistakes.md
@@ -0,0 +1,17 @@
+# Common Mistakes to Avoid
+
+These are real errors observed across many sessions. Read carefully — they save significant tokens and time.
+
+## Git Workflow
+- Default PR base branch is `next`, NOT `master`
+- Barretenberg PRs target `merge-train/barretenberg`
+- yarn-project PRs target `merge-train/spartan`
+- AVM PRs target `merge-train/avm`
+- Always `git fetch` before creating branches to avoid stale bases
+- If `noir/noir-repo` shows as modified, run `git submodule update noir/noir-repo`
+
+## Code Style
+- TypeScript: 120 character line width (not 80). Use `yarn format` before committing.
+- C++: format with `clang-format-20 -i <files>` before committing
+- Noir: max 120 characters per line, use `panic!()` not `assert()` for unreachable code.
+- Rust: run `cargo fmt` before committing.
diff --git a/.claude/rules/git-workflow.md b/.claude/rules/git-workflow.md
new file mode 100644
index 000000000000..562ff4241949
--- /dev/null
+++ b/.claude/rules/git-workflow.md
@@ -0,0 +1,10 @@
+# Git Workflow
+
+## Commit Messages
+
+Follow conventional commits: `fix:`, `feat:`, `chore:`, `refactor:`, `docs:`, `test:`
+
+## PR Merging
+
+- PRs are squashed to a single commit on merge — during development just create normal commits
+- Never target `master` or `main` for PRs without explicit approval
diff --git a/.claude/rules/monorepo.md b/.claude/rules/monorepo.md
new file mode 100644
index 000000000000..297fb137c778
--- /dev/null
+++ b/.claude/rules/monorepo.md
@@ -0,0 +1,43 @@
+# Monorepo Structure and Build System
+
+All paths below are relative to the git root.
+
+## Components
+
+- `barretenberg/` — C++ ZK proving system (Honk, Chonk, ECCVM). See `barretenberg/CLAUDE.md` and `barretenberg/cpp/CLAUDE.md`
+- `barretenberg/cpp/src/barretenberg/vm2/` — AVM (Aztec Virtual Machine) for public execution. See its CLAUDE.md
+- `barretenberg/sol/` — Solidity on-chain verifier. See `barretenberg/sol/CLAUDE.md`
+- `barretenberg/ts/` — TypeScript bindings for barretenberg (bb.js)
+- `avm-transpiler/` — Transpiles Noir bytecode to AVM bytecode (Rust)
+- `noir/` — Noir compiler (git submodule pointing to noir-lang/noir)
+- `noir-projects/` — Protocol circuits and contract libraries written in Noir. See `noir-projects/aztec-nr/CLAUDE.md`
+- `l1-contracts/` — Solidity L1 rollup contracts (Foundry project)
+- `yarn-project/` — TypeScript monorepo: node, client SDK, sequencer, prover, p2p, and tooling. See `yarn-project/CLAUDE.md`
+- `docs/` — Developer documentation site (Docusaurus). See `docs/CLAUDE.md`
+- `spartan/` — Kubernetes deployment infrastructure (Helm charts + Terraform). See `spartan/CLAUDE.md`
+- `bb-pilcom/` — PIL compiler for AVM relation codegen
+- `ci3/` — CI infrastructure scripts
+
+## Build Order
+
+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` — full TS build chain (builds bb, noir, l1-contracts first)
+- `make bb-cpp-native` — barretenberg C++ native only
+- `make noir` — Noir compiler
+- `make l1-contracts` — Solidity contracts via Foundry
+
+For individual components, run `./bootstrap.sh` inside each directory.
+
+## Cross-Component Changes
+
+When your change spans multiple components, rebuild in dependency order:
+
+1. `barretenberg/cpp/` — `cmake --preset default && cd build && ninja`
+2. `barretenberg/ts/` — `./bootstrap.sh` (generates TS bindings from C++)
+3. `noir/` — `./bootstrap.sh` (if noir changes needed)
+4. `noir-projects/` — compile contracts
+5. `l1-contracts/` — `forge build`
+6. `yarn-project/` — `yarn build` (from inside `yarn-project/`, not the git root)
diff --git a/.claude/rules/red-green-testing.md b/.claude/rules/red-green-testing.md
new file mode 100644
index 000000000000..71bfd0c2159b
--- /dev/null
+++ b/.claude/rules/red-green-testing.md
@@ -0,0 +1,22 @@
+# Red/Green Testing
+
+When fixing a bug or addressing an issue, always follow the red/green testing pattern:
+
+1. **Red**: First, write or run a test that demonstrates the failure. Show that the test fails. This proves you understand the problem and have a reliable way to detect it.
+
+2. **Green**: Then make the fix. Run the same test again to show it passes.
+
+This applies to:
+- Bug fixes: Write a test case that reproduces the bug before fixing it
+- CI failures: Reproduce the failure locally before attempting a fix
+- Refactors: Run existing tests to establish a baseline before changing code
+
+If you cannot write a failing test first, explain why (e.g., the issue is non-deterministic, requires infrastructure not available locally, etc.).
+
+## Why This Matters
+
+Without a red test first:
+- You might fix the wrong thing
+- You can't prove your fix actually addresses the issue
+- Reviewers can't verify the fix is correct
+- The same bug can silently regress later
diff --git a/.claude/rules/session-analysis.md b/.claude/rules/session-analysis.md
new file mode 100644
index 000000000000..bc0be67d6dcf
--- /dev/null
+++ b/.claude/rules/session-analysis.md
@@ -0,0 +1,47 @@
+# Session Analysis
+
+At the end of every task (or when the user says "done", "that's it", "thanks", etc.), offer:
+
+> Would you like me to analyze this session for improvement opportunities? I can check the session log for errors, retries, and wasted tokens.
+
+If the user accepts, perform the analysis below.
+
+## Finding the Session JSONL
+
+Claude Code stores session logs as JSONL files under `~/.claude/projects/`. The project path is encoded by replacing `/` with `-`. To find the current session's log:
+
+```bash
+find ~/.claude/projects/ -maxdepth 2 -name "*.jsonl" -not -path "*/subagents/*" \
+  -printf '%T@ %p\n' 2>/dev/null | sort -rn | head -5
+```
+
+Pick the file matching this project's encoded path (e.g., `/home/user/aztec-packages` becomes `-home-user-aztec-packages`).
+
+## What to Look For
+
+Grep the JSONL for patterns that indicate wasted work:
+
+```bash
+SESSION_JSONL="<path from above>"
+
+# Permission blocks and errors (most common waste)
+grep -c 'sensitive file' "$SESSION_JSONL"
+grep -c 'is_error.*true' "$SESSION_JSONL"
+
+# Specific error types
+grep -i 'permission denied\|command not found\|No such file\|ENOENT' "$SESSION_JSONL" | wc -l
+
+# Failed tool calls
+grep '"is_error":true' "$SESSION_JSONL" | grep -oP '"content":"[^"]{0,200}' | head -10
+```
+
+## Output Format
+
+After analysis, produce:
+
+1. **Errors found**: List each distinct error with count and cause
+2. **Token waste**: Estimate retries/detours and what could have prevented them
+3. **CLAUDE.md recommendations**: Specific lines to add that would have prevented these errors
+4. **Missing context**: Information that should have been in a CLAUDE.md but wasn't
+
+Keep recommendations actionable — each should be a concrete sentence that could be copy-pasted into a CLAUDE.md file.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000000..865ba1310c83
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,5 @@
+# aztec-packages
+
+Privacy-first L2 zk-rollup on Ethereum.
+
+All paths in this file are relative to the git root.