Merge branch 'main' of https://github.com/0xMiden/miden-docs into brian/miden-smart-contract

Author: BrianSeong99

.github/workflows/cut-versions.yml

@@ -4,7 +4,7 @@
 #
 # v0.4 Information Architecture:
 #   - Design docs (miden-base, miden-vm, compiler, miden-node) → docs/design/
-#   - Builder docs (miden-tutorials, miden-client) → docs/builder/
+#   - Builder docs (miden-tutorials, miden-client) → docs/builder/develop/tutorials/, docs/builder/tools/client/
 #
 # Workflow responsibilities:
 #   1. Check out external repos at pinned refs
@@ -34,8 +34,9 @@ on:
       compiler_ref: { required: false }
       miden_tutorials_ref: { required: false }
 
-  # Optional: auto-run when manifest changes (enable after you trust the flow)
+  # Auto-run when manifest changes on a branch (NOT main — prevents re-triggering on merge)
   push:
+    branches-ignore: [main]
     paths:
       - ".release/release-manifest.yml"
 
@@ -150,7 +151,8 @@ jobs:
 
           # Clean directories that will be re-synced (v0.4 nested paths)
           rm -rf docs/design/miden-base docs/design/miden-vm docs/design/miden-node docs/design/compiler
-          rm -rf docs/builder/tutorials docs/builder/client
+          rm -rf docs/builder/tools/client
+          # Note: docs/builder/develop/tutorials is NOT fully cleaned to preserve local tutorials (e.g. miden-bank)
 
           # Design docs → docs/design/*
           if [ -d "vendor/miden-base/docs/src" ]; then
@@ -178,16 +180,17 @@ jobs:
           fi
 
           # Builder docs → docs/builder/*
+          # Sync miden-tutorials into develop/tutorials (local tutorials are preserved)
           if [ -d "vendor/miden-tutorials/docs/src" ]; then
