docs: rename Core Concepts to Reference (label + paths)

.github/workflows/cut-versions.yml

@@ -3,7 +3,7 @@
 # This workflow ingests external repos and creates versioned snapshots.
 #
 # v0.4 Information Architecture:
-#   - Core Concepts docs (protocol, miden-vm, compiler, node) → docs/core-concepts/
+#   - Reference docs (protocol, miden-vm, compiler, node) → docs/reference/
 #   - Builder docs (tutorials, miden-client) → docs/builder/tutorials/, docs/builder/tools/client/
 #
 # Workflow responsibilities:
@@ -150,7 +150,7 @@ jobs:
           echo "Aggregating vendor docs into v0.4 IA structure..."
 
           # Clean directories that will be re-synced (v0.4 nested paths)
-          rm -rf docs/core-concepts/protocol docs/core-concepts/miden-vm docs/core-concepts/node docs/core-concepts/compiler
+          rm -rf docs/reference/protocol docs/reference/miden-vm docs/reference/node docs/reference/compiler
           # tools/clients: only clean ingested subdirs; preserve locally-authored web-client/, react-sdk/, index.md
           rm -rf docs/builder/tools/clients/rust-client
           rm -rf docs/builder/tools/clients/img
@@ -172,29 +172,29 @@ jobs:
           done
           rm -rf docs/builder/tutorials/recipes/img
 
-          # Core Concepts docs → docs/core-concepts/*
+          # Reference docs → docs/reference/*
           if [ -d "vendor/protocol/docs/src" ]; then
