Merge remote-tracking branch 'origin/main' into brian/issue-177-sdk-fixes

# Conflicts:
#	static/llms.txt
#	static/skill.md

Author: BrianSeong99

.github/workflows/cut-versions.yml

@@ -3,7 +3,7 @@
 # This workflow ingests external repos and creates versioned snapshots.
 #
 # v0.4 Information Architecture:
-#   - Design docs (miden-base, miden-vm, compiler, miden-node) → docs/design/
+#   - Core Concepts docs (miden-base, miden-vm, compiler, miden-node) → docs/core-concepts/
 #   - Builder docs (miden-tutorials, miden-client) → docs/builder/develop/tutorials/, docs/builder/tools/client/
 #
 # Workflow responsibilities:
@@ -150,33 +150,33 @@ jobs:
           echo "Aggregating vendor docs into v0.4 IA structure..."
 
           # 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/core-concepts/miden-base docs/core-concepts/miden-vm docs/core-concepts/miden-node docs/core-concepts/compiler
           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/*
+          # Core Concepts docs → docs/core-concepts/*
           if [ -d "vendor/miden-base/docs/src" ]; then
-            mkdir -p docs/design/miden-base
-            cp -r vendor/miden-base/docs/src/* docs/design/miden-base/
-            echo "Synced miden-base → docs/design/miden-base"
+            mkdir -p docs/core-concepts/miden-base
+            cp -r vendor/miden-base/docs/src/* docs/core-concepts/miden-base/
+            echo "Synced miden-base → docs/core-concepts/miden-base"
           fi
 
           if [ -d "vendor/miden-vm/docs/src" ]; then
-            mkdir -p docs/design/miden-vm
-            cp -r vendor/miden-vm/docs/src/* docs/design/miden-vm/
-            echo "Synced miden-vm → docs/design/miden-vm"
+            mkdir -p docs/core-concepts/miden-vm
+            cp -r vendor/miden-vm/docs/src/* docs/core-concepts/miden-vm/
+            echo "Synced miden-vm → docs/core-concepts/miden-vm"
           fi
 
           if [ -d "vendor/miden-node/docs/external/src" ]; then
-            mkdir -p docs/design/miden-node
-            cp -r vendor/miden-node/docs/external/src/* docs/design/miden-node/
-            echo "Synced miden-node → docs/design/miden-node"
+            mkdir -p docs/core-concepts/miden-node
+            cp -r vendor/miden-node/docs/external/src/* docs/core-concepts/miden-node/
+            echo "Synced miden-node → docs/core-concepts/miden-node"
           fi
 
           if [ -d "vendor/compiler/docs/external/src" ]; then
-            mkdir -p docs/design/compiler
-            cp -r vendor/compiler/docs/external/src/* docs/design/compiler/
-            echo "Synced compiler → docs/design/compiler"
+            mkdir -p docs/core-concepts/compiler
+            cp -r vendor/compiler/docs/external/src/* docs/core-concepts/compiler/
+            echo "Synced compiler → docs/core-concepts/compiler"
           fi
 
           # Builder docs → docs/builder/*
@@ -195,8 +195,8 @@ jobs:
 
           echo "Content aggregation complete. Final docs structure:"
           ls -la docs/
-          echo "Design subdirs:"
-          ls -la docs/design/ || true
+          echo "Core Concepts subdirs:"
+          ls -la docs/core-concepts/ || true
           echo "Builder subdirs:"
           ls -la docs/builder/ || true
           echo "Tutorials subdirs:"
@@ -209,16 +209,16 @@ jobs:
           npm run docusaurus -- docs:version "$VERSION"
 
       # CRITICAL: Clean up docs/ to maintain canonical-source architecture
-      # docs/ must only contain authored content (builder/, design/ landing pages)
+      # docs/ must only contain authored content (builder/, core-concepts/ landing pages)
       # All ingested content lives in versioned_docs/ after versioning
       - name: Clean up (delete vendor and ingested docs)
         run: |
           rm -rf vendor
           # Clean v0.4 nested paths
-          rm -rf docs/design/miden-base
-          rm -rf docs/design/miden-vm
-          rm -rf docs/design/miden-node
-          rm -rf docs/design/compiler
+          rm -rf docs/core-concepts/miden-base
+          rm -rf docs/core-concepts/miden-vm
+          rm -rf docs/core-concepts/miden-node
+          rm -rf docs/core-concepts/compiler
           rm -rf docs/builder/tools/client
           # Note: tutorials live in docs/builder/develop/tutorials/ (authored content, not cleaned)
 

.github/workflows/deploy-docs.yml

@@ -138,41 +138,41 @@ jobs:
 
       # ============================================================
       # v0.4 IA: Aggregate into nested structure
-      #   - Design docs (miden-base, miden-vm, compiler, miden-node) → docs/design/
+      #   - Core Concepts docs (miden-base, miden-vm, compiler, miden-node) → docs/core-concepts/
       #   - Builder docs (miden-tutorials, miden-client) → docs/builder/
       # ============================================================
       - name: Aggregate docs into single docs tree
         run: |
           echo "Aggregating vendor docs into v0.4 IA structure..."
 
           # 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/core-concepts/miden-base docs/core-concepts/miden-vm docs/core-concepts/miden-node docs/core-concepts/compiler
           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/*
+          # Core Concepts docs → docs/core-concepts/*
           if [ -d "vendor/miden-base/docs/src" ]; then
-            mkdir -p docs/design/miden-base
-            cp -r vendor/miden-base/docs/src/* docs/design/miden-base/
-            echo "Synced miden-base → docs/design/miden-base"
+            mkdir -p docs/core-concepts/miden-base
+            cp -r vendor/miden-base/docs/src/* docs/core-concepts/miden-base/
+            echo "Synced miden-base → docs/core-concepts/miden-base"
           fi
 
           if [ -d "vendor/miden-vm/docs/src" ]; then
-            mkdir -p docs/design/miden-vm
-            cp -r vendor/miden-vm/docs/src/* docs/design/miden-vm/
-            echo "Synced miden-vm → docs/design/miden-vm"
+            mkdir -p docs/core-concepts/miden-vm
+            cp -r vendor/miden-vm/docs/src/* docs/core-concepts/miden-vm/
+            echo "Synced miden-vm → docs/core-concepts/miden-vm"
           fi
 
           if [ -d "vendor/miden-node/docs/external/src" ]; then
-            mkdir -p docs/design/miden-node
-            cp -r vendor/miden-node/docs/external/src/* docs/design/miden-node/
-            echo "Synced miden-node → docs/design/miden-node"
+            mkdir -p docs/core-concepts/miden-node
+            cp -r vendor/miden-node/docs/external/src/* docs/core-concepts/miden-node/
+            echo "Synced miden-node → docs/core-concepts/miden-node"
           fi
 
           if [ -d "vendor/compiler/docs/external/src" ]; then
-            mkdir -p docs/design/compiler
-            cp -r vendor/compiler/docs/external/src/* docs/design/compiler/
-            echo "Synced compiler → docs/design/compiler"
+            mkdir -p docs/core-concepts/compiler
+            cp -r vendor/compiler/docs/external/src/* docs/core-concepts/compiler/
+            echo "Synced compiler → docs/core-concepts/compiler"
           fi
 
           # Builder docs → docs/builder/*
@@ -191,8 +191,8 @@ jobs:
 
           echo "Content aggregation complete. Final docs structure:"
           ls -la docs/
-          echo "Design subdirs:"
-          ls -la docs/design/ || true
+          echo "Core Concepts subdirs:"
+          ls -la docs/core-concepts/ || true
           echo "Builder subdirs:"
           ls -la docs/builder/ || true
           echo "Tutorials subdirs:"

CLAUDE.md

@@ -4,9 +4,9 @@
 Docusaurus v3 documentation site for the Miden ecosystem. Deployed at docs.miden.xyz.
 
 ## Key Directories
-- `docs/` — current docs (design, builder/)
+- `docs/` — current docs (core-concepts, builder/)
 - `docs/builder/` — developer-facing: tools, develop, quick-start, smart-contracts, migration
-- `docs/design/` — protocol design docs
+- `docs/core-concepts/` — protocol design docs
 - `versioned_docs/` — pinned version snapshots
 - `src/` — custom React components, pages, CSS
 - `static/` — images, assets

README.md

@@ -23,7 +23,7 @@ flowchart TD
             BuilderRef["builder/reference/"]
             BuilderFAQ["builder/faq.md"]
             BuilderGlossary["builder/glossary.md"]
-            DesignLanding["design/index.md"]
+            DesignLanding["core-concepts/index.md"]
             Intro["intro.md"]
         end
 
@@ -88,7 +88,7 @@ flowchart TD
 | Category | Location | Source | Example |
 |----------|----------|--------|---------|
 | **Authored** | `docs/builder/` | Written in this repo | `docs/builder/quick-start/`, `docs/builder/faq.md` |
-| **Ingested (live)** | `docs/design/`, `docs/builder/` | External repos @ next | `docs/design/miden-base/`, `docs/builder/tutorials/` |
+| **Ingested (live)** | `docs/core-concepts/`, `docs/builder/` | External repos @ next | `docs/core-concepts/miden-base/`, `docs/builder/tutorials/` |
 | **Ingested (versioned)** | `versioned_docs/` | External repos @ release tags | `versioned_docs/version-0.12/miden-base/` |
 | **Snapshots** | `versioned_docs/` | Frozen via `docs:version` | All versioned content |
 
@@ -181,7 +181,7 @@ Deployment is **automatic** on push to `main`.
 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/`
+   - Core Concepts docs → `docs/core-concepts/miden-base/`, `miden-vm/`, `compiler/`, `miden-node/`
    - 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`
@@ -209,7 +209,7 @@ The build uses:
 ### ❌ DON'T
 
 - **Never** manually copy external content into `docs/` (use CI/CD ingestion)
-- **Never** create root-level `docs/miden-base/`, `docs/miden-vm/`, etc. (use nested paths in `docs/design/`)
+- **Never** create root-level `docs/miden-base/`, `docs/miden-vm/`, etc. (use nested paths in `docs/core-concepts/`)
 - **Never** edit `versioned_docs/` directly (snapshots are immutable)
 - **Never** create a root-level `docs/quick-start/` (Quick Start lives in `docs/builder/`)
 

docs/builder/quick-start/your-first-smart-contract/create.md

@@ -228,7 +228,7 @@ impl IncrementNote {
 
 The struct definition (`IncrementNote`) provides a named type for the note script. Unlike account contracts, note scripts don't store persistent data — the struct serves as the entry point container.
 
-Learn more about [note scripts in the Miden documentation](/miden-base/note/).
+Learn more about [note scripts in the Miden documentation](/core-concepts/miden-base/note/).
 
 #### The Note Script Function
 

docs/builder/quick-start/your-first-smart-contract/deploy.md

@@ -42,7 +42,7 @@ The integration folder serves two essential functions in Miden development:
 Think of the scripts in `src/bin/` as Miden's equivalent to [**Foundry scripts**](https://getfoundry.sh/guides/scripting-with-solidity). These are executable Rust binaries that handle all your contract interactions:
 
 - **Contract Deployment**: Scripts that create and deploy accounts to the network
-- **Function/Procedure Calls**: Scripts that interact with deployed contracts through notes or [transaction scripts](/miden-base/transaction#transaction-lifecycle)
+- **Function/Procedure Calls**: Scripts that interact with deployed contracts through notes or [transaction scripts](/core-concepts/miden-base/transaction#transaction-lifecycle)
 - **State Queries**: Scripts that read contract state from the network
 - **Operations**: Scripts for contract upgrades, configuration changes, etc.
 

docs/builder/smart-contracts/accounts/introduction.md

@@ -21,7 +21,7 @@ Every account has four parts:
 | **Vault** | The fungible and non-fungible assets the account holds |
 | **Nonce** | A counter that increments exactly once per state change, providing replay protection |
 
-The network doesn't store the full account state. Instead, it stores cryptographic commitments — hashes of the code, storage, and vault (see [account design](/design/miden-base/account/)). Only the account owner (or a public account's observers) sees the actual data.
+The network doesn't store the full account state. Instead, it stores cryptographic commitments — hashes of the code, storage, and vault (see [account design](/core-concepts/miden-base/account/)). Only the account owner (or a public account's observers) sees the actual data.
 
 ## Components, not contracts
 

docs/builder/smart-contracts/notes/introduction.md

@@ -48,7 +48,7 @@ Transaction 1 (Sender)                Transaction 2 (Recipient)
 
 **Transaction 1**: The sender's account creates an output note, attaches assets to it, and the note is published (either on-chain or kept private).
 
-**Transaction 2**: The recipient discovers the note, consumes it in their own transaction, the note script runs and verifies the consumer is authorized, and assets transfer into the recipient's vault. A **nullifier** is recorded to prevent the same note from being consumed again (see [note design](/design/miden-base/note)).
+**Transaction 2**: The recipient discovers the note, consumes it in their own transaction, the note script runs and verifies the consumer is authorized, and assets transfer into the recipient's vault. A **nullifier** is recorded to prevent the same note from being consumed again (see [note design](/core-concepts/miden-base/note)).
 
 This separation is what enables privacy and parallelism — the two transactions are independent and unlinkable from the network's perspective.
 

docs/builder/smart-contracts/transactions/introduction.md

@@ -8,7 +8,7 @@ description: "Transactions are Miden's execution unit — they consume input not
 
 Transactions are the execution unit in Miden. Every state change — transferring assets, updating storage, minting tokens — happens inside a transaction. Each transaction runs against a single account, consumes zero or more input notes, and produces zero or more output notes.
 
-The critical difference from other blockchains: transactions execute locally on the user's machine, not on a shared VM. After execution, the Miden VM generates a zero-knowledge proof that the transaction was valid (see [transaction design](/design/miden-base/transaction)). Only this proof and the resulting state commitments are submitted to the network. The network never sees the transaction inputs, the account's private state, or the logic that ran.
+The critical difference from other blockchains: transactions execute locally on the user's machine, not on a shared VM. After execution, the Miden VM generates a zero-knowledge proof that the transaction was valid (see [transaction design](/core-concepts/miden-base/transaction)). Only this proof and the resulting state commitments are submitted to the network. The network never sees the transaction inputs, the account's private state, or the logic that ran.
 
 ## Anatomy of a transaction
 

docs/design/_category_.json docs/core-concepts/_category_.jsondocs/design/_category_.json renamed to docs/core-concepts/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "Design",
+  "label": "Core Concepts",
   "position": 2,
   "collapsible": false,
   "collapsed": false