fix: make docs links resolve consistently regardless of URL form

.github/workflows/check-doc-links.yml

@@ -0,0 +1,31 @@
+name: Check Doc Links
+
+# Fails a PR when current docs (docs/) contain browser-relative internal links
+# that should be source-tree-relative .md / Card docId links. Run
+# `npm run normalize-doc-links` locally to fix. Scoped to docs/ only;
+# versioned_docs snapshots are healed at deploy time, not validated here.
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "scripts/normalize-doc-links.mjs"
+      - ".github/workflows/check-doc-links.yml"
+
+jobs:
+  check-doc-links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+
+      - name: Install deps
+        run: npm install --frozen-lockfile
+
+      - name: Check doc links
+        run: npm run check:doc-links

.github/workflows/deploy-docs.yml

@@ -317,6 +317,12 @@ jobs:
       - name: Install deps
         run: npm install --frozen-lockfile
 
+      # Heal browser-relative internal links across the whole tree (current docs
+      # + every versioned_docs snapshot) before building. Versioned snapshots are
+      # not normalized in-repo, so this is where historical versions get fixed.
+      - name: Normalize docs links
+        run: npm run normalize-doc-links:all
+
       - name: Build site
         env:
           NODE_OPTIONS: "--max-old-space-size=12288" # 12GB

docs/builder/get-started/accounts.md

@@ -113,7 +113,7 @@ To run the code examples in this guide, you'll need to set up a development envi
 
 ### Rust Environment
 