-            mkdir -p docs/core-concepts/protocol
-            cp -r vendor/protocol/docs/src/* docs/core-concepts/protocol/
-            echo "Synced protocol → docs/core-concepts/protocol"
+            mkdir -p docs/reference/protocol
+            cp -r vendor/protocol/docs/src/* docs/reference/protocol/
+            echo "Synced protocol → docs/reference/protocol"
           fi
 
           if [ -d "vendor/miden-vm/docs/src" ]; then
-            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"
+            mkdir -p docs/reference/miden-vm
+            cp -r vendor/miden-vm/docs/src/* docs/reference/miden-vm/
+            echo "Synced miden-vm → docs/reference/miden-vm"
           fi
 
           if [ -d "vendor/node/docs/external/src" ]; then
-            mkdir -p docs/core-concepts/node
-            cp -r vendor/node/docs/external/src/* docs/core-concepts/node/
-            echo "Synced node → docs/core-concepts/node"
+            mkdir -p docs/reference/node
+            cp -r vendor/node/docs/external/src/* docs/reference/node/
+            echo "Synced node → docs/reference/node"
           fi
 
           if [ -d "vendor/compiler/docs/external/src" ]; then
-            mkdir -p docs/core-concepts/compiler
-            cp -r vendor/compiler/docs/external/src/* docs/core-concepts/compiler/
-            echo "Synced compiler → docs/core-concepts/compiler"
+            mkdir -p docs/reference/compiler
+            cp -r vendor/compiler/docs/external/src/* docs/reference/compiler/
+            echo "Synced compiler → docs/reference/compiler"
           fi
 
           # Builder docs → docs/builder/*
@@ -267,8 +267,8 @@ jobs:
 
           echo "Content aggregation complete. Final docs structure:"
           ls -la docs/
-          echo "Core Concepts subdirs:"
-          ls -la docs/core-concepts/ || true
+          echo "Reference subdirs:"
+          ls -la docs/reference/ || true
           echo "Builder subdirs:"
           ls -la docs/builder/ || true
           echo "Tutorials subdirs:"
@@ -281,16 +281,16 @@ jobs:
           npm run docusaurus -- docs:version "$VERSION"
 
       # CRITICAL: Clean up docs/ to maintain canonical-source architecture
-      # docs/ must only contain authored content (builder/, core-concepts/ landing pages)
+      # docs/ must only contain authored content (builder/, reference/ 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/core-concepts/protocol
-          rm -rf docs/core-concepts/miden-vm
-          rm -rf docs/core-concepts/node
-          rm -rf docs/core-concepts/compiler
+          rm -rf docs/reference/protocol
+          rm -rf docs/reference/miden-vm
+          rm -rf docs/reference/node
+          rm -rf docs/reference/compiler
           # tools/clients: only clean ingested subdirs; preserve locally-authored web-client/, react-sdk/, index.md
           rm -rf docs/builder/tools/clients/rust-client
           rm -rf docs/builder/tools/clients/img

.github/workflows/deploy-docs.yml

@@ -155,15 +155,15 @@ jobs:
 
       # ============================================================
       # v0.4 IA: Aggregate into nested structure
-      #   - Core Concepts docs (protocol, miden-vm, compiler, node) → docs/core-concepts/
+      #   - Reference docs (protocol, miden-vm, compiler, node) → docs/reference/
       #   - Builder docs (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/core-concepts/protocol docs/core-concepts/miden-vm docs/core-concepts/node docs/core-concepts/compiler
+          rm -rf docs/reference/protocol docs/reference/miden-vm docs/reference/node docs/reference/compiler
           # tools/clients: only clean ingested subdirs; preserve locally-authored web-client/, react-sdk/, index.md
           rm -rf docs/builder/tools/clients/rust-client
           rm -rf docs/builder/tools/clients/img
@@ -185,29 +185,29 @@ jobs:
           done
           rm -rf docs/builder/tutorials/recipes/img
 
-          # Core Concepts docs → docs/core-concepts/*
+          # Reference docs → docs/reference/*
           if [ -d "vendor/protocol/docs/src" ]; then
-            mkdir -p docs/core-concepts/protocol
-            cp -r vendor/protocol/docs/src/* docs/core-concepts/protocol/
-            echo "Synced protocol → docs/core-concepts/protocol"
+            mkdir -p docs/reference/protocol
+            cp -r vendor/protocol/docs/src/* docs/reference/protocol/
+            echo "Synced protocol → docs/reference/protocol"
           fi
 
           if [ -d "vendor/miden-vm/docs/src" ]; then
-            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"
+            mkdir -p docs/reference/miden-vm
+            cp -r vendor/miden-vm/docs/src/* docs/reference/miden-vm/
+            echo "Synced miden-vm → docs/reference/miden-vm"
           fi
 
           if [ -d "vendor/node/docs/external/src" ]; then
-            mkdir -p docs/core-concepts/node
-            cp -r vendor/node/docs/external/src/* docs/core-concepts/node/
-            echo "Synced node → docs/core-concepts/node"
+            mkdir -p docs/reference/node
+            cp -r vendor/node/docs/external/src/* docs/reference/node/
+            echo "Synced node → docs/reference/node"
           fi
 
           if [ -d "vendor/compiler/docs/external/src" ]; then
-            mkdir -p docs/core-concepts/compiler
-            cp -r vendor/compiler/docs/external/src/* docs/core-concepts/compiler/
-            echo "Synced compiler → docs/core-concepts/compiler"
+            mkdir -p docs/reference/compiler
+            cp -r vendor/compiler/docs/external/src/* docs/reference/compiler/
+            echo "Synced compiler → docs/reference/compiler"
           fi
 
           # Builder docs → docs/builder/*
@@ -285,8 +285,8 @@ jobs:
 
           echo "Content aggregation complete. Final docs structure:"
           ls -la docs/
-          echo "Core Concepts subdirs:"
-          ls -la docs/core-concepts/ || true
+          echo "Reference subdirs:"
+          ls -la docs/reference/ || 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 (core-concepts, builder/)
+- `docs/` — current docs (reference, builder/)
 - `docs/builder/` — developer-facing: tools, develop, get-started, smart-contracts, migration
-- `docs/core-concepts/` — protocol design docs
+- `docs/reference/` — 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
             BuilderMigration["builder/migration/"]
             BuilderFAQ["builder/faq.md"]
             BuilderGlossary["builder/glossary.md"]
-            CoreConceptsLanding["core-concepts/index.md"]
+            ReferenceLanding["reference/index.md"]
         end
 
         subgraph VersionedDocs["versioned_docs/ (snapshots)"]
@@ -87,17 +87,17 @@ flowchart TD
 | Category | Location | Source | Example |
 |----------|----------|--------|---------|
 | **Authored** | `docs/builder/` | Written in this repo | `docs/builder/get-started/`, `docs/builder/faq.md` |
-| **Ingested (live)** | `docs/core-concepts/`, `docs/builder/` | External repos @ next | `docs/core-concepts/protocol/`, `docs/builder/tutorials/` |
+| **Ingested (live)** | `docs/reference/`, `docs/builder/` | External repos @ next | `docs/reference/protocol/`, `docs/builder/tutorials/` |
 | **Ingested (versioned)** | `versioned_docs/` | External repos @ release tags | `versioned_docs/version-0.12/protocol/` |
 | **Snapshots** | `versioned_docs/` | Frozen via `docs:version` | All versioned content |
 
 ### What Each Location Contains
 
 **`docs/` (current/next version)**
 - Get Started guides (`docs/builder/get-started/`)
-- Core Concepts, Smart Contracts, Reference (placeholders)
+- Reference and Smart Contracts placeholders
 - FAQ and Glossary
-- Landing pages for Builder and Core Concepts
+- Landing pages for Builder and Reference
 
 **`versioned_docs/` (frozen releases)**
 - Snapshots of `docs/` at release time
@@ -180,7 +180,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:
-   - Core Concepts docs → `docs/core-concepts/protocol/`, `miden-vm/`, `compiler/`, `node/`
+   - Reference docs → `docs/reference/protocol/`, `miden-vm/`, `compiler/`, `node/`
    - Builder docs → `docs/builder/tutorials/`, `docs/builder/tools/client/`
 3. Runs `npm run build` to generate the static site
 4. Deploys to GitHub Pages at `docs.miden.xyz`
@@ -208,7 +208,7 @@ The build uses:
 ### ❌ DON'T
 
 - **Never** manually copy external content into `docs/` (use CI/CD ingestion)
-- **Never** create root-level `docs/protocol/`, `docs/miden-vm/`, etc. (use nested paths in `docs/core-concepts/`)
+- **Never** create root-level `docs/protocol/`, `docs/miden-vm/`, etc. (use nested paths in `docs/reference/`)
 - **Never** edit `versioned_docs/` directly (snapshots are immutable)
 - **Never** create a root-level `docs/quick-start/` (Get Started lives in `docs/builder/`)
 
@@ -253,7 +253,7 @@ The site uses **Simple Analytics** for privacy-first, cookie-less metrics.
 ### Updating LLM-facing files
 
 Edit `static/llms.txt` and `static/skill.md` directly. Content should:
-- List canonical current entry points for Builder, clients, tutorials, Guardian, and Core Concepts
+- List canonical current entry points for Builder, clients, tutorials, Guardian, and Reference
 - Call out `/` as the latest stable docs and `/next/` as the current unstable docs
 - Avoid stale paths such as `builder/develop/` or old `miden-base` source links
 - Avoid "Polygon Miden" branding (use "Miden" only)

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

@@ -143,7 +143,7 @@ struct CounterContract {
 }
 ```
 
-The `#[component]` attribute marks this as a Miden [Account component](/core-concepts/protocol/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`).
+The `#[component]` attribute marks this as a Miden [Account component](/reference/protocol/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.
 
@@ -233,7 +233,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](/core-concepts/protocol/note/).
+Learn more about [note scripts in the Miden documentation](/reference/protocol/note/).
 
 #### The Note Script Function
 

docs/builder/get-started/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](/core-concepts/protocol/transaction#transaction-lifecycle)
+- **Function/Procedure Calls**: Scripts that interact with deployed contracts through notes or [transaction scripts](/reference/protocol/transaction#transaction-lifecycle)
 - **State Queries**: Scripts that read contract state from the network
 - **Operations**: Scripts for contract upgrades, configuration changes, etc.
 

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

@@ -305,6 +305,6 @@ Congratulations! You've successfully completed the Miden smart contract quick st
 To deepen your knowledge, we recommend exploring the following resources:
 
 - Visit the [Tutorials section](../../tutorials/) for detailed, hands-on guides on topics such as contract interactions, advanced storage, custom note scripting, and integrating with external applications.
-- For in-depth technical explanations of core concepts, consult the [Core Concepts section](../../../core-concepts/) of the documentation. Here you'll find comprehensive information on Miden's architecture, account model, transaction lifecycle, and the underlying zero-knowledge technology that powers the network.
+- For in-depth technical explanations, consult the [Reference section](../../../reference/) of the documentation. Here you'll find comprehensive information on Miden's architecture, account model, transaction lifecycle, and the underlying zero-knowledge technology that powers the network.
 
 The foundational patterns and concepts you've practiced in this Quick Start will enable you to build complex, privacy-preserving applications on the Miden network. Continue with the resources above to take your development further!

docs/builder/index.md

@@ -70,11 +70,11 @@ Accounts, notes, and transactions — authored in Rust, compiled to MASM, proved
 import SectionLinks from '@site/src/components/SectionLinks';
 
 <SectionLinks
-  title="Explore core concepts"
+  title="Explore the reference"
   links={[
-    { href: '../core-concepts', label: 'Architecture overview', description: 'Actor model, state design, and protocol fundamentals' },
-    { href: '../core-concepts#protocol', label: 'Protocol reference', description: 'Accounts, notes, state model, and transaction semantics' },
-    { href: '../core-concepts#virtual-machine-miden-vm', label: 'Virtual machine', description: 'STARK-based VM, chiplets, and Miden Assembly' },
+    { href: '../reference', label: 'Architecture overview', description: 'Actor model, state design, and protocol fundamentals' },
+    { href: '../reference#protocol', label: 'Protocol reference', description: 'Accounts, notes, state model, and transaction semantics' },
+    { href: '../reference#virtual-machine-miden-vm', label: 'Virtual machine', description: 'STARK-based VM, chiplets, and Miden Assembly' },
   ]}
 />
 

docs/builder/migration/05-asset-vault-faucet.md

@@ -19,7 +19,7 @@ Assets are now represented as two words (`ASSET_KEY` + `ASSET_VALUE`) instead of
 The single 4-felt `ASSET` word has been split into two words: `ASSET_KEY` (identity + faucet + callback flag) and `ASSET_VALUE` (amount or data hash). Every kernel procedure and standard-library helper that previously accepted or returned `ASSET` now works with the `ASSET_KEY, ASSET_VALUE` pair.
 
 :::note Canonical layout
-The full field-by-field layout — including how the per-asset callback flag is packed into the reserved low byte of `faucet_id_suffix` — is documented in [Asset encoding](../../core-concepts/protocol/asset.md#encoding). This page covers the v0.13 → v0.14 delta only.
+The full field-by-field layout — including how the per-asset callback flag is packed into the reserved low byte of `faucet_id_suffix` — is documented in [Asset encoding](../../reference/protocol/asset.md#encoding). This page covers the v0.13 → v0.14 delta only.
 :::
 
 ### Affected Code

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](/core-concepts/protocol/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](/reference/protocol/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 onchain 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](/core-concepts/protocol/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](/reference/protocol/note)).
 
 This separation is what enables privacy and parallelism — the two transactions are independent and unlinkable from the network's perspective.