docs: update public guides

.config/cspell.yaml

@@ -0,0 +1,19 @@
+version: "0.2"
+language: en-US
+ignoreRegExpList:
+  - Urls
+  - markdownCodeBlock
+patterns:
+  - name: markdownCodeBlock
+    pattern: "/^(?:```|~~~)[\\s\\S]*?^(?:```|~~~)/gm"
+ignorePaths:
+  - target
+  - docs/external/build
+  - docs/external/node_modules
+  - node_modules
+  - "**/package-lock.json"
+words:
+  - grpcurl
+  - Merkle
+  - Miden
+  - RocksDB

.config/markdownlint-cli2.yaml

@@ -1,2 +1,7 @@
 config:
   line-length: false
+  # Docusaurus pages use frontmatter `title` for sidebar/browser metadata and an explicit H1 for
+  # page content. Do not count the frontmatter title as a page title, otherwise every page with both
+  # fields trips MD025/single-title.
+  single-title:
+    front_matter_title: ""

.github/workflows/ci.yml

@@ -13,11 +13,9 @@ on:
       - next
     paths-ignore:
       - "**.txt"
-      - "docs/**"
   pull_request:
     paths-ignore:
       - "**.txt"
-      - "docs/**"
 
 env:
   # Shared prefix key for the Rust caches.
@@ -176,6 +174,30 @@ jobs:
       - name: Build docs
         run: cargo doc --no-deps --workspace --all-features --locked
 
+  external-docs:
+    name: docs - external
+    runs-on: ubuntu-24.04
+    env:
+      # Docusaurus checks for package updates during builds and may try to write to a user config
+      # directory. Disable that notifier in CI so docs output is limited to build/link failures.
+      NO_UPDATE_NOTIFIER: "1"
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "22.18.0"
+          cache: "npm"
+          cache-dependency-path: docs/external/package-lock.json
+      - name: Install dependencies
+        working-directory: ./docs/external
+        run: npm ci
+      - name: Build documentation and check links
+        working-directory: ./docs/external
+        run: npm run build:dev
+
   # Ensure the stress-test still functions by running some cheap benchmarks.
   stress-test:
     name: stress test
@@ -267,10 +289,17 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "22.18.0"
       - uses: taiki-e/install-action@055f5df8c3f65ea01cd41e9dc855becd88953486 # v2.75.18
         with:
           tool: typos@1.42.0
+      - name: Install CSpell
+        run: npm install --global cspell@10.0.1
       - run: make typos-check
+      - run: make markdown-spellcheck
 
   fmt:
     name: lint - formatting

.github/workflows/trigger-deploy-docs.yml → .github/workflows/publish-external-docs.yml

@@ -1,19 +1,26 @@
-name: Trigger Aggregator Docs Rebuild
+name: Publish External Docs
 
 on:
   push:
     branches: [next]
     paths:
-      - "docs/external**"
+      - "docs/external/**"
+      - ".github/workflows/publish-external-docs.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: "${{ github.workflow }} @ ${{ github.ref }}"
+  cancel-in-progress: true
+
+permissions:
+  contents: read
 
 jobs:
   notify:
+    name: Trigger aggregator docs rebuild
     runs-on: ubuntu-24.04
     environment: deploy-docs
 
-    permissions:
-      contents: read
-
     steps:
       - name: Send repository_dispatch to aggregator
         uses: peter-evans/repository-dispatch@a628c95fd17070f003ea24579a56e6bc89b25766

CHANGELOG.md

