feat(mdbook): publish spec via mdBook on GitHub Pages

Set up the protocol spec as an mdBook and add a GitHub Actions workflow that builds it on every push/PR and deploys to GitHub Pages on main. The repo is now both a machine-readable corpus and a browsable, searchable site. Structure changes (one-time, mechanical): - Rename the spec source directory from `spec/` to `src/` to match mdBook's default convention. All 21 chapter files move; their internal relative cross-links are unchanged. - Add `src/SUMMARY.md` as the mdBook table of contents, grouping chapters under Wire Format, Payloads, Cryptography & Identity, and Routing & Higher-Layer Protocols. - Add `book.toml` at repo root: title, author, search enabled, fold enabled, edit-on-GitHub links, navy theme. - Add `.github/workflows/mdbook.yml`: build on push + PR, deploy on push to main only (configure-pages + upload-pages-artifact + deploy-pages from actions/). - Add `/book/` to .gitignore. Reference updates so the old path is fully retired: - Every `spec_ref` in `corpus/**/*.json` rewritten from `spec/` to `src/` (54 files). - Schema description text and example path in `corpus/schema/test-vector.schema.json`. - `README.md`: prominent link to the published site near the top; "What's Here" updated for the new layout. - `CONTRIBUTING.md`: spec-editing instructions point at `src/` and note the SUMMARY.md requirement. - `CLAUDE.md`: directory-layout notes updated. CHANGELOG.md historical entries intentionally keep their `spec/` paths since those record what the paths were at the time of those commits. After this lands, the user needs to enable GitHub Pages in repo settings with source = "GitHub Actions" (one-time, manual). The workflow will then publish to https://swaits.github.io/meshcore-spec/ on every push to main. Verified locally: `mdbook build` produces a clean book/ tree with all 21 chapters rendered and the SUMMARY-driven sidebar populated. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:36:28 -06:00
1 parent 75fb228909
commit d785e35919
@@ -0,0 +1,47 @@
+name: mdBook
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: latest
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+      - name: Build book
+        run: mdbook build
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./book
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
@@ -20,3 +20,6 @@ Thumbs.db
 /build/
 /dist/
 /references/
+
+# mdBook output
+/book/
@@ -5,7 +5,8 @@
 A specification and conformance test suite for the MeshCore mesh networking
 protocol. It contains:

-1. RFC-style spec documents in `spec/` (Markdown, using RFC 2119 language)
+1. RFC-style spec documents in `src/` (Markdown, using RFC 2119 language; this
+   is also the mdbook source root)
 2. JSON test vector corpus in `corpus/`
 3. Validation tooling in `tools/`

@@ -31,7 +32,8 @@ protocol. It contains:

 ## File Organization

- `spec/NN-topic.md` — Spec sections, numbered for reading order
+- `src/NN-topic.md` — Spec sections, numbered for reading order (mdbook root)
+- `src/SUMMARY.md` — mdbook table of contents; new chapters MUST be added here
 - `corpus/schema/` — JSON Schema for test vector validation
 - `corpus/{layer}/{type}/` — Test vectors organized by protocol layer
 - `tools/` — Python validation and generation scripts
@@ -14,7 +14,8 @@

 ## Editing the Specification

-1. Spec documents live in `spec/` and are numbered for reading order.
+1. Spec documents live in `src/` (the mdbook source root) and are numbered for
+   reading order. New chapters must also be listed in `src/SUMMARY.md`.
 2. Use RFC 2119 language (MUST, SHOULD, MAY) for normative requirements.
 3. Include ASCII wire format diagrams where applicable.
 4. Cross-reference related spec sections and test vector files.
