docs: fix quick start feedback items from review

Address feedback from Dominik's Quick Start review (miden-devrel#126):

- Add missing `cd my-test-project` after project creation in installation guide
- Add conditional "reuse existing project" note in accounts guide
- Add core transaction principle to Two-Transaction Model section
- Fix "private asset transfers" wording to match public NoteType usage
- Add tip blocks and section markers for duplicated code in notes guide
- Add polling loop explanation comments (notes must be committed first)
- Fix "Bob's account" to "Bob's client" for technical accuracy
- Fix "Miden assembly" to "Miden package (.masp file)" in contract guides
- Add felt! macro vs Felt type explanation
- Clarify "Miden component" as "Account component" with link
- Add "in the counter contract" for clarity
- Add Miden Testnet Explorer link after deployment

Author: Keinberger

docs/builder/get-started/accounts.md

@@ -115,7 +115,7 @@ To run the code examples in this guide, you'll need to set up a development envi
 
 ### Rust Environment
 
-Create a new Miden Rust project:
+If you already created `my-test-project` during [installation](./setup/installation), you can reuse it. Otherwise, create a new project:
 
 ```bash title=">_ Terminal"
 miden new my-project

docs/builder/get-started/notes.md

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 3
 title: Notes & Transactions
-description: Learn Miden's unique note-based transaction model for private asset transfers.
+description: Learn Miden's unique note-based transaction model for asset transfers between accounts.
 ---
 
 import { CodeTabs } from '@site/src/components';
@@ -30,6 +30,8 @@ Traditional blockchains move tokens directly between account balances. Miden use
 
 ## The Two-Transaction Model
 
+A core principle of Miden is that **a transaction is the state transition of a single account**. This means each transaction only modifies one account's state, which enables parallel execution and strong privacy guarantees.
+
 Miden uses a **two-transaction model** for asset transfers that provides enhanced privacy and scalability:
 
 ### Transaction 1: Sender Creates Note
@@ -41,7 +43,7 @@ Miden uses a **two-transaction model** for asset transfers that provides enhance
 
 ### Transaction 2: Recipient Consumes Note
 
-- **Bob's account** discovers the note (addressed to his ID)
+- **Bob's client** discovers the note (addressed to his ID)
 - Bob creates a transaction to consume the note
 - Tokens move from the note into Bob's vault
 - Bob's balance increases, note is nullified
@@ -294,6 +296,10 @@ After minting creates a P2ID note containing tokens, the recipient must **consum
 
 Here's how to consume notes programmatically:
 
+:::tip
+This is a complete, self-contained example that includes the setup and minting steps from the previous section. **The new consume logic starts at the `CONSUMING P2ID NOTES` comment.**
+:::
+
 <CodeTabs
 tsFilename="src/lib/consume.ts"
 rustFilename="integration/src/bin/consume.rs"
@@ -422,6 +428,8 @@ async fn main() -> anyhow::Result<()> {
     // CONSUMING P2ID NOTES
     //------------------------------------------------------------
 
+    // Public notes must be committed to a block before they can be consumed.
+    // Poll until the network includes our mint note in a block.
     loop {
         // Sync state to get the latest block
         client.sync_state().await?;
@@ -532,6 +540,8 @@ export async function demo() {
 
     await client.syncState();
 
+    // Public notes must be committed to a block before they can be consumed.
+    // Poll until the network includes our mint note in a block.
     let consumableNotes: ConsumableNoteRecord[] = [];
     while (consumableNotes.length === 0) {
         // Find consumable notes
@@ -600,6 +610,10 @@ This approach means Alice and Bob's transactions are completely separate and unl
 
 Let's implement the complete flow - mint, consume, then send:
 
+:::tip
+This is a complete, self-contained example that includes all previous steps. **The new send logic starts at the `SENDING TOKENS TO BOB` comment.**
+:::
+
 <CodeTabs
 tsFilename="src/lib/send.ts"
 rustFilename="integration/src/bin/send.rs"
@@ -728,6 +742,8 @@ async fn main() -> anyhow::Result<()> {
     // CONSUMING P2ID NOTES
     //------------------------------------------------------------
 
+    // Public notes must be committed to a block before they can be consumed.
+    // Poll until the network includes our mint note in a block.
     loop {
         // Sync state to get the latest block
         client.sync_state().await?;
@@ -872,6 +888,8 @@ export async function demo() {
 
     await client.syncState();
 
+    // Public notes must be committed to a block before they can be consumed.
+    // Poll until the network includes our mint note in a block.
     let consumableNotes: ConsumableNoteRecord[] = [];
     while (consumableNotes.length === 0) {
         // Find consumable notes
@@ -946,7 +964,7 @@ Send 100 tokens to Bob note transaction ID: "0x51ac27474ade3a54adadd50db6c2b9a2e
 
 **Miden's Note-Based Transaction Model:**
 
-- **Notes** enable private asset transfers between accounts
+- **Notes** enable asset transfers between accounts (both public and private)
 - **Two-transaction model** provides privacy and parallelization benefits
 - **Zero-knowledge proofs** validate transaction execution without revealing details
 - **P2ID notes** target specific recipients using their account IDs

docs/builder/get-started/setup/installation.md

@@ -149,9 +149,10 @@ Test by creating a new project:
 
 ```bash title=">_ Terminal"
 miden new my-test-project