-            mkdir -p docs/builder/tutorials
-            cp -r vendor/miden-tutorials/docs/src/* docs/builder/tutorials/
-            echo "Synced miden-tutorials → docs/builder/tutorials"
+            mkdir -p docs/builder/develop/tutorials
+            cp -r vendor/miden-tutorials/docs/src/* docs/builder/develop/tutorials/
+            echo "Synced miden-tutorials → docs/builder/develop/tutorials"
           fi
 
-          if [ -d "vendor/miden-client/docs/src" ]; then
-            mkdir -p docs/builder/client
-            cp -r vendor/miden-client/docs/src/* docs/builder/client/
-            echo "Synced miden-client → docs/builder/client"
+          if [ -d "vendor/miden-client/docs/external/src" ]; then
+            mkdir -p docs/builder/tools/client
+            cp -r vendor/miden-client/docs/external/src/* docs/builder/tools/client/
+            echo "Synced miden-client → docs/builder/tools/client"
           fi
 
           echo "Content aggregation complete. Final docs structure:"
@@ -196,6 +199,8 @@ jobs:
           ls -la docs/design/ || true
           echo "Builder subdirs:"
           ls -la docs/builder/ || true
+          echo "Tutorials subdirs:"
+          ls -la docs/builder/develop/tutorials/ || true
 
       - name: Cut version snapshot
         run: |
@@ -214,8 +219,8 @@ jobs:
           rm -rf docs/design/miden-vm
           rm -rf docs/design/miden-node
           rm -rf docs/design/compiler
-          rm -rf docs/builder/tutorials
-          rm -rf docs/builder/client
+          rm -rf docs/builder/tools/client
+          # Note: tutorials live in docs/builder/develop/tutorials/ (authored content, not cleaned)
 
       - name: Commit snapshots
         run: |

.github/workflows/deploy-docs.yml

@@ -147,7 +147,7 @@ jobs:
 
           # Clean directories that will be re-synced (v0.4 nested paths)
           rm -rf docs/design/miden-base docs/design/miden-vm docs/design/miden-node docs/design/compiler
-          rm -rf docs/builder/client
+          rm -rf docs/builder/tools/client
           # Note: docs/builder/develop/tutorials is NOT fully cleaned to preserve local tutorials (e.g. miden-bank)
 
           # Design docs → docs/design/*
@@ -184,9 +184,9 @@ jobs:
           fi
 
           if [ -d "vendor/miden-client/docs/external/src" ]; then
-            mkdir -p docs/builder/client
-            cp -r vendor/miden-client/docs/external/src/* docs/builder/client/
-            echo "Synced miden-client → docs/builder/client"
+            mkdir -p docs/builder/tools/client
+            cp -r vendor/miden-client/docs/external/src/* docs/builder/tools/client/
+            echo "Synced miden-client → docs/builder/tools/client"
           fi
 
           echo "Content aggregation complete. Final docs structure:"

.release/release-manifest.yml

@@ -1,9 +1,9 @@
-version: "0.12 (stable)" # the label to snapshot (used if no manual override)
+version: "0.13" # the label to snapshot (used if no manual override)
 refs: # exact, immutable refs per source repo (tags or release branches)
-  miden-base: "refs/tags/v0.12.3"
-  miden-node: "refs/tags/v0.12.3"
-  miden-client: "refs/tags/v0.12.3"
+  miden-base: "refs/tags/v0.13.3"
+  miden-node: "refs/tags/v0.13.4"
+  miden-client: "refs/tags/v0.13.0"
   miden-tutorials: "refs/heads/main"
-  miden-vm: "refs/tags/v0.19.1"
-  compiler: "refs/tags/0.5.1"
-next_version: "0.13"
+  miden-vm: "refs/tags/v0.20.6"
+  compiler: "refs/tags/0.7.0"
+next_version: "0.14"

README.md

@@ -152,7 +152,11 @@ refs:
 
 #### 2. Run the Version Cut Workflow
 
-Trigger `.github/workflows/cut-versions.yml` (manually or via push to manifest):
+> **Important:** Run this workflow on a **branch** (not `main`). The workflow commits the snapshot
+> to the current branch, allowing you to review changes in a PR before merging to `main`.
+> The workflow is configured to NOT run automatically when changes are pushed to `main`.
+
+Trigger `.github/workflows/cut-versions.yml` on a branch (manually via `workflow_dispatch`, or by pushing the updated manifest to the branch):
 
 The workflow executes these steps:
 1. **Checkout external repos** at pinned refs
@@ -178,7 +182,7 @@ The `.github/workflows/deploy-docs.yml` workflow:
 1. Checks out this repository and all external source repos
 2. Ingests external docs into v0.4 IA structure:
    - Design docs → `docs/design/miden-base/`, `miden-vm/`, `compiler/`, `miden-node/`
-   - Builder docs → `docs/builder/tutorials/`, `docs/builder/client/`
+   - Builder docs → `docs/builder/develop/tutorials/`, `docs/builder/tools/client/`
 3. Runs `npm run build` to generate the static site
 4. Deploys to GitHub Pages at `docs.miden.xyz`
 

docs/builder/develop/tutorials/rust-compiler/miden-bank/00-project-setup.md

@@ -34,7 +34,15 @@ miden --version
 <summary>Expected output</summary>
 
 ```text
-miden-cli 0.8.x
+The Miden toolchain porcelain:
+
+Environment:
+- cargo version: cargo 1.93.0 (083ac5135 2025-12-15).
+
+Midenup:
+- midenup + miden version: 0.1.0.
+- active toolchain version: 0.20.3.
+- ...
 ```
 
 </details>
@@ -90,7 +98,7 @@ edition = "2021"
 crate-type = ["cdylib"]
 
 [dependencies]
-miden = { workspace = true }
+miden = { version = "0.10" }
 
 [package.metadata.component]
 package = "miden:bank-account"
@@ -132,12 +140,12 @@ use miden::*;
 struct Bank {
     /// Tracks whether the bank has been initialized (deposits enabled).
     /// Word layout: [is_initialized (0 or 1), 0, 0, 0]
-    #[storage(slot(0), description = "initialized")]
+    #[storage(description = "initialized")]
     initialized: Value,
 
     /// Maps depositor AccountId -> balance (as Felt).
     /// We'll use this to track user balances in Part 1.
-    #[storage(slot(1), description = "balances")]
+    #[storage(description = "balances")]
     balances: StorageMap,
 }
 
@@ -185,18 +193,24 @@ Update the root `Cargo.toml` to reflect our renamed contract:
 
 ```toml title="Cargo.toml"
 [workspace]
-resolver = "2"
-
 members = [
-    "contracts/bank-account",
-    "contracts/increment-note",  # We'll replace this later
-    "integration",
+    "integration"
+]
+exclude = [
+    "contracts/",
 ]
+resolver = "2"
+
+[workspace.package]
+edition = "2021"
 
 [workspace.dependencies]
-miden = { version = "0.8" }
 ```
 
+:::info Contracts Are Excluded
+In v0.13, contracts are excluded from the Cargo workspace and built independently by `cargo miden`. Each contract specifies its own `miden` dependency directly. Only the `integration` crate remains a workspace member.
+:::
+
 ## Step 5: Build and Verify
 
 Let's verify everything compiles correctly:
@@ -231,7 +245,7 @@ Let's create a simple test to verify the bank account can be created. Create a n
 use integration::helpers::{
     build_project_in_dir, create_testing_account_from_package, AccountCreationConfig,
 };
-use miden_client::account::{StorageMap, StorageSlot};
+use miden_client::account::{StorageMap, StorageSlot, StorageSlotName};
 use miden_client::Word;
 use std::{path::Path, sync::Arc};
 
@@ -243,13 +257,21 @@ async fn test_bank_account_builds_and_loads() -> anyhow::Result<()> {
         true,
     )?);
 
-    // Create the bank account with initial storage
-    // Slot 0: initialized flag (Value, starts as [0, 0, 0, 0])
-    // Slot 1: balances map (StorageMap, starts empty)
+    // Create named storage slots matching the contract's storage layout
+    let initialized_slot =
+        StorageSlotName::new("miden::component::miden_bank_account::initialized")
+            .expect("Valid slot name");
+    let balances_slot =
+        StorageSlotName::new("miden::component::miden_bank_account::balances")
+            .expect("Valid slot name");
+
     let bank_cfg = AccountCreationConfig {
         storage_slots: vec![
-            StorageSlot::Value(Word::default()),
-            StorageSlot::Map(StorageMap::with_entries([])?),
+            StorageSlot::with_value(initialized_slot, Word::default()),
+            StorageSlot::with_map(
+                balances_slot,
+                StorageMap::with_entries([]).expect("Empty storage map"),
+            ),
         ],
         ..Default::default()
     };
@@ -268,7 +290,7 @@ async fn test_bank_account_builds_and_loads() -> anyhow::Result<()> {
 Run the test from the project root:
 
 ```bash title=">_ Terminal"
-cargo test --package integration part0_setup_test -- --nocapture
+cargo test --package integration test_bank_account_builds_and_loads -- --nocapture
 ```
 
 <details>
@@ -317,7 +339,7 @@ Your bank can be created, but doesn't do anything useful yet. In the next parts,
 
 1. **`miden new`** creates a complete project workspace with contracts and integration folders
 2. **Account components** are defined with `#[component]` on a struct
-3. **Storage slots** are declared with `#[storage(slot(N))]` attributes
+3. **Storage slots** are declared with `#[storage(description = "...")]` attributes (the compiler auto-assigns slot numbers)
 4. **`miden build`** compiles Rust to Miden Assembly (.masp package)
 5. **Tests verify** that your code works before moving on