@@ -3,6 +3,8 @@
 A comprehensive specification and conformance test suite for the
 [MeshCore](https://github.com/meshcore-dev/MeshCore) mesh networking protocol.

+**📖 Read the spec online:** <https://swaits.github.io/meshcore-spec/>
+
 MeshCore Spec aims to be the authoritative, machine-readable definition of the
 MeshCore wire format — much like [RubySpec](https://github.com/ruby/spec) became
 the definitive specification of the Ruby language. Any implementation that passes
@@ -38,12 +40,17 @@ before relying on the spec for anything load-bearing.

 ## What's Here

- **`spec/`** — RFC-style protocol specification in Markdown, covering every
-  layer from packet framing to cryptographic operations.
+- **`src/`** — RFC-style protocol specification in Markdown, covering every
+  layer from packet framing to cryptographic operations. Also the source root
+  for the [mdBook](https://rust-lang.github.io/mdBook/) build published to
+  GitHub Pages.
 - **`corpus/`** — JSON test vectors organized by protocol layer.
  Each vector pairs a structured representation with its exact binary encoding,
  enabling any implementation to verify encode and decode correctness.
 - **`tools/`** — Validation and generation utilities.
+- **`book.toml`** + **`.github/workflows/mdbook.yml`** — mdBook configuration
+  and the GitHub Actions workflow that builds and deploys the spec on every
+  push to `main`.

 ## Test Vector Format

@@ -0,0 +1,22 @@
+[book]
+title = "MeshCore Protocol Specification"
+authors = ["Stephen Waits"]
+description = "An independent, AI-authored specification and conformance test corpus for the MeshCore mesh networking protocol. The official MeshCore C++ firmware is the source of truth; this spec is downstream."
+language = "en"
+src = "src"
+
+[output.html]
+default-theme = "navy"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/swaits/meshcore-spec"
+edit-url-template = "https://github.com/swaits/meshcore-spec/edit/main/{path}"
+site-url = "/meshcore-spec/"
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.search]
+enable = true
+limit-results = 20
+use-boolean-and = true
@@ -1,7 +1,7 @@
 {
  "$schema": "../schema/test-vector.schema.json",
  "name": "Bridge Protocol - Framing",
-  "spec_ref": "spec/20-bridge-protocol.md",
+  "spec_ref": "src/20-bridge-protocol.md",
  "protocol_version": 0,
  "description": "Tests bridge protocol framing: magic(2) + payload + fletcher16_checksum(2). RS232 variant adds length(2) between magic and payload.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../schema/test-vector.schema.json",
  "name": "Companion Protocol - Commands",
-  "spec_ref": "spec/18-companion-protocol.md",
+  "spec_ref": "src/18-companion-protocol.md",
  "protocol_version": 0,
  "description": "Tests companion protocol command type encoding for various command types.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../schema/test-vector.schema.json",
  "name": "Companion Protocol - Framing",
-  "spec_ref": "spec/18-companion-protocol.md",
+  "spec_ref": "src/18-companion-protocol.md",
  "protocol_version": 0,
  "description": "Tests companion protocol frame encoding: type byte followed by variable-length data.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../schema/test-vector.schema.json",
  "name": "Companion Protocol - Responses",
-  "spec_ref": "spec/18-companion-protocol.md",
+  "spec_ref": "src/18-companion-protocol.md",
  "protocol_version": 0,
  "description": "Tests companion protocol response type encoding.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "AES-128-ECB Block Padding",
-  "spec_ref": "spec/14-crypto.md",
+  "spec_ref": "src/14-crypto.md",
  "protocol_version": 0,
  "description": "Tests AES-128-ECB zero-padding for partial blocks. MeshCore pads the final block with zeros before encryption.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "AES-128-ECB Encryption",
-  "spec_ref": "spec/14-crypto.md",
+  "spec_ref": "src/14-crypto.md",
  "protocol_version": 0,
  "description": "Standalone AES-128-ECB encryption test vectors. Key is the first 16 bytes of the shared secret. These vectors test the raw encryption operation without MAC.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "ECDH Shared Secret (X25519)",
-  "spec_ref": "spec/15-identity.md",
+  "spec_ref": "src/15-identity.md",
  "protocol_version": 0,
  "description": "X25519 ECDH key exchange test vectors. MeshCore uses Ed25519 keys transposed to X25519 for key exchange. The resulting 32-byte shared secret is used as: AES key (bytes 0-15) and HMAC key (bytes 0-31).",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Ed25519 Sign/Verify",
-  "spec_ref": "spec/15-identity.md",
+  "spec_ref": "src/15-identity.md",
  "protocol_version": 0,
  "description": "Ed25519 signature test vectors. MeshCore uses Ed25519 for advertisement signing. These vectors use RFC 8032 test keypairs for cross-validation.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Encrypt-then-MAC Roundtrip",
-  "spec_ref": "spec/14-crypto.md",
+  "spec_ref": "src/14-crypto.md",
  "protocol_version": 0,
  "description": "Full encrypt-then-MAC pipeline test vectors. Each vector provides the shared secret, plaintext, and expected MAC+ciphertext output. Implementations should verify: (1) encrypt produces the ciphertext, (2) HMAC produces the MAC, (3) MACThenDecrypt recovers the plaintext.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "HMAC-SHA256 Truncated to 2 Bytes",
-  "spec_ref": "spec/14-crypto.md",
+  "spec_ref": "src/14-crypto.md",
  "protocol_version": 0,
  "description": "Tests HMAC-SHA256 computation with 32-byte key, truncated to CIPHER_MAC_SIZE (2 bytes). The HMAC key is the full 32-byte shared secret (PUB_KEY_SIZE), not just the 16-byte AES key.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "SHA-256 ACK CRC Computation",
-  "spec_ref": "spec/04-payload-ack.md",
+  "spec_ref": "src/04-payload-ack.md",
  "protocol_version": 0,
  "description": "Tests MeshCore ACK CRC computation: SHA-256(timestamp_le || txt_type_attempt || text || sender_pub_key)[0..3]. Each vector presents the full ACK packet that would be returned, along with the crypto_context showing the plaintext fed to SHA-256. Vectors ack-crc-001..004 share timestamp/text/pub_key and differ only in the attempt nibble of txt_type_attempt, demonstrating that each retry produces a distinct ACK CRC.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "SHA-256 Basic",
-  "spec_ref": "spec/14-crypto.md",
+  "spec_ref": "src/14-crypto.md",
  "protocol_version": 0,
  "description": "Basic SHA-256 hash computation test vectors. MeshCore uses SHA-256 for packet hashing, channel hash derivation, and HMAC.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "SHA-256 Packet Hash",
-  "spec_ref": "spec/16-packet-hash.md",
+  "spec_ref": "src/16-packet-hash.md",
  "protocol_version": 0,
  "description": "Tests MeshCore packet hash computation: SHA-256(payload_type || payload)[0..7]. TRACE packets additionally include path_len in the hash input.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../schema/test-vector.schema.json",
  "name": "KISS Protocol - Framing",
-  "spec_ref": "spec/19-kiss-protocol.md",
+  "spec_ref": "src/19-kiss-protocol.md",
  "protocol_version": 0,
  "description": "Tests KISS frame encoding including FEND delimiters, byte stuffing (FESC sequences), and type byte encoding.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../schema/test-vector.schema.json",
  "name": "KISS Protocol - SetHardware Extensions",
-  "spec_ref": "spec/19-kiss-protocol.md",
+  "spec_ref": "src/19-kiss-protocol.md",
  "protocol_version": 0,
  "description": "Tests MeshCore-specific SetHardware (0x06) sub-commands and responses.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../schema/test-vector.schema.json",
  "name": "KISS Protocol - Standard Commands",
-  "spec_ref": "spec/19-kiss-protocol.md",
+  "spec_ref": "src/19-kiss-protocol.md",
  "protocol_version": 0,
  "description": "Tests standard KISS commands (TXDELAY, Persistence, SlotTime, etc.).",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "ACK Payload - Basic",
-  "spec_ref": "spec/04-payload-ack.md",
+  "spec_ref": "src/04-payload-ack.md",
  "protocol_version": 0,
  "description": "Basic ACK payload encoding/decoding tests with various CRC values.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "ACK Payload - Boundary Values",
-  "spec_ref": "spec/04-payload-ack.md",
+  "spec_ref": "src/04-payload-ack.md",
  "protocol_version": 0,
  "description": "ACK CRC boundary value tests including all-zeros, all-ones, and single-bit patterns.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Advertisement App Data - Combined Optional Fields",
-  "spec_ref": "spec/05-payload-advert.md",
+  "spec_ref": "src/05-payload-advert.md",
  "protocol_version": 0,
  "description": "Tests app_data with multiple optional fields present simultaneously. Fields appear in order: flags, location (lat+lon), feat1, feat2, name.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Advertisement App Data - Location",
-  "spec_ref": "spec/05-payload-advert.md",
+  "spec_ref": "src/05-payload-advert.md",
  "protocol_version": 0,
  "description": "Tests app_data with location fields (latitude and longitude as int32_le × 1,000,000).",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Advertisement App Data - Node Types",
-  "spec_ref": "spec/05-payload-advert.md",
+  "spec_ref": "src/05-payload-advert.md",
  "protocol_version": 0,
  "description": "Tests all defined node types in the app_data flags field (bits 0-3). Uses a common pub_key, zero timestamp, and zero signature for structural testing.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Advertisement Payload - Basic Structure",
-  "spec_ref": "spec/05-payload-advert.md",
+  "spec_ref": "src/05-payload-advert.md",
  "protocol_version": 0,
  "description": "Tests the basic structure of advertisement payloads: pub_key(32) + timestamp(4) + signature(64) + optional app_data. Uses synthetic signature bytes since signature verification requires real Ed25519 operations (see signature-verify.json for verifiable vectors).",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Anonymous Request Payload",
-  "spec_ref": "spec/07-payload-anon-req.md",
+  "spec_ref": "src/07-payload-anon-req.md",
  "protocol_version": 0,
  "description": "Tests anonymous request payload: dest_hash(1) + sender_pub_key(32) + cipher_mac(2) + ciphertext.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Control Payload - Basic",
-  "spec_ref": "spec/12-payload-control.md",
+  "spec_ref": "src/12-payload-control.md",
  "protocol_version": 0,
  "description": "Tests control payload encoding. Control packets carry raw bytes where the first byte's bit 7 indicates zero-hop-only restriction.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Encrypted Payload - Basic",
-  "spec_ref": "spec/06-payload-encrypted.md",
+  "spec_ref": "src/06-payload-encrypted.md",
  "protocol_version": 0,
  "description": "Tests encrypted payload encoding (REQ/RESPONSE/TXT_MSG) with known cryptographic material. Uses shared_secret = 0x000102...1F, AES key = first 16 bytes, HMAC key = full 32 bytes.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Encrypted Payload - MAC Verification",
-  "spec_ref": "spec/06-payload-encrypted.md",
+  "spec_ref": "src/06-payload-encrypted.md",
  "protocol_version": 0,
  "description": "Tests MAC verification: valid MACs must pass, tampered MACs or ciphertext must fail.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Encrypted Payload - AES Block Padding",
-  "spec_ref": "spec/06-payload-encrypted.md",
+  "spec_ref": "src/06-payload-encrypted.md",
  "protocol_version": 0,
  "description": "Tests AES-128-ECB zero-padding behavior at block boundaries. Plaintexts of 1, 15, 16, 17, and 32 bytes exercise all padding edge cases.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Encrypted Payload - Roundtrip Verification",
-  "spec_ref": "spec/06-payload-encrypted.md",
+  "spec_ref": "src/06-payload-encrypted.md",
  "protocol_version": 0,
  "description": "Roundtrip encrypt-then-MAC verification vectors. Each vector provides full key material enabling implementations to verify: (1) encryption produces the given ciphertext, (2) MAC computation produces the given MAC, (3) MAC verification succeeds, (4) decryption recovers the plaintext.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Encrypted Payload - Extra Edge Cases",
-  "spec_ref": "spec/06-payload-encrypted.md",
+  "spec_ref": "src/06-payload-encrypted.md",
  "protocol_version": 0,
  "description": "Additional encrypted payload tests: non-FLOOD routes, hash_size>1 paths, 32-byte plaintext, and payload-level invalid cases.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Group Data Payload",
-  "spec_ref": "spec/08-payload-group.md",
+  "spec_ref": "src/08-payload-group.md",
  "protocol_version": 0,
  "description": "Tests group datagram payload. Same wire format as GRP_TXT but payload type = 0x06.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Group Text Payload",
-  "spec_ref": "spec/08-payload-group.md",
+  "spec_ref": "src/08-payload-group.md",
  "protocol_version": 0,
  "description": "Tests group text message payload: channel_hash(1) + cipher_mac(2) + ciphertext.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Multipart Payload - Basic",
-  "spec_ref": "spec/11-payload-multipart.md",
+  "spec_ref": "src/11-payload-multipart.md",
  "protocol_version": 0,
  "description": "Tests multipart payload encoding: first byte = (remaining << 4) | sub_type. Currently only multipart ACK (sub_type=3) is defined.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Path Return Payload - Basic",
-  "spec_ref": "spec/09-payload-path.md",
+  "spec_ref": "src/09-payload-path.md",
  "protocol_version": 0,
  "description": "Tests path return payload outer structure: dest_hash(1) + src_hash(1) + encrypt-then-MAC. The encrypted inner format contains path_len + path + extra_type + extra_data.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Raw Custom Payload - Basic",
-  "spec_ref": "spec/13-payload-raw-custom.md",
+  "spec_ref": "src/13-payload-raw-custom.md",
  "protocol_version": 0,
  "description": "Tests raw custom payload encoding. RAW_CUSTOM carries application-defined raw bytes.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Trace Payload - Basic",
-  "spec_ref": "spec/10-payload-trace.md",
+  "spec_ref": "src/10-payload-trace.md",
  "protocol_version": 0,
  "description": "Tests the basic 9-byte TRACE payload structure: tag(4) + auth_code(4) + flags(1).",
  "vectors": [
@@ -17,7 +17,7 @@
    },
    "spec_ref": {
      "type": "string",
-      "description": "Path to the relevant spec section (e.g., 'spec/01-wire-format.md')"
+      "description": "Path to the relevant spec section (e.g., 'src/01-wire-format.md')"
    },
    "protocol_version": {
      "type": "integer",
@@ -1,7 +1,7 @@
 {
  "$schema": "../../../schema/test-vector.schema.json",
  "name": "Framing - Decode Only",
-  "spec_ref": "spec/01-wire-format.md",
+  "spec_ref": "src/01-wire-format.md",
  "protocol_version": 0,
  "description": "Tests one-way decode cases where the binary is valid to decode but may not be the canonical encoding a conformant encoder would produce.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Framing - Empty Payload Rejection",
-  "spec_ref": "spec/01-wire-format.md",
+  "spec_ref": "src/01-wire-format.md",
  "protocol_version": 0,
  "description": "Verifies that packets with zero-length payload are rejected. The reference implementation (Packet::readFrom) checks 'if (i >= len) return false' after reading header+transport+path_len+path, requiring at least 1 byte of payload.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Framing - Maximum Size Packets",
-  "spec_ref": "spec/01-wire-format.md",
+  "spec_ref": "src/01-wire-format.md",
  "protocol_version": 0,
  "description": "Tests packets at or near the maximum wire size of 255 bytes (MAX_TRANS_UNIT). Verifies size calculation: total = 1 (header) + transport(0|4) + 1 (path_len) + path_bytes + payload_len.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Framing - Minimal Valid Packets",
-  "spec_ref": "spec/01-wire-format.md",
+  "spec_ref": "src/01-wire-format.md",
  "protocol_version": 0,
  "description": "Tests the smallest valid packets for each route type. A valid packet must have at least header(1) + path_len(1) + payload(1+) bytes, plus 4 bytes for transport codes if applicable.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Header - Combined Field Encoding",
-  "spec_ref": "spec/02-header.md",
+  "spec_ref": "src/02-header.md",
  "protocol_version": 0,
  "description": "Combinatorial tests of header byte encoding, exercising various combinations of version, payload type, and route type to verify correct bit packing.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Header - Payload Types",
-  "spec_ref": "spec/02-header.md",
+  "spec_ref": "src/02-header.md",
  "protocol_version": 0,
  "description": "Tests encoding of all defined payload types in the header byte. Uses FLOOD routing and minimal payloads to isolate header encoding.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Header - Route Types",
-  "spec_ref": "spec/02-header.md",
+  "spec_ref": "src/02-header.md",
  "protocol_version": 0,
  "description": "Tests encoding and decoding of all 4 route types in the header byte, using ACK (payload_type=3) as a simple payload.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Header - Protocol Versions",
-  "spec_ref": "spec/02-header.md",
+  "spec_ref": "src/02-header.md",
  "protocol_version": 0,
  "description": "Tests encoding of all 4 protocol version values in header bits 6-7. Uses ACK (type=3) with FLOOD routing as a simple baseline.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Invalid - Bad Path Length Encoding",
-  "spec_ref": "spec/03-path.md",
+  "spec_ref": "src/03-path.md",
  "protocol_version": 0,
  "description": "Tests invalid path_len values including the reserved hash_size=4 and path overflow conditions.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Invalid - Too Short Packets",
-  "spec_ref": "spec/01-wire-format.md",
+  "spec_ref": "src/01-wire-format.md",
  "protocol_version": 0,
  "description": "Tests packets that are shorter than the minimum required size for their route type.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Invalid - Truncated Packets",
-  "spec_ref": "spec/01-wire-format.md",
+  "spec_ref": "src/01-wire-format.md",
  "protocol_version": 0,
  "description": "Tests packets that are truncated at various points, verifying that decoders reject them gracefully.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Path - Boundary Conditions",
-  "spec_ref": "spec/03-path.md",
+  "spec_ref": "src/03-path.md",
  "protocol_version": 0,
  "description": "Tests boundary conditions for path encoding including maximum valid values and values just below overflow thresholds.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Path - Hash Counts",
-  "spec_ref": "spec/03-path.md",
+  "spec_ref": "src/03-path.md",
  "protocol_version": 0,
  "description": "Tests various hash count values including zero, small, and maximum values for each hash size.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Path - Hash Sizes",
-  "spec_ref": "spec/03-path.md",
+  "spec_ref": "src/03-path.md",
  "protocol_version": 0,
  "description": "Tests all valid hash sizes (1, 2, 3 bytes) in the path length encoding. These vectors are critical for catching implementations that treat path_len as a raw byte count.",
  "vectors": [
@@ -1,7 +1,7 @@
 {
  "$schema": "../../schema/test-vector.schema.json",
  "name": "Transport Codes - Basic",
-  "spec_ref": "spec/01-wire-format.md",
+  "spec_ref": "src/01-wire-format.md",
  "protocol_version": 0,
  "description": "Tests transport code encoding with various values and route types that include/exclude transport codes.",
  "vectors": [
@@ -0,0 +1,35 @@
+# Summary
+
+[Introduction](00-overview.md)
+
+# Wire Format
+
+- [Wire Format](01-wire-format.md)
+- [Header](02-header.md)
+- [Path](03-path.md)
+
+# Payloads
+
+- [ACK](04-payload-ack.md)
+- [Advertisement](05-payload-advert.md)
+- [Encrypted (REQ / RESPONSE / TXT_MSG)](06-payload-encrypted.md)
+- [Anonymous Request](07-payload-anon-req.md)
+- [Group (GRP_TXT / GRP_DATA)](08-payload-group.md)
+- [Path Return](09-payload-path.md)
+- [Trace](10-payload-trace.md)
+- [Multipart](11-payload-multipart.md)
+- [Control](12-payload-control.md)
+- [Raw Custom](13-payload-raw-custom.md)
+
+# Cryptography & Identity
+
+- [Cryptography](14-crypto.md)
+- [Identity](15-identity.md)
+- [Packet Hash](16-packet-hash.md)
+
+# Routing & Higher-Layer Protocols
+
+- [Routing](17-routing.md)
+- [Companion Protocol](18-companion-protocol.md)
+- [KISS Modem Protocol](19-kiss-protocol.md)
+- [Bridge Protocol](20-bridge-protocol.md)