+cd my-test-project
 ```
 
-If successful, you'll see a new directory with Miden project files.
+If successful, you'll see a new directory with Miden project files. The `cd` command enters the project directory, which you'll need for the following guides.
 
 ### Troubleshooting
 

docs/builder/get-started/your-first-smart-contract/create.md

@@ -53,7 +53,7 @@ cd ../increment-note
 miden build
 ```
 
-This compiles the Rust contract code into Miden assembly, making it ready for deployment and interaction.
+This compiles the Rust contract code into a Miden package (`.masp` file), making it ready for deployment and interaction.
 
 ## Understanding the Counter Account Contract
 
@@ -123,6 +123,7 @@ use miden::{component, felt, Felt, StorageMap, StorageMapAccess, Word};
 These imports provide:
 
 - **`component`**: Macro for defining contract components
+- **`felt`**: Macro for creating `Felt` literals (e.g., `felt!(1)`)
 - **`Felt`/`Word`**: Miden's native field element and word types
 - **`StorageMap`**: Key-value storage within account storage slots
 - **`StorageMapAccess`**: Needed for reading storage values (`get_count` function)
@@ -138,7 +139,7 @@ struct CounterContract {
 }
 ```
 
-The `#[component]` attribute marks this as a Miden component. The `count_map` field is a `StorageMap` stored in a named storage slot of the account. In v0.13, storage slots are identified by name rather than explicit index numbers — the slot name is derived automatically from the component's package name and field name (e.g., `miden::component::miden_counter_account::count_map`).
+The `#[component]` attribute marks this as a Miden [Account component](/core-concepts/miden-base/account). The `count_map` field is a `StorageMap` stored in a named storage slot of the account. In v0.13, storage slots are identified by name rather than explicit index numbers — the slot name is derived automatically from the component's package name and field name (e.g., `miden::component::miden_counter_account::count_map`).
 
 **Important**: Storage slots in Miden hold `Word` values, which are composed of four field elements (`Felt`). Each `Felt` is a 64-bit unsigned integer (u64). The `StorageMap` provides a key-value interface within a single storage slot, allowing you to store multiple key-value pairs within the four-element word structure.
 
@@ -158,7 +159,7 @@ The `CounterContract` implementation defines the external interface that other c
 let key = Word::from_u64_unchecked(0, 0, 0, 1);
 ```
 
-Both functions use the same fixed key `[0, 0, 0, 1]` to store and retrieve the counter value within the storage map. The `Word::from_u64_unchecked` constructor creates a `Word` from four `u64` values. This demonstrates a simple but effective storage pattern.
+Both functions in the counter contract use the same fixed key `[0, 0, 0, 1]` to store and retrieve the counter value within the storage map. The `Word::from_u64_unchecked` constructor creates a `Word` from four `u64` values. This demonstrates a simple but effective storage pattern.
 
 ## Understanding the Increment Note Script
 

docs/builder/get-started/your-first-smart-contract/deploy.md

@@ -93,7 +93,7 @@ Account delta: AccountDelta { account_id: V0(AccountIdV0 { prefix: 7255964780328
 
 </details>
 
-Congratulations, you have successfully deployed the Counter Contract to the Miden Testnet, and incremented its count by one!
+Congratulations, you have successfully deployed the Counter Contract to the Miden Testnet, and incremented its count by one! You can view your account on the [Miden Testnet Explorer](https://testnet.midenscan.com).
 
 ### What Happens During Execution
 
@@ -149,8 +149,8 @@ let note_package = Arc::new(
 The `build_project_in_dir()` function:
 
 - Takes the path to your contract's Rust source code
-- Compiles the Rust code into Miden assembly
-- Generates a package containing the compiled contract bytecode and metadata
+- Compiles the Rust code into a Miden package (`.masp` file)
+- The package contains the compiled contract bytecode and metadata
 - This is equivalent to manually running `miden build` in each contract directory
 
 These packages contain all the information needed to deploy and interact with your contracts on the Miden network.

versioned_docs/version-0.13/builder/get-started/accounts.md

@@ -115,7 +115,7 @@ To run the code examples in this guide, you'll need to set up a development envi
 
 ### Rust Environment
 
-Create a new Miden Rust project:
+If you already created `my-test-project` during [installation](./setup/installation), you can reuse it. Otherwise, create a new project:
 
 ```bash title=">_ Terminal"
 miden new my-project

