docs: update public guides

.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: "20"
+          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

.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

Makefile

@@ -11,6 +11,8 @@ 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
@@ -47,18 +49,18 @@ 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: shear
@@ -161,16 +163,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

compose/monitor.yml

@@ -12,4 +12,4 @@ services:
       - MIDEN_MONITOR_DISABLE_NTX_SERVICE=true
       - 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

@@ -99,7 +99,7 @@ services:
       - --validator.url=http://validator:50101
       - --ntx-builder.url=http://ntx-builder:50301
     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

docs/external/src/full-node/bootstrap.md

@@ -0,0 +1,69 @@
+---
+title: "Bootstrap"
+sidebar_position: 3
+---
+
+<!-- markdownlint-disable MD033 MD041 -->
+
+import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem";
+
+# Bootstrap
+
+A full node must perform one-time initialization by bootstrapping its local chain state to the target network's genesis
+block.
+
+<Tabs groupId="full-node-runtime" defaultValue="native">
+  <TabItem value="native" label="Native binary">
+
+For an official network:
+
+```bash
+miden-node bootstrap \
+  --data-directory full-node-data \
+  --network <network>
+```
+
+For a local or custom network:
+
+```bash
+miden-node bootstrap \
+  --data-directory full-node-data \
+  --file genesis.dat
+```
+
+The data directory must be empty when bootstrapping.
+
+  </TabItem>
+  <TabItem value="docker" label="Docker image">
+
+For an official network:
+
+```bash
+docker run --rm \
+  -v miden-full-node-data:/data \
+  ghcr.io/0xmiden/miden-node:<release-tag> \
+  miden-node bootstrap \
+  --data-directory /data \
+  --network <network>
+```
+
+For a local or custom network:
+
+```bash
+docker run --rm \
+  -v miden-full-node-data:/data \
+  -v "$PWD/genesis.dat:/genesis.dat:ro" \
+  ghcr.io/0xmiden/miden-node:<release-tag> \
+  miden-node bootstrap \
+  --data-directory /data \
+  --file /genesis.dat
+```
+
+The data volume must be empty when bootstrapping.
+
+  </TabItem>
+</Tabs>
+
+<!-- markdownlint-enable MD033 MD041 -->
+
+Use the same node version and genesis source as the upstream network you intend to follow.

docs/external/src/full-node/configuration.md

@@ -0,0 +1,42 @@
+---
+title: "Configuration"
+sidebar_position: 7
+---
+
+# Configuration
+
+Required options:
+
+| Option                    | Purpose                                                  |
+| ------------------------- | -------------------------------------------------------- |
+| `--data-directory`        | Directory containing local node state.                   |
+| `--rpc.listen`            | Socket address for the local public RPC API.             |
+| `--sync.block-source.url` | Upstream RPC URL used for block and proof subscriptions. |
+
+The rest have sensible default values which should only be tweaked for specific reasons. Use the command help output for
+the complete current configuration surface.
+
+Most options also have environment variable forms, which are useful when running under an orchestrator.
+
+## OpenTelemetry Traces
+
+Full nodes can export OpenTelemetry traces using the standard OTLP environment variables. Trace export is enabled when
+either of these variables is set to a non-empty value:
+
+- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`
+- `OTEL_EXPORTER_OTLP_ENDPOINT`
+
+For example:
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317 \
+OTEL_RESOURCE_ATTRIBUTES=service.instance.id=full-node-1 \
+miden-node full \
+  --data-directory full-node-data \
+  --rpc.listen 127.0.0.1:57291 \
+  --sync.block-source.url http://upstream-node:57291
+```
+
+Use `OTEL_RESOURCE_ATTRIBUTES=service.instance.id=<node-id>` to identify a specific node instance in your tracing
+backend. Other standard OpenTelemetry environment variables, such as `OTEL_SERVICE_NAME`, can be used to override the
+service name when needed.