-If you already created `my-test-project` during [installation](./setup/installation#rust-project), you can reuse it. Otherwise, create a new project:
+If you already created `my-test-project` during [installation](./setup/installation.md#rust-project), you can reuse it. Otherwise, create a new project:
 
 ```bash title=">_ Terminal"
 miden new my-project
@@ -134,7 +134,7 @@ cargo run --bin demo --release
 
 ### TypeScript Environment
 
-If you already created `miden-app` during [installation](./setup/installation#typescript-project), you can reuse it. Otherwise, scaffold a new Vite vanilla-ts project:
+If you already created `miden-app` during [installation](./setup/installation.md#typescript-project), you can reuse it. Otherwise, scaffold a new Vite vanilla-ts project:
 
 ```bash title=">_ Terminal"
 npm create vite@latest miden-app -- --template vanilla-ts
@@ -165,7 +165,7 @@ npm run dev
 Open the dev-server URL in the browser and watch the devtools console for output.
 
 :::tip
-For detailed frontend setup guidance (React, wallets, UI), see the [Tutorials section](../tutorials/).
+For detailed frontend setup guidance (React, wallets, UI), see the [Tutorials section](../tutorials/index.md).
 :::
 
 ## Creating Accounts Programmatically
@@ -406,6 +406,6 @@ Faucet account ID: 0xde0ba31282f7522046d3d4af40722b
 - **BasicFungibleFaucet**: Enables token minting capabilities
 - **AuthSingleSig**: Handles cryptographic authentication (Falcon512 or ECDSA via the `AuthScheme` enum)
 
-Now that you understand how to create accounts and faucets, you're ready to learn about Miden's unique transaction model. Continue to [Notes & Transactions](./notes) to explore how assets move between accounts using notes.
+Now that you understand how to create accounts and faucets, you're ready to learn about Miden's unique transaction model. Continue to [Notes & Transactions](./notes.md) to explore how assets move between accounts using notes.
 
 ---

docs/builder/get-started/index.md

@@ -25,22 +25,22 @@ Key concepts you'll encounter:
 Follow these guides in order:
 
 <CardGrid cols={2}>
-  <Card title="Installation" href="./setup/installation" eyebrow="1. Set up">
+  <Card title="Installation" docId="builder/get-started/setup/installation" eyebrow="1. Set up">
     Install the Miden toolchain with `midenup`.
   </Card>
-  <Card title="CLI basics" href="./setup/cli-basics" eyebrow="2. CLI">
+  <Card title="CLI basics" docId="builder/get-started/setup/cli-basics" eyebrow="2. CLI">
     Essential Miden CLI commands — create a wallet and mint your first tokens.
   </Card>
-  <Card title="Accounts" href="./accounts" eyebrow="3. Programmatic">
+  <Card title="Accounts" docId="builder/get-started/accounts" eyebrow="3. Programmatic">
     Create and manage Miden accounts programmatically in Rust and TypeScript.
   </Card>
-  <Card title="Notes & transactions" href="./notes" eyebrow="4. Transfers">
+  <Card title="Notes & transactions" docId="builder/get-started/notes" eyebrow="4. Transfers">
     Miden's note-based transaction model for private asset transfers.
   </Card>
-  <Card title="Read storage" href="./read-storage" eyebrow="5. Query">
+  <Card title="Read storage" docId="builder/get-started/read-storage" eyebrow="5. Query">
     Query account storage data and interact with deployed smart contracts.
   </Card>
-  <Card title="Your first smart contract" href="./your-first-smart-contract" eyebrow="6. Build">
+  <Card title="Your first smart contract" docId="builder/get-started/your-first-smart-contract/index" eyebrow="6. Build">
     Build, test, and deploy a smart contract on Miden using Rust.
   </Card>
 </CardGrid>

docs/builder/get-started/notes.md

@@ -57,7 +57,7 @@ This approach provides several advantages over direct transfers:
 
 ## Set Up Development Environment
 
-To run the code examples in this guide, you'll need to set up a development environment. If you haven't already, follow the setup instructions in the [Accounts](./accounts#set-up-development-environment) guide.
+To run the code examples in this guide, you'll need to set up a development environment. If you haven't already, follow the setup instructions in the [Accounts](./accounts.md#set-up-development-environment) guide.
 
 ## Minting Tokens
 

docs/builder/get-started/read-storage.md

@@ -26,7 +26,7 @@ Miden accounts contain several types of data you can read.
 
 ## Set Up Development Environment
 
-To run the code examples in this guide, you'll need to set up a development environment. If you haven't already, follow the setup instructions in the [Accounts](./accounts#set-up-development-environment) guide.
+To run the code examples in this guide, you'll need to set up a development environment. If you haven't already, follow the setup instructions in the [Accounts](./accounts.md#set-up-development-environment) guide.
 
 ## Reading from a Public Smart Contract
 

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

@@ -260,6 +260,6 @@ The counter example demonstrates a complete interaction pattern: the account con
 
 ## Next Steps
 
-Now that you understand the contract code structure, let's move on to [deploying your contract](./deploy) and learn how the integration folder enables interaction with your contracts on the Miden network.
+Now that you understand the contract code structure, let's move on to [deploying your contract](./deploy.md) and learn how the integration folder enables interaction with your contracts on the Miden network.
 
 ---

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

@@ -31,13 +31,13 @@ The counter example is designed to teach core Miden concepts through a simple, u
 
 ## Prerequisites
 
-Before starting this guide, ensure you have completed the [Installation](../setup/installation) tutorial and have:
+Before starting this guide, ensure you have completed the [Installation](../setup/installation.md) tutorial and have:
 
 - **Rust toolchain** installed and configured
 - **midenup toolchain** installed with Miden CLI tools
 
 :::tip Prerequisites Required
-You need those development tools installed for this guide. If you haven't set up your environment yet, please complete the [installation](../setup/installation) guide first.
+You need those development tools installed for this guide. If you haven't set up your environment yet, please complete the [installation](../setup/installation.md) guide first.
 :::
 
 ## No Prior Experience Required
@@ -62,9 +62,9 @@ If you get stuck during this tutorial:
 
 This tutorial is divided into focused sections:
 
-1. **[Create Your Project](./create)** - Set up your workspace and understand the counter contract code
-2. **[Deploy Your Contract](./deploy)** - Learn the integration folder and deploy to testnet
-3. **[Test Your Contract](./test)** - Learn how to effectively test your contracts
+1. **[Create Your Project](./create.md)** - Set up your workspace and understand the counter contract code
+2. **[Deploy Your Contract](./deploy.md)** - Learn the integration folder and deploy to testnet
+3. **[Test Your Contract](./test.md)** - Learn how to effectively test your contracts
 
 Each section builds on the previous one, so we recommend following them in order.
 

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

@@ -304,7 +304,7 @@ 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, 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.
+- Visit the [Tutorials section](../../tutorials/index.md) 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, consult the [Reference section](../../../reference/index.md) 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/glossary.md

@@ -55,7 +55,7 @@ A key-value store associated with an account. Made up of storage slots.
 
 ### MultiSig
 
-A multi-signature account on Miden that requires a configurable threshold (N-of-M) of authorized signers to approve transactions before execution. MultiSig workflows are coordinated through [Miden Guardian](./miden-guardian/).
+A multi-signature account on Miden that requires a configurable threshold (N-of-M) of authorized signers to approve transactions before execution. MultiSig workflows are coordinated through [Miden Guardian](./miden-guardian/index.md).
 
 ## Notes & assets
 
@@ -125,19 +125,19 @@ A data structure that represents the basic unit of computation and storage in Mi
 
 ### Miden Guardian
 
-Infrastructure built by OpenZeppelin for managing private account state on Miden. Guardian provides a server and client SDKs for backing up, syncing, and coordinating state across devices and parties without trust assumptions. See the [Miden Guardian documentation](./miden-guardian/).
+Infrastructure built by OpenZeppelin for managing private account state on Miden. Guardian provides a server and client SDKs for backing up, syncing, and coordinating state across devices and parties without trust assumptions. See the [Miden Guardian documentation](./miden-guardian/index.md).
 
 ### Canonicalization
 
-The background process by which [Miden Guardian](./miden-guardian/) promotes candidate deltas to canonical status by verifying them against the Miden network.
+The background process by which [Miden Guardian](./miden-guardian/index.md) promotes candidate deltas to canonical status by verifying them against the Miden network.
 
 ### Delta
 
 A Delta represents the changes between two states `s` and `s'`. Applying a Delta `d` to `s` produces `s'`.
 
 ### Delta Proposal
 
-A coordination mechanism in [Miden Guardian](./miden-guardian/) that allows multiple signers to propose, review, and co-sign state changes before they are promoted to a canonical delta.
+A coordination mechanism in [Miden Guardian](./miden-guardian/index.md) that allows multiple signers to propose, review, and co-sign state changes before they are promoted to a canonical delta.
 
 ### Threshold Signature
 

docs/builder/index.md

@@ -11,52 +11,52 @@ Accounts, notes, and transactions — authored in Rust, compiled to MASM, proved
 ## Start here
 
 <CardGrid cols={2}>
-  <Card title="Get started" href="./get-started" eyebrow="Install & run">
+  <Card title="Get started" docId="builder/get-started/index" eyebrow="Install & run">
     Install midenup, create a wallet, and send your first transaction — in under ten minutes.
   </Card>
-  <Card title="Your first smart contract" href="./get-started/your-first-smart-contract" eyebrow="Tutorial">
+  <Card title="Your first smart contract" docId="builder/get-started/your-first-smart-contract/index" eyebrow="Tutorial">
     Walk through writing, proving, and deploying a counter contract in Rust.
   </Card>
 </CardGrid>
 
 ## Build
 
 <CardGrid cols={2}>
-  <Card title="Smart contracts" href="./smart-contracts" eyebrow="Reference">
+  <Card title="Smart contracts" docId="builder/smart-contracts/index" eyebrow="Reference">
     Accounts, notes, storage, components, transactions — the full Rust SDK surface.
   </Card>
-  <Card title="Tutorials" href="./tutorials" eyebrow="Walkthroughs">
+  <Card title="Tutorials" docId="builder/tutorials/index" eyebrow="Walkthroughs">
     Real-world examples: the Miden Bank, private multisig, custom note scripts.
   </Card>
-  <Card title="Development helpers" href="./tutorials#development-helpers" eyebrow="How-to">
+  <Card title="Development helpers" docId="builder/tutorials/index" hash="#development-helpers" eyebrow="How-to">
     Testing, debugging, and common pitfalls when writing Miden programs.
   </Card>
-  <Card title="Tools" href="./tools" eyebrow="Clients & CLI">
+  <Card title="Tools" docId="builder/tools/index" eyebrow="Clients & CLI">
     Rust, Web, and React SDKs · playground · block explorer · CLI.
   </Card>
 </CardGrid>
 
 ## Ship
 
 <CardGrid cols={2}>
-  <Card title="Migration" href="./migration" eyebrow="v0.13 → v0.14">
+  <Card title="Migration" docId="builder/migration/index" eyebrow="v0.13 → v0.14">
     Breaking changes, renames, and new features across accounts, notes, transactions, MASM, and the client.
   </Card>
-  <Card title="Miden Guardian" href="./miden-guardian" eyebrow="Account state">
+  <Card title="Miden Guardian" docId="builder/miden-guardian/index" eyebrow="Account state">
     Backup, sync, and coordinate private account state across devices.
   </Card>
-  <Card title="Private multisig" href="./private-multisig" eyebrow="Solutions">
+  <Card title="Private multisig" docId="builder/private-multisig/index" eyebrow="Solutions">
     Multi-party threshold signature workflows built on Miden.
   </Card>
 </CardGrid>
 
 ## Reference
 
 <CardGrid cols={2}>
-  <Card title="FAQ" href="./faq" eyebrow="Questions">
+  <Card title="FAQ" docId="builder/faq" eyebrow="Questions">
     Frequently asked questions about Miden.
   </Card>
-  <Card title="Glossary" href="./glossary" eyebrow="Terminology">
+  <Card title="Glossary" docId="builder/glossary" eyebrow="Terminology">
     Key terms and definitions used throughout the docs.
   </Card>
 </CardGrid>

docs/builder/miden-guardian/index.md

@@ -55,22 +55,22 @@ Guardian has an explicit trust boundary:
 ## Learn more
 
 <CardGrid cols={2}>
-  <Card title="Architecture" href="./core-concepts/architecture" eyebrow="Core concepts">
+  <Card title="Architecture" docId="builder/miden-guardian/core-concepts/architecture" eyebrow="Core concepts">
     Roles, trust boundaries, state flow, and failure behavior.
   </Card>
-  <Card title="Data structures" href="./core-concepts/data-structures" eyebrow="Core concepts">
+  <Card title="Data structures" docId="builder/miden-guardian/core-concepts/data-structures" eyebrow="Core concepts">
     State, deltas, commitments, and delta proposals.
   </Card>
-  <Card title="Components" href="./core-concepts/components" eyebrow="Core concepts">
+  <Card title="Components" docId="builder/miden-guardian/core-concepts/components" eyebrow="Core concepts">
     API, authentication, storage, and other server components.
   </Card>
-  <Card title="Security" href="./core-concepts/security" eyebrow="Core concepts">
+  <Card title="Security" docId="builder/miden-guardian/core-concepts/security" eyebrow="Core concepts">
     Trust model, integrity guarantees, and edge cases.
   </Card>
-  <Card title="Operator guide" href="./operator-guide/running" eyebrow="Run it">
+  <Card title="Operator guide" docId="builder/miden-guardian/operator-guide/running" eyebrow="Run it">
     How to run, deploy, and troubleshoot a Guardian server.
   </Card>
-  <Card title="Private multisig" href="../private-multisig/" eyebrow="Solutions">
+  <Card title="Private multisig" docId="builder/private-multisig/index" eyebrow="Solutions">
     Multi-party threshold signature workflows powered by Guardian.
   </Card>
 </CardGrid>

docs/builder/miden-guardian/operator-guide/running.md

@@ -103,4 +103,4 @@ cargo run -p guardian-server --features postgres --bin server
 | `PUT /delta/proposal`         | Signed headers    |
 | `/dashboard/accounts*`        | Dashboard session |
 
-Signed requests carry three headers: `x-pubkey`, `x-signature`, and `x-timestamp`. Timestamps must be within ±5 minutes of server time and strictly greater than the last value the server saw for that public key — see [Authentication failures](./troubleshooting#authentication-failures) if requests are being rejected.
+Signed requests carry three headers: `x-pubkey`, `x-signature`, and `x-timestamp`. Timestamps must be within ±5 minutes of server time and strictly greater than the last value the server saw for that public key — see [Authentication failures](./troubleshooting.md#authentication-failures) if requests are being rejected.