versioned_docs/version-0.13/builder/get-started/notes.md

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 3
 title: Notes & Transactions
-description: Learn Miden's unique note-based transaction model for private asset transfers.
+description: Learn Miden's unique note-based transaction model for asset transfers between accounts.
 ---
 
 import { CodeTabs } from '@site/src/components';
@@ -30,6 +30,8 @@ Traditional blockchains move tokens directly between account balances. Miden use
 
 ## The Two-Transaction Model
 
+A core principle of Miden is that **a transaction is the state transition of a single account**. This means each transaction only modifies one account's state, which enables parallel execution and strong privacy guarantees.
+
 Miden uses a **two-transaction model** for asset transfers that provides enhanced privacy and scalability:
 
 ### Transaction 1: Sender Creates Note
@@ -41,7 +43,7 @@ Miden uses a **two-transaction model** for asset transfers that provides enhance
 
 ### Transaction 2: Recipient Consumes Note
 
-- **Bob's account** discovers the note (addressed to his ID)
+- **Bob's client** discovers the note (addressed to his ID)
 - Bob creates a transaction to consume the note
 - Tokens move from the note into Bob's vault
 - Bob's balance increases, note is nullified
@@ -294,6 +296,10 @@ After minting creates a P2ID note containing tokens, the recipient must **consum
 
 Here's how to consume notes programmatically:
 
+:::tip
+This is a complete, self-contained example that includes the setup and minting steps from the previous section. **The new consume logic starts at the `CONSUMING P2ID NOTES` comment.**
+:::
+
 <CodeTabs
 tsFilename="src/lib/consume.ts"
 rustFilename="integration/src/bin/consume.rs"