@@ -280,7 +280,7 @@
 - Refactored account table and introduce tracking forest ([#1394](https://github.com/0xMiden/node/pull/1394)).
 - [BREAKING] Re-organized RPC protobuf schema to be independent of internal schema ([#1401](https://github.com/0xMiden/node/pull/1401)).
 - Removed internal errors from the `miden-network-monitor` ([#1424](https://github.com/0xMiden/node/pull/1424)).
-- [BREAKING] Added block signing capabilities to Validator component and updated gensis bootstrap to sign blocks with configured signer ([#1426](https://github.com/0xMiden/node/pull/1426)).
+- [BREAKING] Added block signing capabilities to Validator component and updated genesis bootstrap to sign blocks with configured signer ([#1426](https://github.com/0xMiden/node/pull/1426)).
 - Track network transactions latency in `miden-network-monitor` ([#1430](https://github.com/0xMiden/node/pull/1430)).
 - Reduced default block interval from `5s` to `2s` ([#1438](https://github.com/0xMiden/node/pull/1438)).
 - Increased retained account tree history from 33 to 100 blocks to account for the reduced block interval ([#1438](https://github.com/0xMiden/node/pull/1438)).

Makefile

@@ -11,11 +11,15 @@ STRESS_TEST_DATA_DIR ?= stress-test-store-$(shell date +%Y%m%d-%H%M%S)
 COMPOSE_FILES = -f docker-compose.yml -f compose/telemetry.yml -f compose/monitor.yml
 CONFIG_DIR = .config
 README_FILES = $(shell git ls-files '*README.md')
+EXTERNAL_DOCS_MARKDOWN_FILES = $(shell git ls-files 'docs/external/**/*.md')
+MARKDOWN_FILES = $(README_FILES) $(EXTERNAL_DOCS_MARKDOWN_FILES)
 PRETTIER_CONFIG = $(CONFIG_DIR)/prettier.json
 PRETTIER_LOG_LEVEL = warn
 PRETTIER_VERSION ?= 3.8.3
 MARKDOWNLINT_CONFIG = $(CONFIG_DIR)/markdownlint-cli2.yaml
 MARKDOWNLINT_CLI2_VERSION ?= 0.22.1
+CSPELL_CONFIG = $(CONFIG_DIR)/cspell.yaml
+CSPELL_VERSION ?= 10.0.1
 RUSTFMT_CONFIG = $(CONFIG_DIR)/rustfmt.toml
 TAPLO_CONFIG = $(CONFIG_DIR)/taplo.toml
 
@@ -47,18 +51,23 @@ format-check: markdown-format-check ## Checks rustfmt, README formatting, and co
 
 
 .PHONY: markdown-format
-markdown-format: ## Formats README Markdown files
-	@prettier --config $(PRETTIER_CONFIG) --log-level $(PRETTIER_LOG_LEVEL) --write $(README_FILES)
+markdown-format: ## Formats Markdown files
+	@prettier --config $(PRETTIER_CONFIG) --log-level $(PRETTIER_LOG_LEVEL) --write $(MARKDOWN_FILES)
 
 
 .PHONY: markdown-format-check
-markdown-format-check: ## Checks README Markdown formatting
-	@prettier --config $(PRETTIER_CONFIG) --log-level $(PRETTIER_LOG_LEVEL) --check $(README_FILES)
+markdown-format-check: ## Checks Markdown formatting
+	@prettier --config $(PRETTIER_CONFIG) --log-level $(PRETTIER_LOG_LEVEL) --check $(MARKDOWN_FILES)
 
 
 .PHONY: markdown-lint
-markdown-lint: ## Lints README Markdown files
-	markdownlint-cli2 --config $(MARKDOWNLINT_CONFIG) $(README_FILES)
+markdown-lint: ## Lints Markdown files
+	markdownlint-cli2 --config $(MARKDOWNLINT_CONFIG) $(MARKDOWN_FILES)
+
+
+.PHONY: markdown-spellcheck
+markdown-spellcheck: ## Spellchecks Markdown files
+	cspell --config $(CSPELL_CONFIG) --no-progress --show-suggestions $(MARKDOWN_FILES)
 
 
 .PHONY: shear
@@ -85,7 +94,7 @@ workspace-check: ## Runs a check that all packages have `lints.workspace = true`
 
 
 .PHONY: lint
-lint: typos-check format markdown-lint fix clippy toml shear ## Runs all linting tasks at once (Clippy, formatting, Markdown, cargo-shear)
+lint: typos-check markdown-spellcheck format markdown-lint fix clippy toml shear ## Runs all linting tasks at once (Clippy, formatting, spelling, Markdown, cargo-shear)
 
 # --- docs ----------------------------------------------------------------------------------------
 
@@ -161,16 +170,23 @@ install-network-monitor: ## Installs network monitor binary
 
 # --- docker --------------------------------------------------------------------------------------
 
-.PHONY: compose-up
-compose-up: ## Starts all node components, telemetry, and monitor via docker compose
+.PHONY: local-network-build
+local-network-build: docker-build ## Builds Docker images used by the local development network
+
+.PHONY: local-network-up
+local-network-up: ## Starts the local development network
 	docker compose $(COMPOSE_FILES) up -d
 
-.PHONY: compose-down
-compose-down: ## Stops and removes all containers via docker compose
+.PHONY: local-network-down
+local-network-down: ## Stops the local development network, preserving volumes
 	docker compose $(COMPOSE_FILES) down --remove-orphans
 
-.PHONY: compose-logs
-compose-logs: ## Follows logs for all components via docker compose
+.PHONY: local-network-delete
+local-network-delete: ## Stops the local development network and deletes volumes
+	docker compose $(COMPOSE_FILES) down -v --remove-orphans
+
+.PHONY: local-network-logs
+local-network-logs: ## Follows logs for the local development network
 	docker compose $(COMPOSE_FILES) logs -f
 
 .PHONY: docker-build
@@ -249,6 +265,7 @@ check-tools: ## Checks if development tools are installed
 	@command -v npm >/dev/null 2>&1 && echo "[OK] npm is installed" || echo "[MISSING] npm is not installed (run: make install-tools)"
 	@command -v prettier >/dev/null 2>&1 && echo "[OK] prettier is installed" || echo "[MISSING] prettier is not installed (run: make install-tools)"
 	@command -v markdownlint-cli2 >/dev/null 2>&1 && echo "[OK] markdownlint-cli2 is installed" || echo "[MISSING] markdownlint-cli2 is not installed (run: make install-tools)"
+	@command -v cspell >/dev/null 2>&1 && echo "[OK] cspell is installed" || echo "[MISSING] cspell is not installed (run: make install-tools)"
 
 .PHONY: install-tools
 install-tools: ## Installs tools required by the Makefile
@@ -266,5 +283,5 @@ install-tools: ## Installs tools required by the Makefile
 		echo "On Windows: Download from https://nodejs.org/"; \
 		exit 1; \
 	fi
-	npm install --global prettier@$(PRETTIER_VERSION) markdownlint-cli2@$(MARKDOWNLINT_CLI2_VERSION)
+	npm install --global prettier@$(PRETTIER_VERSION) markdownlint-cli2@$(MARKDOWNLINT_CLI2_VERSION) cspell@$(CSPELL_VERSION)
 	@echo "Development tools installation complete!"

README.md

@@ -30,11 +30,11 @@ further value from it. If any information is missing from the official documenta
 ## Developer docs
 
 Developers can find repository and onboarding documentation in the [developer docs][developer-docs]. Those docs are more
-in-depth but the following sections endeavour to provide a short summary.
+in-depth but the following sections endeavor to provide a short summary.
 
-### Workspace organisation
+### Workspace organization
 
-The workspace is organised around several binaries, with supplementary crates providing organisation and shared
+The workspace is organized around several binaries, with supplementary crates providing organization and shared
 functionality. These crates are for internal use only; the primary outputs are the binaries and gRPC schema. The former
 are found under the `bin` directory, the latter in the `proto` directory.
 

compose/monitor.yml

@@ -14,4 +14,4 @@ services:
       - MIDEN_MONITOR_NETWORK_NAME=Localhost
       - OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317
     ports:
-      - "3001:3001"
+      - "127.0.0.1:3001:3001"

compose/telemetry.yml

@@ -5,8 +5,8 @@ services:
       - ./compose/tempo/tempo.yml:/etc/tempo.yaml
     command: ["-config.file=/etc/tempo.yaml"]
     ports:
-      - "3200:3200"
-      - "4317:4317"
+      - "127.0.0.1:3200:3200"
+      - "127.0.0.1:4317:4317"
 
   grafana:
     image: grafana/grafana:12.4
@@ -19,7 +19,7 @@ services:
       - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
       - GF_DASHBOARDS_DEFAULT_HOME_DASHBOARD_PATH=/var/lib/grafana/dashboards/miden-node.json
     ports:
-      - "3000:3000"
+      - "127.0.0.1:3000:3000"
     depends_on:
       - tempo
 

docker-compose.yml

@@ -104,7 +104,7 @@ services:
       - --ntx-builder.url=http://ntx-builder:50301
       - --rpc.network-tx-auth-header-value=secret_value
     ports:
-      - "57291:57291"
+      - "127.0.0.1:57291:57291"
 
   validator:
     image: miden-validator

docs/external/docusaurus.config.ts

@@ -2,14 +2,19 @@ import type { Config } from "@docusaurus/types";
 import { themes as prismThemes } from "prism-react-renderer";
 
 // If your content lives in docs/src, set DOCS_PATH='src'; else '.'
-const DOCS_PATH =
-  process.env.DOCS_PATH || (require("fs").existsSync("src") ? "src" : ".");
+const DOCS_PATH = process.env.DOCS_PATH || (require("fs").existsSync("src") ? "src" : ".");
 
 const config: Config = {
   title: "Docs Dev Preview",
   url: "http://localhost:3000",
   baseUrl: "/",
   trailingSlash: false,
+  onBrokenLinks: "throw",
+  markdown: {
+    hooks: {
+      onBrokenMarkdownLinks: "throw",
+    },
+  },
 
   // Minimal classic preset: docs only, autogenerated sidebars, same math plugins as prod
   presets: [
@@ -102,7 +107,7 @@ const config: Config = {
       prism: {
         theme: prismThemes.oneLight,
         darkTheme: prismThemes.oneDark,
-        additionalLanguages: ["rust", "solidity", "toml", "yaml"],
+        additionalLanguages: ["bash", "json", "protobuf", "rust", "solidity", "toml", "yaml"],
       },
       navbar: {
         logo: {

docs/external/src/full-node/_category_.yml

@@ -0,0 +1,3 @@
+label: "Full Node Guide"
+position: 2
+collapsed: true