diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-js/how_to_pay_fees.md b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-js/how_to_pay_fees.md
index 1f7c3e9b9a13..108a7b4294fc 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-js/how_to_pay_fees.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-js/how_to_pay_fees.md
@@ -215,7 +215,7 @@ const fpcClient = new FpcClient({
 // Estimate gas, fetch a signed quote, and build the payment method
 const payment = await fpcClient.createPaymentMethod({
   wallet,
-  user: wallet.getAddress(),
+  user: aliceAddress, // the account paying the fee
   tokenAddress,     // the token you want to pay in
   estimatedGas,     // from a prior estimateGas call
 });
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-js/how_to_use_authwit.md b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-js/how_to_use_authwit.md
index 530c877d8e5c..0f410bee2bde 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-js/how_to_use_authwit.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-js/how_to_use_authwit.md
@@ -35,7 +35,8 @@ import { General } from '@site/src/components/Snippets/general_snippets';
 
 The authwit system supports different intent types depending on your use case:
 
-- **`CallIntent`**: Use when authorizing a specific contract function call. Contains `{ caller, action }` where `action` is a `ContractFunctionInteraction`.
+- **`CallIntent`**: Use when authorizing a specific contract function call. Contains `{ caller, call }` where `call` is a `FunctionCall`, typically obtained with `await interaction.getFunctionCall()`.
+- **`ContractFunctionInteractionCallIntent`**: Convenience form that takes the interaction directly. Contains `{ caller, action }` where `action` is a `ContractFunctionInteraction`; internally resolved to a `FunctionCall` before signing.
 - **`IntentInnerHash`**: Use when authorizing arbitrary data. Contains `{ consumer, innerHash }` where `consumer` is the contract that will verify the authwit.
 
 ## Create private authwits
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/debugging.md b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/debugging.md
index 51c81a75d33d..83d049050618 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/debugging.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/debugging.md
@@ -31,7 +31,7 @@ Log values from your contract using `debug_log`:
 
 ```rust
 // Import debug logging
-use dep::aztec::oracle::logging::{ debug_log, debug_log_format };
+use aztec::oracle::logging::{ debug_log, debug_log_format };
 
 // Log simple messages
 debug_log("checkpoint reached");
@@ -63,11 +63,7 @@ LOG_LEVEL="info;debug:simulator:client_execution_context;debug:simulator:client_
 ```
 
 :::info Log filter format
-`LOG_LEVEL` accepts a semicolon-delimited list of filters. Each filter can be:
-
-- `level` - Sets default level for all modules
-- `level:module` - Sets level for a specific module
-- `level:module:submodule` - Sets level for a specific submodule
+`LOG_LEVEL` is a semicolon-delimited list. The **first segment must be a bare log level** — it sets the default level for all modules. Subsequent segments are `level:module` (or `level:module:submodule`) overrides.
 
 **The default-level filter must be the first segment.** A bare `level:module` with no preceding default (e.g. `LOG_LEVEL="warn:simulator"`) is invalid and throws `Invalid log level`, because the parser reads everything before the first `;` as the default level. To filter only specific modules, lead with a default level — use `silent` to suppress everything else.
 
@@ -75,16 +71,17 @@ LOG_LEVEL="info;debug:simulator:client_execution_context;debug:simulator:client_
 # Default level only
 LOG_LEVEL="debug"
 
-# Default level + specific module overrides
+# Default level + module overrides
 LOG_LEVEL="info;debug:simulator;debug:execution"
 
-# Default level + specific submodule overrides
+# Default level + submodule overrides
 LOG_LEVEL="info;debug:simulator:client_execution_context;debug:simulator:client_view_context"
 
 # Silence everything except one module
 LOG_LEVEL="silent;debug:simulator"
 ```
 
+A bare `level:module` (e.g. `LOG_LEVEL="warn:simulator"`) is **not valid** — the parser reads the first segment as the default level and rejects it with `Invalid log level: warn:simulator`.
 :::
 
 ## Debugging common errors
@@ -116,9 +113,12 @@ LOG_LEVEL="silent;debug:simulator"
 ### Quick Fixes for Common Issues
 
 ```bash
-# Archiver sync issues - force progress with dummy transactions
-aztec-wallet send transfer --from test0 --to test0 --amount 0
-aztec-wallet send transfer --from test0 --to test0 --amount 0
+# Archiver sync issues - force progress with dummy transactions.
+# Assumes you have imported the local network test accounts
+# (aztec-wallet import-test-accounts) and have a deployed token
+# aliased as `testtoken`.
+aztec-wallet send transfer --from test0 --contract-address testtoken --args accounts:test0 0
+aztec-wallet send transfer --from test0 --contract-address testtoken --args accounts:test0 0
 
 # L1 to L2 message pending - wait for inclusion
 # Messages need 2 blocks to be processed
@@ -210,7 +210,7 @@ LOG_LEVEL=verbose aztec start --local-network
 ### Common debug imports
 
 ```rust
-use dep::aztec::oracle::logging::{ debug_log, debug_log_format };
+use aztec::oracle::logging::{ debug_log, debug_log_format };
 ```
 
 ### Check contract registration
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/how_to_prove_history.md b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/how_to_prove_history.md
index 89f49d40e27b..0dd61ca4b4fb 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/how_to_prove_history.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/how_to_prove_history.md
@@ -51,7 +51,7 @@ let confirmed_note = assert_note_existed_by(header, hinted_note);
 To prove a note was valid (existed AND wasn't nullified) at a historical block:
 
 ```rust
-use dep::aztec::history::note::assert_note_was_valid_by;
+use aztec::history::note::assert_note_was_valid_by;
 
 let header = self.context.get_anchor_block_header();
 assert_note_was_valid_by(header, hinted_note, &mut self.context);
@@ -66,7 +66,7 @@ This verifies both:
 To prove against state at a specific past block (not just the anchor block):
 
 ```rust
-use dep::aztec::history::note::assert_note_existed_by;
+use aztec::history::note::assert_note_existed_by;
 
 let historical_header = self.context.get_block_header_at(block_number);
 assert_note_existed_by(historical_header, hinted_note);
@@ -81,7 +81,7 @@ Using `get_block_header_at` adds ~3k constraints to prove Archive tree membershi
 To prove a note has been spent/nullified:
 
 ```rust
-use dep::aztec::history::note::assert_note_was_nullified_by;
+use aztec::history::note::assert_note_was_nullified_by;
 
 let header = self.context.get_anchor_block_header();
 assert_note_was_nullified_by(header, confirmed_note, &mut self.context);
@@ -92,7 +92,7 @@ assert_note_was_nullified_by(header, confirmed_note, &mut self.context);
 To prove a contract's bytecode was published at a historical block:
 
 ```rust
-use dep::aztec::history::deployment::assert_contract_bytecode_was_published_by;
+use aztec::history::deployment::assert_contract_bytecode_was_published_by;
 
 let header = self.context.get_anchor_block_header();
 assert_contract_bytecode_was_published_by(header, contract_address);
@@ -101,8 +101,8 @@ assert_contract_bytecode_was_published_by(header, contract_address);
 You can also prove a contract was initialized (constructor was called):
 
 ```rust
-use dep::aztec::history::deployment::assert_contract_was_initialized_by;
-use dep::aztec::oracle::get_contract_instance::get_contract_instance;
+use aztec::history::deployment::assert_contract_was_initialized_by;
+use aztec::oracle::get_contract_instance::get_contract_instance;
 
 let header = self.context.get_anchor_block_header();
 let instance = get_contract_instance(contract_address);
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/how_to_retrieve_filter_notes.md b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/how_to_retrieve_filter_notes.md
index 5e7abea3346d..ac1563e88a74 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/how_to_retrieve_filter_notes.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/how_to_retrieve_filter_notes.md
@@ -16,8 +16,8 @@ This guide shows you how to retrieve and filter notes from private storage using
 ## Required imports
 
 ```rust
-use dep::aztec::note::note_getter_options::{NoteGetterOptions, NoteStatus, SortOrder};
-use dep::aztec::utils::comparison::Comparator;
+use aztec::note::note_getter_options::{NoteGetterOptions, NoteStatus, SortOrder};
+use aztec::utils::comparison::Comparator;
 ```
 
 ## Set up basic note retrieval
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/writing_efficient_contracts.md b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/writing_efficient_contracts.md
index 71977ac0aeb9..833baf624d67 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/writing_efficient_contracts.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/advanced/writing_efficient_contracts.md
@@ -179,11 +179,11 @@ See [this example](https://github.com/noir-lang/noir-examples/blob/master/noir_b
 Consider the following example of an implementation of the `sqrt` function:
 
 ```rust
-use dep::aztec::macros::aztec;
+use aztec::macros::aztec;
 
 #[aztec]
 pub contract OptimisationExample {
-    use dep::aztec::macros::{functions::{external, initializer}, storage::storage};
+    use aztec::macros::{functions::{external, initializer}, storage::storage};
 
     #[storage]
     struct Storage<Context> {}
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/contract_structure.md b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/contract_structure.md
index 2b393b06d518..dee81f37234d 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/contract_structure.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/contract_structure.md
@@ -10,28 +10,18 @@ High-level structure of how Aztec smart contracts including the different compon
 
 ## Directory structure
 
-When you create a new project with `aztec new my_project`, it generates a workspace with two crates named after your project: a `my_project_contract` crate for your smart contract and a `my_project_test` crate for Noir tests.
+When you create a new project with `aztec new my_project`, it generates a single-crate Noir contract project:
 
 ```text title="layout of an aztec contract project"
 ─── my_project
-       ├── Nargo.toml                    <-- workspace root
-       ├── my_project_contract
-       │     ├── src
-       │     │     └── main.nr           <-- your contract
-       │     └── Nargo.toml              <-- contract package and dependencies
-       └── my_project_test
-             ├── src
-             │     └── lib.nr            <-- your tests
-             └── Nargo.toml              <-- test package and dependencies
+       ├── Nargo.toml                    <-- contract package and dependencies
+       └── src
+             └── main.nr                 <-- your contract
 ```
 
-The workspace root `Nargo.toml` declares both crates as workspace members. The contract code lives in `my_project_contract/src/main.nr`, and tests live in a separate `my_project_test` crate that depends on the contract crate.
+`Nargo.toml` declares the contract package (with `type = "contract"`) and its dependencies. Your contract code lives in `src/main.nr`. Noir tests using `#[test]` live alongside the contract in the same crate — see [Testing Contracts](../testing_contracts.md).
 
-You can add more contracts to an existing workspace by running `aztec new <name>` from inside the workspace directory. This creates a new `<name>_contract` and `<name>_test` crate pair and adds them to the workspace.
-
-:::warning Keep tests out of the contract crate
-Do not add `#[test]` functions to the `<name>_contract` crate. Because the contract artifact depends on everything in its crate, any change — including a test-only change — forces a full recompilation of the contract. The separate `<name>_test` crate lets you iterate on tests without rebuilding the contract. See [Testing Contracts](../testing_contracts.md#keep-tests-in-the-test-crate) for details.
-:::
+To add another contract as a sibling of an existing one, run `aztec new <name>` from the parent directory (each contract is its own crate). To initialize a contract project inside an existing empty directory instead, `cd` into it and run `aztec init` (it takes no positional argument; pass `--name <name>` if you want the package name to differ from the directory name).
 
 See the vanilla Noir docs for [more info on packages](https://noir-lang.org/docs/noir/modules_packages_crates/crates_and_packages).
 
@@ -58,7 +48,7 @@ The `#[aztec]` macro performs a lot of the low-level operations required to take
 
 ## Imports
 
-Aside from the [`#[aztec]`](pathname:///aztec-nr-api/mainnet/noir_aztec/macros/aztec/fn.aztec) macro import, all other imports need to go _inside_ the `contract` block - this is because `contract` acts like `mod`, creating a new [module](https://noir-lang.org/docs/noir/modules_packages_crates/modules).
+Aside from the [`#[aztec]`](pathname:///aztec-nr-api/mainnet/noir_aztec/macros/fn.aztec) macro import, all other imports need to go _inside_ the `contract` block - this is because `contract` acts like `mod`, creating a new [module](https://noir-lang.org/docs/noir/modules_packages_crates/modules).
 
 ```rust
 use aztec::macros::aztec;
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/functions/how_to_define_functions.md b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/functions/how_to_define_functions.md
index 8c2f64aba92e..e8fc39ee84c3 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/functions/how_to_define_functions.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/framework-description/functions/how_to_define_functions.md
@@ -121,8 +121,8 @@ Create constructor-like functions using the `#[initializer]` annotation:
 #[initializer]
 #[external("private")]
 // We can name our initializer anything we want as long as it's marked as aztec(initializer)
-fn initialize(headstart: u64, owner: AztecAddress) {
-    self.storage.counters.at(owner).add(headstart as u128).deliver(
+fn initialize(headstart: u128, owner: AztecAddress) {
+    self.storage.counters.at(owner).add(headstart).deliver(
         MessageDelivery.ONCHAIN_CONSTRAINED,
     );
 }
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/index.md b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/index.md
index fc5e9c1214e4..e898ef8563f2 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/index.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/index.md
@@ -42,15 +42,15 @@ storage.votes.insert(new_vote).deliver(MessageDelivery.ONCHAIN_CONSTRAINED); //
 
 ### Flow
 
-1. Write your contract and specify your contract dependencies. Create a new project with `aztec new my_project`, which sets up a workspace with a `my_project_contract` crate and a `my_project_test` crate, with the `aztec` dependency already configured. If you need additional dependencies, add them to `my_project_contract/Nargo.toml`:
+1. Write your contract and specify your contract dependencies. Create a new project with `aztec new my_project`, which creates a single-crate Noir contract project (`Nargo.toml` + `src/main.nr`) with the `aztec` dependency already configured. If you need additional dependencies, add them to `my_project/Nargo.toml`:
 
 ```toml
-# my_project_contract/Nargo.toml
+# my_project/Nargo.toml
 [dependencies]
 aztec = { git="https://github.com/AztecProtocol/aztec-nr/", tag="v4.2.0", directory="aztec" }
 ```
 
-Update your `my_project_contract/src/main.nr` contract file to use the Aztec.nr macros for writing contracts.
+Update your `my_project/src/main.nr` contract file to use the Aztec.nr macros for writing contracts.
 
 ```rust title="setup" showLineNumbers 
 use aztec::macros::aztec;
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/testing_contracts.md b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/testing_contracts.md
index 21fbb89ef581..52ab8b73e7b6 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/testing_contracts.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/aztec-nr/testing_contracts.md
@@ -44,38 +44,30 @@ aztec test
 Always use `aztec test` instead of `nargo test`. The `TestEnvironment` requires the TXE (Test eXecution Environment) oracle resolver.
 :::
 
-## Keep tests in the test crate
-
-When you create a project with `aztec new` or `aztec init`, the generated workspace has two crates: `<name>_contract` and `<name>_test`. It is important that all tests live in the `<name>_test` crate, **not** in the `<name>_contract` crate.
-
-If you place `#[test]` functions inside the contract crate, `aztec compile` will emit a warning:
-
-```
-WARNING: Found tests in contract crate(s):
-  my_contract::test_something
-Tests should be in a dedicated test crate, not in the contract crate.
-```
-
-The reason is **unnecessary recompilation**: the contract artifact depends on everything inside the contract crate. If tests live there too, editing a test changes the crate and forces the contract to be recompiled and reprocessed, even though the contract logic itself has not changed. By keeping tests in a separate crate, you can iterate on tests without triggering a full contract rebuild.
-
 ## Basic test structure
 
-Tests live in `<name>_test/src/lib.nr` and import the contract crate by name (not `crate::`):
+Tests live in the same crate as your contract. `aztec new` creates a single-crate project, and the convention is to place `#[test]` functions in a `mod tests` block alongside the contract (or in submodules of the crate):
 
 ```rust
-use my_contract::MyContract;
-use aztec::{
-    protocol::address::AztecAddress,
-    test::helpers::test_environment::TestEnvironment,
-};
+use aztec::macros::aztec;
 
-#[test]
-unconstrained fn test_basic_flow() {
-    // 1. Create test environment
-    let mut env = TestEnvironment::new();
+#[aztec]
+pub contract MyContract {
+    // ...contract functions...
+}
 
-    // 2. Create accounts
-    let owner = env.create_light_account();
+mod tests {
+    use super::MyContract;
+    use aztec::test::helpers::test_environment::TestEnvironment;
+
+    #[test]
+    unconstrained fn test_basic_flow() {
+        // 1. Create test environment
+        let mut env = TestEnvironment::new();
+
+        // 2. Create accounts
+        let _owner = env.create_light_account();
+    }
 }
 ```
 
@@ -88,12 +80,14 @@ unconstrained fn test_basic_flow() {
 :::
 
 :::tip Organizing test files
-Tests live in the separate `<name>_test` crate that `aztec new` creates. You can organize them into modules:
+For larger test suites, split tests into submodules of your crate rather than keeping them all inside `main.nr`:
 
-- Split tests into modules like `<name>_test/src/transfer_tests.nr`, `<name>_test/src/auth_tests.nr`
-- Import them in `<name>_test/src/lib.nr` with `mod transfer_tests;`, `mod auth_tests;`
-- Share setup functions in `<name>_test/src/utils.nr`
-  :::
+- Create modules like `src/transfer_tests.nr`, `src/auth_tests.nr`
+- Declare them from `src/main.nr` with `mod transfer_tests;`, `mod auth_tests;`
+- Share setup functions in `src/test_utils.nr`
+
+See the [aztec-standards token contract](https://github.com/defi-wonderland/aztec-standards/tree/dev/src/token_contract) for a worked example of this layout.
+:::
 
 ## Deploying contracts
 
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/counter_contract.md b/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/counter_contract.md
index 058449326f6a..8c4ab4a331d1 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/counter_contract.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/counter_contract.md
@@ -125,8 +125,8 @@ Let’s create a constructor method to run on deployment that assigns an initial
 #[initializer]
 #[external("private")]
 // We can name our initializer anything we want as long as it's marked as aztec(initializer)
-fn initialize(headstart: u64, owner: AztecAddress) {
-    self.storage.counters.at(owner).add(headstart as u128).deliver(
+fn initialize(headstart: u128, owner: AztecAddress) {
+    self.storage.counters.at(owner).add(headstart).deliver(
         MessageDelivery.ONCHAIN_CONSTRAINED,
     );
 }
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/recursive_verification.md b/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/recursive_verification.md
index 3c65e0db4e5e..fbf8766c3031 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/recursive_verification.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/recursive_verification.md
@@ -202,9 +202,9 @@ nargo test
 Expected output:
 
 ```text
-[hello_circuit] Running 1 test functions
-[hello_circuit] Testing test_main... ok
-[hello_circuit] All tests passed
+[hello_circuit] Running 1 test function
+[hello_circuit] Testing test_main ... ok
+[hello_circuit] 1 test passed
 ```
 
 **Tip**: Circuit tests run without generating proofs, making them fast for development. Use them to verify your circuit logic before the more expensive proof generation step.
@@ -225,12 +225,14 @@ The contract demonstrates several important patterns:
 
 ### Create the Contract Project
 
-Use `aztec init` to generate the contract project structure:
+Use `aztec new` to generate the contract project structure:
 
 ```bash
-aztec init --contract contract
+aztec new --name ValueNotEqual contract
 ```
 
+The `aztec new` wrapper stops parsing arguments at the first positional, so `--name` must come **before** the `contract` path — otherwise the flag is silently dropped and the Nargo package ends up named `contract`. The Nargo package name (`--name`) is independent of the Noir contract name declared inside `main.nr`; the artifact filename downstream is driven by the contract name.
+
 This creates:
 
 ```tree
@@ -699,7 +701,7 @@ Expected output:
 Proof verification: SUCCESS
 Using deflattenFields to convert proof...
 VK size: 115
-Proof size: 508
+Proof size: 500
 Public inputs: 1
 Done
 ```
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/token_contract.md b/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/token_contract.md
index c27b69157932..d5d8b84cce03 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/token_contract.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/contract_tutorials/token_contract.md
@@ -41,7 +41,7 @@ Let's create a simple yarn + aztec.nr project:
 ```bash
 aztec new bob_token
 cd bob_token
-yarn init
+yarn init -y
 # This is to ensure yarn uses node_modules instead of pnp for dependency installation
 yarn config set nodeLinker node-modules
 yarn add @aztec/aztec.js@v4.2.0 @aztec/accounts@v4.2.0 @aztec/kv-store@v4.2.0 @aztec/wallets@v4.2.0
@@ -89,6 +89,10 @@ pub contract BobToken {
 
 These are the different macros we need to define the visibility of functions, and some handy types and functions.
 
+:::note
+You may see "unused import" warnings from your IDE or compiler for `only_self`, `MessageDelivery`, and `Owned`. That's expected at this stage — we'll start using them in Part 2 when we add the private half of the contract.
+:::
+
 ## Building the Mental Health Token System
 
 ### The Privacy Architecture
@@ -269,7 +273,9 @@ async function main() {
   // Connect to local network
   const node = createAztecNodeClient("http://localhost:8080");
 
-  const wallet = await EmbeddedWallet.create(node);
+  // `ephemeral: true` keeps PXE state in memory, so restarting the local
+  // network won't leave this script pointing at stale block hashes.
+  const wallet = await EmbeddedWallet.create(node, { ephemeral: true });
 
   const [giggleWalletData, aliceWalletData, bobClinicWalletData] =
     await getInitialTestAccountsData();
@@ -318,6 +324,14 @@ What's this `tsx` dark magic? `tsx` is a tool that compiles and runs TypeScript
 
 :::
 
+:::tip Ephemeral PXE state
+
+We pass `{ ephemeral: true }` to `EmbeddedWallet.create`. This tells the PXE to keep its state in memory instead of writing it to `pxe_data_*` / `wallet_data_*` folders on disk. If you ever stop and restart your local network (or wipe its state), the next run starts clean instead of failing with errors like `No local block hash for block number …` because on-disk PXE state no longer matches the chain.
+
+For real applications you typically want persistent state, but for tutorials that spin up a fresh network each run, ephemeral is the safer default.
+
+:::
+
 ### 🎉 Celebrate
 
 Congratulations! You've just deployed a working token contract on Aztec! You can:
@@ -352,11 +366,15 @@ When Alice spends 40 BOB tokens at Bob's clinic:
 3. She creates a "change" note for herself (40 BOB)
 4. The consumed notes are nullified (marked as spent)
 
+:::info What is a nullifier?
+A **nullifier** is a unique, one-way tag emitted when a private note is spent. The network adds it to a nullifier tree so the same note can't be spent twice, but because the nullifier is derived from secrets only the note's owner knows, nobody can link a nullifier back to the note it invalidated. See [State Management](../../foundational-topics/state_management.md#private-state) for more.
+:::
+
 In this case, all that the network sees (including Giggle) is just "something happening to some state in some contract". How cool is that?
 
 ### Updating Storage for Privacy
 
-For something like balances, you can use a simple library called `easy_private_state` which abstracts away a custom private Note. A Note is at the core of how private state works in Aztec and you can read about it [here](../../foundational-topics/state_management.md). For now, let's add it by replacing the `[dependencies]` section in `Nargo.toml`:
+For something like balances, you can use a simple library called `balance_set` which abstracts away a custom private Note. A Note is at the core of how private state works in Aztec and you can read about it [here](../../foundational-topics/state_management.md). For now, let's add it by replacing the `[dependencies]` section in `Nargo.toml`:
 
 ```toml
 [dependencies]
@@ -579,6 +597,14 @@ aztec codegen target --outdir artifacts
 
 ## Testing the Complete Privacy System
 
+Before running the updated script, double-check your local network is still running:
+
+```bash
+aztec start --local-network
+```
+
+If you stopped it between parts of the tutorial, start it again here. Because we set `ephemeral: true` when creating the wallet, restarting the network is safe — the script won't try to reuse stale PXE state from a previous run.
+
 Now that you've implemented all the privacy features, let's update our test script to showcase the full privacy flow:
 
 ### Update Your Test Script
@@ -679,7 +705,14 @@ Let's give it a try:
 npx tsx index.ts
 ```
 
-You should see the complete privacy journey from transparent allocation to confidential usage!
+You should see the complete privacy journey from transparent allocation to confidential usage. The final pair of log lines should look like:
+
+```text
+📊 Alice has 100 public BOB tokens and 130 private BOB tokens
+📊 Bob's Clinic has 20 public BOB tokens and 50 private BOB tokens
+```
+
+If your output doesn't match, double-check that the local network is running and that you started this run with a fresh `aztec start --local-network`.
 
 ## Summary
 
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/local_network.md b/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/local_network.md
deleted file mode 100644
index 51826cfdd3bc..000000000000
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/local_network.md
+++ /dev/null
@@ -1,214 +0,0 @@
----
-title: Run Aztec in a Local Network
-sidebar_position: 0
-tags: [local_network, wallet]
-description: Information about running the Aztec local network development environment.
----
-
-<!-- NOTE: How is this different from getting started with local network - need to merge then delete this one!!! -->
-
-- Current version: `v4.2.0`
-- Update with `aztec-up 4.2.0`
-
-On this page you will find
-
-- [Versions](#versions)
-  - [Dependency versions](#dependency-versions)
-  - [Example contract versions](#example-contract-versions)
-  - [Language server version](#language-server-version)
-- [Updating](#updating)
-  - [Steps to keep up to date](#steps-to-keep-up-to-date)
-- [Updating Aztec.nr packages](#updating-aztecnr-packages)
-  - [Automatic update](#automatic-update)
-  - [Manual update](#manual-update)
-- [Updating Aztec.js packages](#updating-aztecjs-packages)
-- [Local Network PXE Proving](#local-network-pxe-proving)
-  - [Local Network in Proving Mode](#local-network-in-proving-mode)
-    - [Usage](#usage)
-  - [Proving with `aztec-wallet`](#proving-with-aztec-wallet)
-
-## Versions
-
-Aztec tools (local network, nargo), dependencies (Aztec.nr), and sample contracts are constantly being improved.
-When developing and referring to example .nr files/snippets, it is helpful to verify the versions of different components (below), and if required keep them in lock-step by [updating](#updating).
-
-### Dependency versions
-
-Dependency versions in a contract's `Nargo.toml` file correspond to the `aztec-packages` repository tag `aztec-packages` (filter tags by `aztec`...)
-
-If you get an error like: `Cannot read file ~/nargo/github.com/AztecProtocol/aztec-packages/...`
-Check the `git=` github url, tag, and directory.
-
-### Example contract versions
-
-Example contracts serve as a helpful reference between versions of the Aztec.nr framework since they are strictly maintained with each release.
-
-Code referenced in the documentation is sourced from contracts within [this directory (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/v4.2.0/noir-projects/noir-contracts/contracts).
-
-As in the previous section, the location of the noir contracts moved at version `0.24.0`, from `yarn-project/noir-contracts` before, to `noir-projects/noir-contracts`.
-
-:::tip
-Notice the difference between the sample Counter contract from `0.23.0` to `0.24.0` shows the `note_type_id` was added.
-
-```shell
-diff ~/nargo/github.com/AztecProtocol/v0.23.0/yarn-project/noir-contracts/contracts/test/counter_contract/src/main.nr ~/nargo/github.com/AztecProtocol/v0.24.0/noir-projects/noir-contracts/contracts/test/counter_contract/src/main.nr
-```
-
-```
-57a58
->         note_type_id: Field,
-```
-
-:::
-
-### Language server version
-
-The [Noir LSP](../aztec-nr/installation.md) uses your local version of `aztec`, and thus also `aztec compile`.
-The path of the former (once installed) can be seen by hovering over "Nargo" in the bottom status bar of VS Code, and the latter via the `which aztec` command.
-
-:::caution
-For Aztec contract files, this should be `aztec` and for noir-only files this should be `nargo`. Mismatching tools and file types will generate misleading syntax and compiler errors.
-:::
-
-This can present confusion when opening older contracts (and dependencies) written in older version of noir, such as:
-
-- Logs filled with errors from the dependencies
-- Or the LSP fails (re-runs automatically then stops)
-  The second point requires a restart of the extension, which you can trigger with the command palette (Ctrl + Shift + P) and typing "Reload Window".
-
-## Updating
-
-### Steps to keep up to date
-
-1. Update the Aztec local network to the latest version (includes `aztec` command, pxe, etc):
-
-```shell
-aztec-up
-```
-
-To update to a specific version, pass the version number after the `aztec-up` command, or set `VERSION` for a particular git tag, eg for [v**0.77.0**](https://github.com/AztecProtocol/aztec-packages/tree/v0.77.0)
-
-```shell
-aztec-up 0.77.0
-# or
-VERSION=0.77.0 aztec-up
-```
-
-2. Update Aztec.nr and individual @aztec dependencies:
-
-Inside your project run:
-
-```shell
-cd your/aztec/project
-aztec update . --contract src/contract1 --contract src/contract2
-```
-
-The local network must be running for the update command to work. Make sure it is [installed and running](../../getting_started_on_local_network.md).
-
-Follow [updating Aztec.nr packages](#updating-aztecnr-packages) and [updating JavaScript packages](#updating-aztecjs-packages) guides.
-
-3. Refer to [Migration Notes](../resources/migration_notes.md) on any breaking changes that might affect your dapp
-
----
-
-There are four components whose versions need to be kept compatible:
-
-1. Aztec local network (includes the `aztec` command)
-2. `Aztec.nr`, the Noir framework for writing Aztec contracts
-
-You can manage Aztec versions using `aztec-up`. Use `aztec-up install <version>` to install a specific version, or `aztec-up use <version>` to switch between installed versions.
-You need to update your Aztec.nr version manually or using `aztec update`.
-
-## Updating Aztec.nr packages
-
-### Automatic update
-
-You can update your Aztec.nr packages to the appropriate version with the `aztec update` command. Run this command from the root of your project and pass the paths to the folders containing the Nargo.toml files for your projects like so:
-
-```shell
-aztec update . --contract src/contract1 --contract src/contract2
-```
-
-### Manual update
-
-To update the aztec.nr packages manually, update the tags of the `aztec.nr` dependencies in the `Nargo.toml` file.
-
-```diff
-[dependencies]
--aztec = { git="https://github.com/AztecProtocol/aztec-packages", tag="v0.7.5", directory="noir-projects/aztec-nr/aztec" }
-+aztec = { git="https://github.com/AztecProtocol/aztec-packages", tag="v4.2.0", directory="noir-projects/aztec-nr/aztec" }
--value_note = { git="https://github.com/AztecProtocol/aztec-packages", tag="v0.7.5", directory="noir-projects/aztec-nr/value-note" }
-+value_note = { git="https://github.com/AztecProtocol/aztec-packages", tag="v4.2.0", directory="noir-projects/aztec-nr/value-note" }
-```
-
-Go to the contract directory and try compiling it to verify that the update was successful:
-
-```shell
-cd /your/contract/directory
-aztec compile        # compiles the contract
-```
-
-If the dependencies fail to resolve ensure that the tag matches a tag in the [aztec-packages repository (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tags).
-
-## Updating Aztec.js packages
-
-To update Aztec.js packages, go to your `package.json` and replace the versions in the dependencies.
-
-```diff
-[dependencies]
--"@aztec/accounts": "0.7.5",
-+"@aztec/accounts": "v4.2.0",
--"@aztec/noir-contracts.js": "0.35.1",
-+"@aztec/accounts": "v4.2.0",
-```
-
-## Local Network PXE Proving
-
-The local network does not have client-side proving in the PXE enabled by default. This reduces testing times and increases development speed by allowing for rapid iteration.
-
-You may want to enable client-side proving in the local network to better understand how long it takes to execute Aztec transactions. There are 2 ways of doing this:
-
-1. Run the local network in proving mode (every transaction wil be proved) or
-2. Use `aztec-wallet` cli to prove a one-off transaction
-
-:::note
-Proving is much slower and should only be used sparingly to analyze real proving times of executing private functions of a contract.
-:::
-
-### Local Network in Proving Mode
-
-Here every transaction, contract deployment will be proved. If you want to just prove a single transaction, follow [proving with aztec-wallet cli](#proving-with-aztec-wallet).
-
-#### Usage
-
-To enable client-side proving:
-
-```bash
-PXE_PROVER_ENABLED=1 aztec start --local-network
-```
-
-The local network will take much longer to start. The first time it starts, it will need to download a large crs file, which can take several minutes even on a fast internet connection. This is a one-time operation, you will not need to download it again until you update to a new Aztec version.
-
-The local network will also deploy 3 Schnorr account contracts on startup. The local network will need to generate transaction proofs for deployment, which will take additional time.
-
-Once everything has been set up, you will see that the PXE is listening on `localhost:8080` as you would see with the local network running in the default mode. At this point you can use the local network as you would without client-side proving enabled.
-
-### Proving with `aztec-wallet`
-
-You can enable proving on a per-transaction basis using the `aztec-wallet` CLI by setting the `PXE_PROVER_ENABLED` environment variable to `1`. This will use your local `bb` binary to prove the transaction.
-
-```bash
-PXE_PROVER_ENABLED=1 aztec-wallet create-account -a test
-```
-
-Check the [Getting Started on Local Network](../../getting_started_on_local_network.md) for a refresher on how to send transactions using `aztec-wallet` or check the [reference here](../cli/aztec_wallet_cli_reference.md)
-
-Note that you do not need to restart the local network in order to start sending proven transactions. You can optionally set this for one-off transactions.
-
-If this is the first time you are sending transactions with proving enabled, it will take a while to download a CRS file (which is several MBs) that is required for proving.
-
-:::note
-You can also profile your transactions to get gate count, if you don't want to prove your transactions but check how many constraints it is. Follow the [guide here](../aztec-nr/framework-description/advanced/how_to_profile_transactions.md)
-:::
-
-You can learn more about custom commands in the [Aztec CLI Reference](../cli/aztec_cli_reference.md).
diff --git a/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/testing_governance_rollup_upgrade.md b/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/testing_governance_rollup_upgrade.md
index f4427e532d5b..806c32b0a3b3 100644
--- a/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/testing_governance_rollup_upgrade.md
+++ b/docs/developer_versioned_docs/version-v4.2.0/docs/tutorials/testing_governance_rollup_upgrade.md
@@ -359,10 +359,13 @@ aztec get-l1-addresses \
 
 ```bash
 aztec debug-rollup \
+  --rollup $NEW_ROLLUP_ADDRESS \
   --l1-rpc-urls $L1_RPC_URL \
   -c $L1_CHAIN_ID
 ```
 
+The `--rollup` flag is required; without it the command may fail trying to resolve the default rollup address.
+
 ---
 
 ## Quick Test (Empty Payload)
diff --git a/docs/docs-developers/docs/aztec-js/how_to_pay_fees.md b/docs/docs-developers/docs/aztec-js/how_to_pay_fees.md
index 85baf5a85eda..b036f41926d1 100644
--- a/docs/docs-developers/docs/aztec-js/how_to_pay_fees.md
+++ b/docs/docs-developers/docs/aztec-js/how_to_pay_fees.md
@@ -146,7 +146,7 @@ const fpcClient = new FpcClient({
 // Estimate gas, fetch a signed quote, and build the payment method
 const payment = await fpcClient.createPaymentMethod({
   wallet,
-  user: wallet.getAddress(),
+  user: aliceAddress, // the account paying the fee
   tokenAddress,     // the token you want to pay in
   estimatedGas,     // from a prior estimateGas call
 });
diff --git a/docs/docs-developers/docs/aztec-js/how_to_test.md b/docs/docs-developers/docs/aztec-js/how_to_test.md
index ae916c535cb1..d22443b724e2 100644
--- a/docs/docs-developers/docs/aztec-js/how_to_test.md
+++ b/docs/docs-developers/docs/aztec-js/how_to_test.md
@@ -37,7 +37,7 @@ Deploy contracts using the generated contract class:
 
 Use `.simulate()` to read contract state without creating a transaction:
 
-#include_code simulate_function docs/examples/ts/aztecjs_connection/index.ts typescript
+#include_code simulate_function /docs/examples/ts/aztecjs_connection/index.ts typescript
 
 Simulations are free (no gas cost) and return the function's result directly. Use them for:
 
diff --git a/docs/docs-developers/docs/aztec-js/how_to_use_authwit.md b/docs/docs-developers/docs/aztec-js/how_to_use_authwit.md
index 1b38f508a8fe..7390e1a451cf 100644
--- a/docs/docs-developers/docs/aztec-js/how_to_use_authwit.md
+++ b/docs/docs-developers/docs/aztec-js/how_to_use_authwit.md
@@ -35,7 +35,8 @@ import { General } from '@site/src/components/Snippets/general_snippets';
 
 The authwit system supports different intent types depending on your use case:
 
-- **`CallIntent`**: Use when authorizing a specific contract function call. Contains `{ caller, action }` where `action` is a `ContractFunctionInteraction`.
+- **`CallIntent`**: Use when authorizing a specific contract function call. Contains `{ caller, call }` where `call` is a `FunctionCall`, typically obtained with `await interaction.getFunctionCall()`.
+- **`ContractFunctionInteractionCallIntent`**: Convenience form that takes the interaction directly. Contains `{ caller, action }` where `action` is a `ContractFunctionInteraction`; internally resolved to a `FunctionCall` before signing.
 - **`IntentInnerHash`**: Use when authorizing arbitrary data. Contains `{ consumer, innerHash }` where `consumer` is the contract that will verify the authwit.
 
 ## Create private authwits
diff --git a/docs/docs-developers/docs/aztec-nr/debugging.md b/docs/docs-developers/docs/aztec-nr/debugging.md
index 8816db5b873d..a3cd449bb554 100644
--- a/docs/docs-developers/docs/aztec-nr/debugging.md
+++ b/docs/docs-developers/docs/aztec-nr/debugging.md
@@ -52,9 +52,12 @@ LOG_LEVEL=verbose aztec start --local-network
 ### Quick Fixes for Common Issues
 
 ```bash
-# Archiver sync issues - force progress with dummy transactions
-aztec-wallet send transfer --from test0 --to test0 --amount 0
-aztec-wallet send transfer --from test0 --to test0 --amount 0
+# Archiver sync issues - force progress with dummy transactions.
+# Assumes you have imported the local network test accounts
+# (aztec-wallet import-test-accounts) and have a deployed token
+# aliased as `testtoken`.
+aztec-wallet send transfer --from test0 --contract-address testtoken --args accounts:test0 0
+aztec-wallet send transfer --from test0 --contract-address testtoken --args accounts:test0 0
 
 # L1 to L2 message pending - wait for inclusion
 # Messages need 2 blocks to be processed
diff --git a/docs/docs-developers/docs/aztec-nr/framework-description/advanced/how_to_prove_history.md b/docs/docs-developers/docs/aztec-nr/framework-description/advanced/how_to_prove_history.md
index b3c3cc6105c4..dfd246633454 100644
--- a/docs/docs-developers/docs/aztec-nr/framework-description/advanced/how_to_prove_history.md
+++ b/docs/docs-developers/docs/aztec-nr/framework-description/advanced/how_to_prove_history.md
@@ -42,7 +42,7 @@ Prove a note exists in the note hash tree:
 To prove a note was valid (existed AND wasn't nullified) at a historical block:
 
 ```rust
-use dep::aztec::history::note::assert_note_was_valid_by;
+use aztec::history::note::assert_note_was_valid_by;
 
 let header = self.context.get_anchor_block_header();
 assert_note_was_valid_by(header, hinted_note, &mut self.context);
@@ -57,7 +57,7 @@ This verifies both:
 To prove against state at a specific past block (not just the anchor block):
 
 ```rust
-use dep::aztec::history::note::assert_note_existed_by;
+use aztec::history::note::assert_note_existed_by;
 
 let historical_header = self.context.get_block_header_at(block_number);
 assert_note_existed_by(historical_header, hinted_note);
@@ -72,7 +72,7 @@ Using `get_block_header_at` adds ~3k constraints to prove Archive tree membershi
 To prove a note has been spent/nullified:
 
 ```rust
-use dep::aztec::history::note::assert_note_was_nullified_by;
+use aztec::history::note::assert_note_was_nullified_by;
 
 let header = self.context.get_anchor_block_header();
 assert_note_was_nullified_by(header, confirmed_note, &mut self.context);
@@ -83,7 +83,7 @@ assert_note_was_nullified_by(header, confirmed_note, &mut self.context);
 To prove a contract's bytecode was published at a historical block:
 
 ```rust
-use dep::aztec::history::deployment::assert_contract_bytecode_was_published_by;
+use aztec::history::deployment::assert_contract_bytecode_was_published_by;
 
 let header = self.context.get_anchor_block_header();
 assert_contract_bytecode_was_published_by(header, contract_address);
@@ -92,8 +92,8 @@ assert_contract_bytecode_was_published_by(header, contract_address);
 You can also prove a contract was initialized (constructor was called):
 
 ```rust
-use dep::aztec::history::deployment::assert_contract_was_initialized_by;
-use dep::aztec::oracle::get_contract_instance::get_contract_instance;
+use aztec::history::deployment::assert_contract_was_initialized_by;
+use aztec::oracle::get_contract_instance::get_contract_instance;
 
 let header = self.context.get_anchor_block_header();
 let instance = get_contract_instance(contract_address);
diff --git a/docs/docs-developers/docs/aztec-nr/framework-description/advanced/how_to_retrieve_filter_notes.md b/docs/docs-developers/docs/aztec-nr/framework-description/advanced/how_to_retrieve_filter_notes.md
index ede622c187d7..b0fb8969443d 100644
--- a/docs/docs-developers/docs/aztec-nr/framework-description/advanced/how_to_retrieve_filter_notes.md
+++ b/docs/docs-developers/docs/aztec-nr/framework-description/advanced/how_to_retrieve_filter_notes.md
@@ -16,8 +16,8 @@ This guide shows you how to retrieve and filter notes from private storage using
 ## Required imports
 
 ```rust
-use dep::aztec::note::note_getter_options::{NoteGetterOptions, NoteStatus, SortOrder};
-use dep::aztec::utils::comparison::Comparator;
+use aztec::note::note_getter_options::{NoteGetterOptions, NoteStatus, SortOrder};
+use aztec::utils::comparison::Comparator;
 ```
 
 ## Set up basic note retrieval
diff --git a/docs/docs-developers/docs/aztec-nr/framework-description/advanced/writing_efficient_contracts.md b/docs/docs-developers/docs/aztec-nr/framework-description/advanced/writing_efficient_contracts.md
index 71977ac0aeb9..833baf624d67 100644
--- a/docs/docs-developers/docs/aztec-nr/framework-description/advanced/writing_efficient_contracts.md
+++ b/docs/docs-developers/docs/aztec-nr/framework-description/advanced/writing_efficient_contracts.md
@@ -179,11 +179,11 @@ See [this example](https://github.com/noir-lang/noir-examples/blob/master/noir_b
 Consider the following example of an implementation of the `sqrt` function:
 
 ```rust
-use dep::aztec::macros::aztec;
+use aztec::macros::aztec;
 
 #[aztec]
 pub contract OptimisationExample {
-    use dep::aztec::macros::{functions::{external, initializer}, storage::storage};
+    use aztec::macros::{functions::{external, initializer}, storage::storage};
 
     #[storage]
     struct Storage<Context> {}
diff --git a/docs/docs-developers/docs/aztec-nr/framework-description/contract_structure.md b/docs/docs-developers/docs/aztec-nr/framework-description/contract_structure.md
index c699bc41486d..8213d0ecf34b 100644
--- a/docs/docs-developers/docs/aztec-nr/framework-description/contract_structure.md
+++ b/docs/docs-developers/docs/aztec-nr/framework-description/contract_structure.md
@@ -10,28 +10,18 @@ High-level structure of how Aztec smart contracts including the different compon
 
 ## Directory structure
 
-When you create a new project with `aztec new my_project`, it generates a workspace with two crates named after your project: a `my_project_contract` crate for your smart contract and a `my_project_test` crate for Noir tests.
+When you create a new project with `aztec new my_project`, it generates a single-crate Noir contract project:
 
 ```text title="layout of an aztec contract project"
 ─── my_project
-       ├── Nargo.toml                    <-- workspace root
-       ├── my_project_contract
-       │     ├── src
-       │     │     └── main.nr           <-- your contract
-       │     └── Nargo.toml              <-- contract package and dependencies
-       └── my_project_test
-             ├── src
-             │     └── lib.nr            <-- your tests
-             └── Nargo.toml              <-- test package and dependencies
+       ├── Nargo.toml                    <-- contract package and dependencies
+       └── src
+             └── main.nr                 <-- your contract
 ```
 
-The workspace root `Nargo.toml` declares both crates as workspace members. The contract code lives in `my_project_contract/src/main.nr`, and tests live in a separate `my_project_test` crate that depends on the contract crate.
+`Nargo.toml` declares the contract package (with `type = "contract"`) and its dependencies. Your contract code lives in `src/main.nr`. Noir tests using `#[test]` live alongside the contract in the same crate — see [Testing Contracts](../testing_contracts.md).
 
-You can add more contracts to an existing workspace by running `aztec new <name>` from inside the workspace directory. This creates a new `<name>_contract` and `<name>_test` crate pair and adds them to the workspace.
-
-:::warning Keep tests out of the contract crate
-Do not add `#[test]` functions to the `<name>_contract` crate. Because the contract artifact depends on everything in its crate, any change — including a test-only change — forces a full recompilation of the contract. The separate `<name>_test` crate lets you iterate on tests without rebuilding the contract. See [Testing Contracts](../testing_contracts.md#keep-tests-in-the-test-crate) for details.
-:::
+To add another contract as a sibling of an existing one, run `aztec new <name>` from the parent directory (each contract is its own crate). To initialize a contract project inside an existing empty directory instead, `cd` into it and run `aztec init` (it takes no positional argument; pass `--name <name>` if you want the package name to differ from the directory name).
 
 See the vanilla Noir docs for [more info on packages](https://noir-lang.org/docs/noir/modules_packages_crates/crates_and_packages).
 
diff --git a/docs/docs-developers/docs/aztec-nr/index.md b/docs/docs-developers/docs/aztec-nr/index.md
index 646d94a67ba1..3e42007a7d72 100644
--- a/docs/docs-developers/docs/aztec-nr/index.md
+++ b/docs/docs-developers/docs/aztec-nr/index.md
@@ -42,15 +42,15 @@ storage.votes.insert(new_vote).deliver(MessageDelivery.ONCHAIN_CONSTRAINED); //
 
 ### Flow
 
-1. Write your contract and specify your contract dependencies. Create a new project with `aztec new my_project`, which sets up a workspace with a `my_project_contract` crate and a `my_project_test` crate, with the `aztec` dependency already configured. If you need additional dependencies, add them to `my_project_contract/Nargo.toml`:
+1. Write your contract and specify your contract dependencies. Create a new project with `aztec new my_project`, which creates a single-crate Noir contract project (`Nargo.toml` + `src/main.nr`) with the `aztec` dependency already configured. If you need additional dependencies, add them to `my_project/Nargo.toml`:
 
 ```toml
-# my_project_contract/Nargo.toml
+# my_project/Nargo.toml
 [dependencies]
 aztec = { git="https://github.com/AztecProtocol/aztec-nr/", tag="#include_aztec_version", directory="aztec" }
 ```
 
-Update your `my_project_contract/src/main.nr` contract file to use the Aztec.nr macros for writing contracts.
+Update your `my_project/src/main.nr` contract file to use the Aztec.nr macros for writing contracts.
 
 #include_code setup /docs/examples/contracts/counter_contract/src/main.nr rust
 
diff --git a/docs/docs-developers/docs/aztec-nr/testing_contracts.md b/docs/docs-developers/docs/aztec-nr/testing_contracts.md
index 2d994ad6584f..eeaa18bb94ae 100644
--- a/docs/docs-developers/docs/aztec-nr/testing_contracts.md
+++ b/docs/docs-developers/docs/aztec-nr/testing_contracts.md
@@ -44,38 +44,30 @@ aztec test
 Always use `aztec test` instead of `nargo test`. The `TestEnvironment` requires the TXE (Test eXecution Environment) oracle resolver.
 :::
 
-## Keep tests in the test crate
-
-When you create a project with `aztec new` or `aztec init`, the generated workspace has two crates: `<name>_contract` and `<name>_test`. It is important that all tests live in the `<name>_test` crate, **not** in the `<name>_contract` crate.
-
-If you place `#[test]` functions inside the contract crate, `aztec compile` will emit a warning:
-
-```
-WARNING: Found tests in contract crate(s):
-  my_contract::test_something
-Tests should be in a dedicated test crate, not in the contract crate.
-```
-
-The reason is **unnecessary recompilation**: the contract artifact depends on everything inside the contract crate. If tests live there too, editing a test changes the crate and forces the contract to be recompiled and reprocessed, even though the contract logic itself has not changed. By keeping tests in a separate crate, you can iterate on tests without triggering a full contract rebuild.
-
 ## Basic test structure
 
-Tests live in `<name>_test/src/lib.nr` and import the contract crate by name (not `crate::`):
+Tests live in the same crate as your contract. `aztec new` creates a single-crate project, and the convention is to place `#[test]` functions in a `mod tests` block alongside the contract (or in submodules of the crate):
 
 ```rust
-use my_contract::MyContract;
-use aztec::{
-    protocol::address::AztecAddress,
-    test::helpers::test_environment::TestEnvironment,
-};
+use aztec::macros::aztec;
 
-#[test]
-unconstrained fn test_basic_flow() {
-    // 1. Create test environment
-    let mut env = TestEnvironment::new();
+#[aztec]
+pub contract MyContract {
+    // ...contract functions...
+}
 
-    // 2. Create accounts
-    let owner = env.create_light_account();
+mod tests {
+    use super::MyContract;
+    use aztec::test::helpers::test_environment::TestEnvironment;
+
+    #[test]
+    unconstrained fn test_basic_flow() {
+        // 1. Create test environment
+        let mut env = TestEnvironment::new();
+
+        // 2. Create accounts
+        let _owner = env.create_light_account();
+    }
 }
 ```
 
@@ -88,12 +80,14 @@ unconstrained fn test_basic_flow() {
 :::
 
 :::tip Organizing test files
-Tests live in the separate `<name>_test` crate that `aztec new` creates. You can organize them into modules:
+For larger test suites, split tests into submodules of your crate rather than keeping them all inside `main.nr`:
 
-- Split tests into modules like `<name>_test/src/transfer_tests.nr`, `<name>_test/src/auth_tests.nr`
-- Import them in `<name>_test/src/lib.nr` with `mod transfer_tests;`, `mod auth_tests;`
-- Share setup functions in `<name>_test/src/utils.nr`
-  :::
+- Create modules like `src/transfer_tests.nr`, `src/auth_tests.nr`
+- Declare them from `src/main.nr` with `mod transfer_tests;`, `mod auth_tests;`
+- Share setup functions in `src/test_utils.nr`
+
+See the [aztec-standards token contract](https://github.com/defi-wonderland/aztec-standards/tree/dev/src/token_contract) for a worked example of this layout.
+:::
 
 ## Deploying contracts
 
diff --git a/docs/docs-developers/docs/tutorials/contract_tutorials/recursive_verification.md b/docs/docs-developers/docs/tutorials/contract_tutorials/recursive_verification.md
index d8546925e6b5..acc4aec289f2 100644
--- a/docs/docs-developers/docs/tutorials/contract_tutorials/recursive_verification.md
+++ b/docs/docs-developers/docs/tutorials/contract_tutorials/recursive_verification.md
@@ -182,9 +182,9 @@ nargo test
 Expected output:
 
 ```text
-[hello_circuit] Running 1 test functions
-[hello_circuit] Testing test_main... ok
-[hello_circuit] All tests passed
+[hello_circuit] Running 1 test function
+[hello_circuit] Testing test_main ... ok
+[hello_circuit] 1 test passed
 ```
 
 **Tip**: Circuit tests run without generating proofs, making them fast for development. Use them to verify your circuit logic before the more expensive proof generation step.
@@ -208,9 +208,11 @@ The contract demonstrates several important patterns:
 Use `aztec new` to generate the contract project structure:
 
 ```bash
-aztec new contract --name ValueNotEqual
+aztec new --name ValueNotEqual contract
 ```
 
+The `aztec new` wrapper stops parsing arguments at the first positional, so `--name` must come **before** the `contract` path — otherwise the flag is silently dropped and the Nargo package ends up named `contract`. The Nargo package name (`--name`) is independent of the Noir contract name declared inside `main.nr`; the artifact filename downstream is driven by the contract name.
+
 This creates:
 
 ```tree
@@ -544,7 +546,7 @@ Expected output:
 Proof verification: SUCCESS
 Using deflattenFields to convert proof...
 VK size: 115
-Proof size: 508
+Proof size: 500
 Public inputs: 1
 Done
 ```
diff --git a/docs/docs-developers/docs/tutorials/contract_tutorials/token_contract.md b/docs/docs-developers/docs/tutorials/contract_tutorials/token_contract.md
index 251ffffe8a75..28df817287b3 100644
--- a/docs/docs-developers/docs/tutorials/contract_tutorials/token_contract.md
+++ b/docs/docs-developers/docs/tutorials/contract_tutorials/token_contract.md
@@ -41,7 +41,7 @@ Let's create a simple yarn + aztec.nr project:
 ```bash
 aztec new bob_token
 cd bob_token
-yarn init
+yarn init -y
 # This is to ensure yarn uses node_modules instead of pnp for dependency installation
 yarn config set nodeLinker node-modules
 yarn add @aztec/aztec.js@#include_aztec_version @aztec/accounts@#include_aztec_version @aztec/kv-store@#include_aztec_version @aztec/wallets@#include_aztec_version
@@ -79,6 +79,10 @@ Since we're here, let's import more specific stuff from this library:
 
 These are the different macros we need to define the visibility of functions, and some handy types and functions.
 
+:::note
+You may see "unused import" warnings from your IDE or compiler for `only_self`, `MessageDelivery`, and `Owned`. That's expected at this stage — we'll start using them in Part 2 when we add the private half of the contract.
+:::
+
 ## Building the Mental Health Token System
 
 ### The Privacy Architecture
@@ -215,6 +219,14 @@ What's this `tsx` dark magic? `tsx` is a tool that compiles and runs TypeScript
 
 :::
 
+:::tip Ephemeral PXE state
+
+We pass `{ ephemeral: true }` to `EmbeddedWallet.create`. This tells the PXE to keep its state in memory instead of writing it to `pxe_data_*` / `wallet_data_*` folders on disk. If you ever stop and restart your local network (or wipe its state), the next run starts clean instead of failing with errors like `No local block hash for block number …` because on-disk PXE state no longer matches the chain.
+
+For real applications you typically want persistent state, but for tutorials that spin up a fresh network each run, ephemeral is the safer default.
+
+:::
+
 ### 🎉 Celebrate
 
 Congratulations! You've just deployed a working token contract on Aztec! You can:
@@ -249,11 +261,15 @@ When Alice spends 40 BOB tokens at Bob's clinic:
 3. She creates a "change" note for herself (40 BOB)
 4. The consumed notes are nullified (marked as spent)
 
+:::info What is a nullifier?
+A **nullifier** is a unique, one-way tag emitted when a private note is spent. The network adds it to a nullifier tree so the same note can't be spent twice, but because the nullifier is derived from secrets only the note's owner knows, nobody can link a nullifier back to the note it invalidated. See [State Management](../../foundational-topics/state_management.md#private-state) for more.
+:::
+
 In this case, all that the network sees (including Giggle) is just "something happening to some state in some contract". How cool is that?
 
 ### Updating Storage for Privacy
 
-For something like balances, you can use a simple library called `easy_private_state` which abstracts away a custom private Note. A Note is at the core of how private state works in Aztec and you can read about it [here](../../foundational-topics/state_management.md). For now, let's add it by replacing the `[dependencies]` section in `Nargo.toml`:
+For something like balances, you can use a simple library called `balance_set` which abstracts away a custom private Note. A Note is at the core of how private state works in Aztec and you can read about it [here](../../foundational-topics/state_management.md). For now, let's add it by replacing the `[dependencies]` section in `Nargo.toml`:
 
 ```toml
 [dependencies]
@@ -373,6 +389,14 @@ aztec codegen target --outdir artifacts
 
 ## Testing the Complete Privacy System
 
+Before running the updated script, double-check your local network is still running:
+
+```bash
+aztec start --local-network
+```
+
+If you stopped it between parts of the tutorial, start it again here. Because we set `ephemeral: true` when creating the wallet, restarting the network is safe — the script won't try to reuse stale PXE state from a previous run.
+
 Now that you've implemented all the privacy features, let's update our test script to showcase the full privacy flow:
 
 ### Update Your Test Script
@@ -409,7 +433,14 @@ Let's give it a try:
 npx tsx index.ts
 ```
 
-You should see the complete privacy journey from transparent allocation to confidential usage!
+You should see the complete privacy journey from transparent allocation to confidential usage. The final pair of log lines should look like:
+
+```text
+📊 Alice has 100 public BOB tokens and 130 private BOB tokens
+📊 Bob's Clinic has 20 public BOB tokens and 50 private BOB tokens
+```
+
+If your output doesn't match, double-check that the local network is running and that you started this run with a fresh `aztec start --local-network`.
 
 ## Summary
 
diff --git a/docs/docs-developers/docs/tutorials/testing_governance_rollup_upgrade.md b/docs/docs-developers/docs/tutorials/testing_governance_rollup_upgrade.md
index ea02d87b6d64..9794f7af1f4c 100644
--- a/docs/docs-developers/docs/tutorials/testing_governance_rollup_upgrade.md
+++ b/docs/docs-developers/docs/tutorials/testing_governance_rollup_upgrade.md
@@ -359,10 +359,13 @@ aztec get-l1-addresses \
 
 ```bash
 aztec debug-rollup \
+  --rollup $NEW_ROLLUP_ADDRESS \
   --l1-rpc-urls $L1_RPC_URL \
   -c $L1_CHAIN_ID
 ```
 
+The `--rollup` flag is required; without it the command may fail trying to resolve the default rollup address.
+
 ---
 
 ## Quick Test (Empty Payload)
diff --git a/docs/examples/contracts/counter_contract/src/main.nr b/docs/examples/contracts/counter_contract/src/main.nr
index d4502f12ab60..da23da3d221f 100644
--- a/docs/examples/contracts/counter_contract/src/main.nr
+++ b/docs/examples/contracts/counter_contract/src/main.nr
@@ -26,8 +26,8 @@ pub contract Counter {
     #[initializer]
     #[external("private")]
     // We can name our initializer anything we want as long as it's marked as aztec(initializer)
-    fn initialize(headstart: u64, owner: AztecAddress) {
-        self.storage.counters.at(owner).add(headstart as u128).deliver(
+    fn initialize(headstart: u128, owner: AztecAddress) {
+        self.storage.counters.at(owner).add(headstart).deliver(
             MessageDelivery.ONCHAIN_CONSTRAINED,
         );
     }
diff --git a/docs/examples/ts/bob_token_contract/index.ts b/docs/examples/ts/bob_token_contract/index.ts
index 9b154e1279a3..6ce79a32c124 100644
--- a/docs/examples/ts/bob_token_contract/index.ts
+++ b/docs/examples/ts/bob_token_contract/index.ts
@@ -52,7 +52,9 @@ async function main() {
   // Connect to local network
   const node = createAztecNodeClient("http://localhost:8080");
 
-  const wallet = await EmbeddedWallet.create(node);
+  // `ephemeral: true` keeps PXE state in memory, so restarting the local
+  // network won't leave this script pointing at stale block hashes.
+  const wallet = await EmbeddedWallet.create(node, { ephemeral: true });
 
   const [giggleWalletData, aliceWalletData, bobClinicWalletData] =
     await getInitialTestAccountsData();