@@ -422,6 +428,8 @@ async fn main() -> anyhow::Result<()> {
     // CONSUMING P2ID NOTES
     //------------------------------------------------------------
 
+    // Public notes must be committed to a block before they can be consumed.
+    // Poll until the network includes our mint note in a block.
     loop {
         // Sync state to get the latest block
         client.sync_state().await?;
@@ -532,6 +540,8 @@ export async function demo() {
 
     await client.syncState();
 
+    // Public notes must be committed to a block before they can be consumed.
+    // Poll until the network includes our mint note in a block.
     let consumableNotes: ConsumableNoteRecord[] = [];
     while (consumableNotes.length === 0) {
         // Find consumable notes
@@ -600,6 +610,10 @@ This approach means Alice and Bob's transactions are completely separate and unl
 
 Let's implement the complete flow - mint, consume, then send:
 
+:::tip
+This is a complete, self-contained example that includes all previous steps. **The new send logic starts at the `SENDING TOKENS TO BOB` comment.**
+:::
+
 <CodeTabs
 tsFilename="src/lib/send.ts"
 rustFilename="integration/src/bin/send.rs"
@@ -728,6 +742,8 @@ async fn main() -> anyhow::Result<()> {
     // CONSUMING P2ID NOTES
     //------------------------------------------------------------
 
+    // Public notes must be committed to a block before they can be consumed.
+    // Poll until the network includes our mint note in a block.
     loop {
         // Sync state to get the latest block
         client.sync_state().await?;
@@ -872,6 +888,8 @@ export async function demo() {
 
     await client.syncState();
 
+    // Public notes must be committed to a block before they can be consumed.
+    // Poll until the network includes our mint note in a block.
     let consumableNotes: ConsumableNoteRecord[] = [];
     while (consumableNotes.length === 0) {
         // Find consumable notes
@@ -946,7 +964,7 @@ Send 100 tokens to Bob note transaction ID: "0x51ac27474ade3a54adadd50db6c2b9a2e
 
 **Miden's Note-Based Transaction Model:**
 
-- **Notes** enable private asset transfers between accounts
+- **Notes** enable asset transfers between accounts (both public and private)
 - **Two-transaction model** provides privacy and parallelization benefits
 - **Zero-knowledge proofs** validate transaction execution without revealing details
 - **P2ID notes** target specific recipients using their account IDs

versioned_docs/version-0.13/builder/get-started/setup/installation.md

@@ -166,9 +166,10 @@ Test by creating a new project:
 
 ```bash title=">_ Terminal"
 miden new my-test-project
+cd my-test-project
 ```
 
-If successful, you'll see a new directory with Miden project files.
+If successful, you'll see a new directory with Miden project files. The `cd` command enters the project directory, which you'll need for the following guides.
 
 ### Troubleshooting
 

versioned_docs/version-0.13/builder/get-started/your-first-smart-contract/create.md

@@ -53,7 +53,7 @@ cd ../increment-note
 miden build
 ```
 
-This compiles the Rust contract code into Miden assembly, making it ready for deployment and interaction.
+This compiles the Rust contract code into a Miden package (`.masp` file), making it ready for deployment and interaction.
 
 ## Understanding the Counter Account Contract
 
@@ -123,6 +123,7 @@ use miden::{component, felt, Felt, StorageMap, StorageMapAccess, Word};
 These imports provide:
 
 - **`component`**: Macro for defining contract components
+- **`felt`**: Macro for creating `Felt` literals (e.g., `felt!(1)`)
 - **`Felt`/`Word`**: Miden's native field element and word types
 - **`StorageMap`**: Key-value storage within account storage slots
 - **`StorageMapAccess`**: Needed for reading storage values (`get_count` function)
@@ -138,7 +139,7 @@ struct CounterContract {
 }
 ```
 
-The `#[component]` attribute marks this as a Miden component. The `count_map` field is a `StorageMap` stored in a named storage slot of the account. In v0.13, storage slots are identified by name rather than explicit index numbers — the slot name is derived automatically from the component's package name and field name (e.g., `miden::component::miden_counter_account::count_map`).
+The `#[component]` attribute marks this as a Miden [Account component](/core-concepts/miden-base/account). The `count_map` field is a `StorageMap` stored in a named storage slot of the account. In v0.13, storage slots are identified by name rather than explicit index numbers — the slot name is derived automatically from the component's package name and field name (e.g., `miden::component::miden_counter_account::count_map`).
 
 **Important**: Storage slots in Miden hold `Word` values, which are composed of four field elements (`Felt`). Each `Felt` is a 64-bit unsigned integer (u64). The `StorageMap` provides a key-value interface within a single storage slot, allowing you to store multiple key-value pairs within the four-element word structure.
 
@@ -158,7 +159,7 @@ The `CounterContract` implementation defines the external interface that other c
 let key = Word::from_u64_unchecked(0, 0, 0, 1);
 ```
 
-Both functions use the same fixed key `[0, 0, 0, 1]` to store and retrieve the counter value within the storage map. The `Word::from_u64_unchecked` constructor creates a `Word` from four `u64` values. This demonstrates a simple but effective storage pattern.
+Both functions in the counter contract use the same fixed key `[0, 0, 0, 1]` to store and retrieve the counter value within the storage map. The `Word::from_u64_unchecked` constructor creates a `Word` from four `u64` values. This demonstrates a simple but effective storage pattern.
 
 ## Understanding the Increment Note Script
 

versioned_docs/version-0.13/builder/get-started/your-first-smart-contract/deploy.md

@@ -93,7 +93,7 @@ Account delta: AccountDelta { account_id: V0(AccountIdV0 { prefix: 7255964780328
 
 </details>
 
-Congratulations, you have successfully deployed the Counter Contract to the Miden Testnet, and incremented its count by one!
+Congratulations, you have successfully deployed the Counter Contract to the Miden Testnet, and incremented its count by one! You can view your account on the [Miden Testnet Explorer](https://testnet.midenscan.com).
 
 ### What Happens During Execution
 
@@ -149,8 +149,8 @@ let note_package = Arc::new(
 The `build_project_in_dir()` function:
 
 - Takes the path to your contract's Rust source code
-- Compiles the Rust code into Miden assembly
-- Generates a package containing the compiled contract bytecode and metadata
+- Compiles the Rust code into a Miden package (`.masp` file)
+- The package contains the compiled contract bytecode and metadata
 - This is equivalent to manually running `miden build` in each contract directory
 
 These packages contain all the information needed to deploy and interact with your contracts on the Miden network.