diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
new file mode 100644
index 0000000..c142d75
--- /dev/null
+++ b/.github/workflows/validate.yml
@@ -0,0 +1,85 @@
+# Static validation plus per-language template smoke builds.
+#
+# What CI can and cannot verify: these jobs only run scripts/validate.py and
+# build the hello-syscall templates. They CANNOT run the demos that need a
+# KVM/libvirt VM, root privileges, or the LGTM stack — none of that exists on
+# GitHub-hosted runners. The authoritative gate for the book remains a host
+# run of scripts/test-all-examples.py against the real VM lab.
+
+name: validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # Needed for validate.py's Lua syntax pass; non-fatal so a transient
+      # apt outage doesn't block the whole workflow (validate.py skips the
+      # pass when lua5.4 is absent).
+      - name: Install Lua 5.4 (best effort)
+        run: sudo apt-get update && sudo apt-get install -y lua5.4 || echo "lua5.4 install failed; Lua syntax pass will be skipped"
+
+      - name: Run validate.py
+        run: python3 scripts/validate.py
+
+  smoke-go:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v5
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: examples/_template/go/go.mod
+
+      - name: Build Go template
+        working-directory: examples/_template/go
+        run: go build ./...
+
+  smoke-rust:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v5
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: "1.97.1"
+
+      - name: Build Rust template
+        working-directory: examples/_template/rust
+        run: cargo build --release
+
+  smoke-cpp:
+    runs-on: ubuntu-latest
+    # Match the book's primary toolchain (Fedora GCC) rather than Ubuntu's.
+    container: fedora:44
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v5
+
+      - name: Install toolchain
+        run: dnf install -y gcc-c++ cmake ninja-build
+
+      - name: Build C++ template
+        working-directory: examples/_template/cpp
+        run: |
+          cmake --preset release
+          cmake --build --preset release
diff --git a/.gitignore b/.gitignore
index 28d1dc4..7123213 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,3 +21,4 @@ __pycache__/
 
 # Reports
 reports/
+build-logs/
diff --git a/examples/_infra/README.md b/examples/_infra/README.md
new file mode 100644
index 0000000..f77880a
--- /dev/null
+++ b/examples/_infra/README.md
@@ -0,0 +1,60 @@
+# Shared example infrastructure
+
+Host-side services that some examples depend on. Today that is one thing: the
+Grafana LGTM observability stack (Loki + Grafana + Tempo + Mimir, with a
+built-in OpenTelemetry Collector), run as a single container via podman compose.
+
+## LGTM stack
+
+### Start / stop
+
+From the repo root:
+
+```sh
+podman compose -f examples/_infra/compose-lgtm.yaml up -d
+podman compose -f examples/_infra/compose-lgtm.yaml down
+```
+
+The container is named `lsp-lgtm` and has a healthcheck; wait for it to report
+healthy before pointing examples at it (first boot can take ~30s):
+
+```sh
+podman inspect --format '{{.State.Health.Status}}' lsp-lgtm
+```
+
+### Ports
+
+| Port | Purpose |
+|------|---------|
+| 3000 | Grafana UI (`http://localhost:3000`, anonymous admin) |
+| 4317 | OTLP gRPC ingest |
+| 4318 | OTLP HTTP ingest |
+
+### How examples declare the dependency
+
+An example that emits telemetry declares the stack in its manifest:
+
+```yaml
+requires: [lgtm]
+```
+
+The verification harness reads this and checks that the OTLP port is reachable
+(via `expect_port_open`) before running the example, skipping (exit 77) when
+the stack is not up rather than failing.
+
+### Exporting from inside the lab VM
+
+Examples deployed to the lab VM (`TARGET=...` with `deploy-to-vm.sh`) cannot
+reach `localhost` on the host. From a libvirt guest on the default NAT network,
+the host is reachable at the network's gateway IP — on this lab that is
+`192.168.124.1` (libvirt's stock default is `192.168.122.1`; check yours with
+`ip route show default` inside the guest). Pass the endpoint through
+`OTEL_ENDPOINT`:
+
+```sh
+OTEL_ENDPOINT=http://192.168.124.1:4318 TARGET=systems-target ./demo.sh run
+```
+
+Verify the actual gateway from inside the guest with `ip route show default`
+if the network is not the libvirt default. Ports 4317/4318 must be open to the
+libvirt bridge on the host firewall (on Fedora: the `libvirt` firewalld zone).
diff --git a/examples/_infra/compose-lgtm.yaml b/examples/_infra/compose-lgtm.yaml
new file mode 100644
index 0000000..503787a
--- /dev/null
+++ b/examples/_infra/compose-lgtm.yaml
@@ -0,0 +1,39 @@
+# compose-lgtm.yaml
+#
+# Shared observability backend for the book's examples: the Grafana LGTM
+# all-in-one image (Grafana + Loki + Tempo + Mimir + Prometheus + the
+# OpenTelemetry Collector) as a single container on the host.
+#
+# Start/stop:
+#   podman compose -f examples/_infra/compose-lgtm.yaml up -d
+#   podman compose -f examples/_infra/compose-lgtm.yaml down
+#
+# Access after startup:
+#   Grafana UI:  http://localhost:3000
+#   OTLP gRPC:   localhost:4317
+#   OTLP HTTP:   http://localhost:4318
+
+services:
+  lgtm:
+    image: docker.io/grafana/otel-lgtm:0.8.1
+    container_name: lsp-lgtm
+    ports:
+      - "3000:3000"      # Grafana UI
+      - "4317:4317"      # OTLP gRPC
+      - "4318:4318"      # OTLP HTTP
+    mem_limit: 2g
+    environment:
+      # Anonymous admin access keeps local demos friction-free. Never ship this.
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+      - GF_AUTH_DISABLE_LOGIN_FORM=true
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3000/api/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 30s   # the all-in-one image takes a while on first boot
+
+networks:
+  default:
+    name: lsp-observability
diff --git a/examples/_template/README.md b/examples/_template/README.md
new file mode 100644
index 0000000..39b523c
--- /dev/null
+++ b/examples/_template/README.md
@@ -0,0 +1,51 @@
+# _template — hello-syscall
+
+The seed for every runnable example in the book. It implements the same tiny
+program three times — C++23, Go, and Rust — each printing exactly one line:
+
+```
+pid <PID> on <sysname> <release> (<machine>)
+```
+
+via `getpid(2)` + `uname(2)` equivalents, with each language's idiomatic error
+handling (`std::expected` / wrapped errors via `%w` / `rustix`).
+
+## Layout
+
+```
+_template/
+├── demo.sh      # dispatcher: ./demo.sh [cpp|go|rust|all|build] [args...]
+├── verify.lua   # automated check driven by CI
+├── cpp/         # CMake preset build, demo.sh
+├── go/          # go build, demo.sh
+└── rust/        # cargo build, demo.sh
+```
+
+## The demo contract
+
+Every language directory has a `demo.sh` with the same interface, identical
+across the whole book:
+
+- `./demo.sh` — build then run
+- `./demo.sh build` — build only
+- `./demo.sh run [args]` — run the built binary
+- With env `TARGET` set, `run` deploys the binary to that lab VM via
+  `scripts/lab/deploy-to-vm.sh "$TARGET" <binary> -- [args]` instead of
+  running locally.
+
+The top-level `demo.sh` here is only a dispatcher: `./demo.sh cpp run` execs
+`cpp/demo.sh run`; bare `./demo.sh` (or `all`) builds and runs all three.
+
+## Verification
+
+`verify.lua` is run from this directory with `LSP_LANG` set to one language at
+a time. It uses `scripts/lib/checks.lua` to run `./demo.sh $LSP_LANG run` and
+asserts the output matches `pid %d+ on Linux`. Exit 0 = pass, 1 = fail,
+77 = skip.
+
+## Mapping to a chapter
+
+Each chapter's example is a copy of this template (`scripts/new-example.sh
+NN-slug`) with the program body replaced by that chapter's code. Keep the
+demo contract and `verify.lua` shape intact so CI and the manifest
+(`examples/manifest.yaml`) keep working.
diff --git a/examples/_template/cpp/.clang-format b/examples/_template/cpp/.clang-format
new file mode 100644
index 0000000..2c8640f
--- /dev/null
+++ b/examples/_template/cpp/.clang-format
@@ -0,0 +1,8 @@
+---
+BasedOnStyle: LLVM
+Language: Cpp
+Standard: c++20
+IndentWidth: 4
+ColumnLimit: 100
+PointerAlignment: Left
+AllowShortFunctionsOnASingleLine: Inline
diff --git a/examples/_template/cpp/.clang-tidy b/examples/_template/cpp/.clang-tidy
new file mode 100644
index 0000000..2f275ba
--- /dev/null
+++ b/examples/_template/cpp/.clang-tidy
@@ -0,0 +1,11 @@
+---
+Checks: >
+  bugprone-*,
+  modernize-*,
+  performance-*,
+  readability-*,
+  -modernize-use-trailing-return-type,
+  -readability-identifier-length
+WarningsAsErrors: ''
+HeaderFilterRegex: '.*'
+FormatStyle: file
diff --git a/examples/_template/cpp/CMakeLists.txt b/examples/_template/cpp/CMakeLists.txt
new file mode 100644
index 0000000..6bdb445
--- /dev/null
+++ b/examples/_template/cpp/CMakeLists.txt
@@ -0,0 +1,8 @@
+cmake_minimum_required(VERSION 3.25)
+project(template_hello CXX)
+
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+add_executable(app src/main.cpp)
diff --git a/examples/_template/cpp/CMakePresets.json b/examples/_template/cpp/CMakePresets.json
new file mode 100644
index 0000000..e31bd2f
--- /dev/null
+++ b/examples/_template/cpp/CMakePresets.json
@@ -0,0 +1,62 @@
+{
+  "version": 6,
+  "cmakeMinimumRequired": { "major": 3, "minor": 25, "patch": 0 },
+  "configurePresets": [
+    {
+      "name": "_base",
+      "hidden": true,
+      "generator": "Ninja",
+      "binaryDir": "${sourceDir}/build/${presetName}",
+      "cacheVariables": {
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+      }
+    },
+    {
+      "name": "release",
+      "inherits": "_base",
+      "displayName": "Release (-O2 with debug info)",
+      "cacheVariables": { "CMAKE_BUILD_TYPE": "RelWithDebInfo" }
+    },
+    {
+      "name": "debug",
+      "inherits": "_base",
+      "displayName": "Debug",
+      "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" }
+    },
+    {
+      "name": "asan",
+      "inherits": "_base",
+      "displayName": "ASan + UBSan instrumented build",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "CMAKE_CXX_FLAGS": "-O1 -g -fno-omit-frame-pointer -fsanitize=address,undefined",
+        "CMAKE_EXE_LINKER_FLAGS": "-fsanitize=address,undefined"
+      }
+    },
+    {
+      "name": "release-clang",
+      "inherits": "release",
+      "displayName": "Release (clang)",
+      "cacheVariables": {
+        "CMAKE_C_COMPILER": "clang",
+        "CMAKE_CXX_COMPILER": "clang++"
+      }
+    },
+    {
+      "name": "debug-clang",
+      "inherits": "debug",
+      "displayName": "Debug (clang)",
+      "cacheVariables": {
+        "CMAKE_C_COMPILER": "clang",
+        "CMAKE_CXX_COMPILER": "clang++"
+      }
+    }
+  ],
+  "buildPresets": [
+    { "name": "release",       "configurePreset": "release" },
+    { "name": "debug",         "configurePreset": "debug" },
+    { "name": "asan",          "configurePreset": "asan" },
+    { "name": "release-clang", "configurePreset": "release-clang" },
+    { "name": "debug-clang",   "configurePreset": "debug-clang" }
+  ]
+}
diff --git a/examples/_template/cpp/demo.sh b/examples/_template/cpp/demo.sh
new file mode 100755
index 0000000..6af6509
--- /dev/null
+++ b/examples/_template/cpp/demo.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")"
+REPO_ROOT="$(cd ../../.. && pwd)"
+BIN=build/release/app
+
+build() {
+    cmake --preset release
+    cmake --build --preset release
+}
+
+run() {
+    if [[ ! -x "$BIN" ]]; then
+        build
+    fi
+    if [[ -n "${TARGET:-}" ]]; then
+        "$REPO_ROOT/scripts/lab/deploy-to-vm.sh" "$TARGET" "$BIN" -- "$@"
+    else
+        "./$BIN" "$@"
+    fi
+}
+
+case "${1:-}" in
+    build)
+        build
+        ;;
+    run)
+        shift
+        run "$@"
+        ;;
+    "")
+        build
+        run
+        ;;
+    *)
+        echo "usage: $0 [build|run [args]]" >&2
+        exit 2
+        ;;
+esac
diff --git a/examples/_template/cpp/src/main.cpp b/examples/_template/cpp/src/main.cpp
new file mode 100644
index 0000000..74a956e
--- /dev/null
+++ b/examples/_template/cpp/src/main.cpp
@@ -0,0 +1,32 @@
+// hello-syscall: print "pid <PID> on <sysname> <release> (<machine>)" via getpid(2) + uname(2).
+
+#include <cerrno>
+#include <cstdio>
+#include <expected>
+#include <print>
+#include <system_error>
+
+#include <sys/utsname.h>
+#include <unistd.h>
+
+namespace {
+
+[[nodiscard]] std::expected<utsname, std::error_code> system_info() {
+    utsname info{};
+    if (::uname(&info) != 0) {
+        return std::unexpected(std::error_code{errno, std::system_category()});
+    }
+    return info;
+}
+
+} // namespace
+
+int main() {
+    const auto info = system_info();
+    if (!info) {
+        std::println(stderr, "uname failed: {}", info.error().message());
+        return 1;
+    }
+    std::println("pid {} on {} {} ({})", ::getpid(), info->sysname, info->release, info->machine);
+    return 0;
+}
diff --git a/examples/_template/demo.sh b/examples/_template/demo.sh
new file mode 100755
index 0000000..afbbe4c
--- /dev/null
+++ b/examples/_template/demo.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")"
+
+langs=(cpp go rust)
+
+case "${1:-all}" in
+  cpp|go|rust)
+    lang="$1"
+    shift
+    exec "./$lang/demo.sh" "$@"
+    ;;
+  all)
+    for lang in "${langs[@]}"; do "./$lang/demo.sh"; done
+    ;;
+  build)
+    for lang in "${langs[@]}"; do "./$lang/demo.sh" build; done
+    ;;
+  *)
+    echo "usage: $0 [cpp|go|rust|all|build] [args...]" >&2
+    exit 2
+    ;;
+esac
diff --git a/examples/_template/go/demo.sh b/examples/_template/go/demo.sh
new file mode 100755
index 0000000..28606df
--- /dev/null
+++ b/examples/_template/go/demo.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")"
+REPO_ROOT="$(cd ../../.. && pwd)"
+BIN=bin/app
+
+build() {
+  go build -o "$BIN" .
+}
+
+run() {
+  if [[ -n "${TARGET:-}" ]]; then
+    exec "$REPO_ROOT/scripts/lab/deploy-to-vm.sh" "$TARGET" "$BIN" -- "$@"
+  fi
+  exec "./$BIN" "$@"
+}
+
+case "${1:-}" in
+  build) build ;;
+  run)   shift; run "$@" ;;
+  "")    build; run ;;
+  *)     echo "usage: $0 [build|run [args...]]" >&2; exit 2 ;;
+esac
diff --git a/examples/_template/go/go.mod b/examples/_template/go/go.mod
new file mode 100644
index 0000000..032b7d8
--- /dev/null
+++ b/examples/_template/go/go.mod
@@ -0,0 +1,7 @@
+module github.com/patterncatalyst/linux-systems-programming/examples/_template/go
+
+go 1.26
+
+toolchain go1.26.5
+
+require golang.org/x/sys v0.47.0
diff --git a/examples/_template/go/go.sum b/examples/_template/go/go.sum
new file mode 100644
index 0000000..37ee2d4
--- /dev/null
+++ b/examples/_template/go/go.sum
@@ -0,0 +1,2 @@
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
diff --git a/examples/_template/go/main.go b/examples/_template/go/main.go
new file mode 100644
index 0000000..98d75b2
--- /dev/null
+++ b/examples/_template/go/main.go
@@ -0,0 +1,30 @@
+// hello-syscall: print "pid <PID> on <sysname> <release> (<machine>)".
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"golang.org/x/sys/unix"
+)
+
+func helloLine() (string, error) {
+	var uts unix.Utsname
+	if err := unix.Uname(&uts); err != nil {
+		return "", fmt.Errorf("uname: %w", err)
+	}
+	return fmt.Sprintf("pid %d on %s %s (%s)",
+		unix.Getpid(),
+		unix.ByteSliceToString(uts.Sysname[:]),
+		unix.ByteSliceToString(uts.Release[:]),
+		unix.ByteSliceToString(uts.Machine[:])), nil
+}
+
+func main() {
+	line, err := helloLine()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "error:", err)
+		os.Exit(1)
+	}
+	fmt.Println(line)
+}
diff --git a/examples/_template/rust/Cargo.lock b/examples/_template/rust/Cargo.lock
new file mode 100644
index 0000000..9fc0988
--- /dev/null
+++ b/examples/_template/rust/Cargo.lock
@@ -0,0 +1,66 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+
+[[package]]
+name = "template-hello"
+version = "0.1.0"
+dependencies = [
+ "rustix",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
diff --git a/examples/_template/rust/Cargo.toml b/examples/_template/rust/Cargo.toml
new file mode 100644
index 0000000..62c962f
--- /dev/null
+++ b/examples/_template/rust/Cargo.toml
@@ -0,0 +1,11 @@
+[package]
+name = "template-hello"
+version = "0.1.0"
+edition = "2024"
+
+[[bin]]
+name = "app"
+path = "src/main.rs"
+
+[dependencies]
+rustix = { version = "1", features = ["system"] }
diff --git a/examples/_template/rust/demo.sh b/examples/_template/rust/demo.sh
new file mode 100755
index 0000000..220feea
--- /dev/null
+++ b/examples/_template/rust/demo.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+BIN=target/release/app
+
+build() {
+  cargo build --release
+}
+
+run() {
+  if [[ -n "${TARGET:-}" ]]; then
+    local repo_root
+    repo_root=$(cd ../../.. && pwd)
+    "$repo_root/scripts/lab/deploy-to-vm.sh" "$TARGET" "$BIN" -- "$@"
+  else
+    "./$BIN" "$@"
+  fi
+}
+
+case "${1:-}" in
+  build) build ;;
+  run) shift; run "$@" ;;
+  "") build; run ;;
+  *) echo "usage: $0 [build|run [args...]]" >&2; exit 2 ;;
+esac
diff --git a/examples/_template/rust/rust-toolchain.toml b/examples/_template/rust/rust-toolchain.toml
new file mode 100644
index 0000000..4099f1a
--- /dev/null
+++ b/examples/_template/rust/rust-toolchain.toml
@@ -0,0 +1,3 @@
+[toolchain]
+channel = "1.97.1"
+components = ["rustfmt", "clippy", "rust-src"]
diff --git a/examples/_template/rust/src/main.rs b/examples/_template/rust/src/main.rs
new file mode 100644
index 0000000..9536d12
--- /dev/null
+++ b/examples/_template/rust/src/main.rs
@@ -0,0 +1,12 @@
+use rustix::system::uname;
+
+fn main() {
+    let info = uname();
+    println!(
+        "pid {} on {} {} ({})",
+        std::process::id(),
+        info.sysname().to_string_lossy(),
+        info.release().to_string_lossy(),
+        info.machine().to_string_lossy(),
+    );
+}
diff --git a/examples/_template/verify.lua b/examples/_template/verify.lua
new file mode 100644
index 0000000..230569e
--- /dev/null
+++ b/examples/_template/verify.lua
@@ -0,0 +1,17 @@
+-- Verify the hello-syscall template: run the demo for LSP_LANG and check its output.
+-- Invoked from the example directory with LSP_LANG (cpp|go|rust) and EXAMPLE_DIR set.
+
+local script_dir = arg[0]:match("(.*/)") or "./"
+local repo_root = os.getenv("REPO_ROOT") or (script_dir .. "../..")
+package.path = package.path .. ";" .. repo_root .. "/scripts/lib/?.lua"
+local checks = require("checks")
+
+local lang = os.getenv("LSP_LANG")
+if lang ~= "cpp" and lang ~= "go" and lang ~= "rust" then
+  checks.skip("LSP_LANG must be cpp|go|rust (got " .. tostring(lang) .. ")")
+end
+
+local r = checks.run("./demo.sh " .. lang .. " run")
+checks.expect_exit(r, 0, lang .. ": demo exits 0")
+checks.expect_match(r.out, "pid %d+ on Linux", lang .. ": prints pid/uname line")
+checks.finish()
diff --git a/examples/manifest.yaml b/examples/manifest.yaml
new file mode 100644
index 0000000..6337fb2
--- /dev/null
+++ b/examples/manifest.yaml
@@ -0,0 +1,15 @@
+# Manifest of runnable examples — one entry per directory under examples/.
+#
+# Fields:
+#   id:       directory name under examples/ (e.g. 02-hello-syscall)
+#   langs:    languages implemented; subset of [cpp, go, rust]
+#   mode:     local    — build and run on the host
+#             vm       — run the built binary inside a lab VM (TARGET set)
+#             vm-peer  — needs two lab VMs talking to each other
+#   requires: optional prerequisites, e.g. [lgtm] for the observability stack
+#   timeout:  per-language verification budget in seconds
+examples:
+  - id: _template
+    langs: [cpp, go, rust]
+    mode: local
+    timeout: 180
diff --git a/scripts/check-host.sh b/scripts/check-host.sh
new file mode 100755
index 0000000..43c09ca
--- /dev/null
+++ b/scripts/check-host.sh
@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# Verify the Fedora 44 host has every prerequisite the demos and the
+# KVM lab need. Prints a table of PASS / WARN / FAIL lines and exits
+# non-zero if any hard requirement fails.
+#
+# Run this once after following §2's installation steps, and re-run
+# any time you change toolchains.
+#
+# Deliberately no -e: failing checks are recorded in the table, not
+# fatal on the spot.
+set -uo pipefail
+
+# ── Colors ───────────────────────────────────────────────────────────────
+# Honor NO_COLOR if set or if stdout is not a tty.
+if [[ -t 1 ]] && [[ -z "${NO_COLOR:-}" ]]; then
+    C_RED=$'\033[31m'
+    C_GREEN=$'\033[32m'
+    C_YELLOW=$'\033[33m'
+    C_RESET=$'\033[0m'
+else
+    C_RED=""
+    C_GREEN=""
+    C_YELLOW=""
+    C_RESET=""
+fi
+
+log_ok()   { printf '%s[ ok ]%s  %s\n' "$C_GREEN"  "$C_RESET" "$*"; }
+log_warn() { printf '%s[warn]%s  %s\n' "$C_YELLOW" "$C_RESET" "$*" >&2; }
+log_err()  { printf '%s[fail]%s  %s\n' "$C_RED"    "$C_RESET" "$*" >&2; }
+
+# ── Status table accumulator ─────────────────────────────────────────────
+# Status values:
+#   ok    — hard requirement satisfied
+#   fail  — hard requirement missing; gates exit code
+#   warn  — soft requirement missing; informational, doesn't gate exit
+PASS=0; FAIL=0; WARN=0
+TABLE=()
+
+record() {
+    local status="$1"; shift
+    local label="$1"; shift
+    local detail="$1"; shift
+    local hint="${1:-}"
+    case "$status" in
+        ok)
+            PASS=$((PASS + 1))
+            TABLE+=("$(printf '%s[ ok ]%s  %-32s  %s' "$C_GREEN" "$C_RESET" "$label" "$detail")")
+            ;;
+        warn)
+            WARN=$((WARN + 1))
+            TABLE+=("$(printf '%s[warn]%s  %-32s  %s' "$C_YELLOW" "$C_RESET" "$label" "$detail")")
+            if [[ -n "$hint" ]]; then
+                TABLE+=("        ↳ $hint")
+            fi
+            ;;
+        *)
+            FAIL=$((FAIL + 1))
+            TABLE+=("$(printf '%s[fail]%s  %-32s  %s' "$C_RED" "$C_RESET" "$label" "$detail")")
+            if [[ -n "$hint" ]]; then
+                TABLE+=("        ↳ $hint")
+            fi
+            ;;
+    esac
+}
+
+# check_version <label> <cmd> <version_arg> <min_major> <min_minor> [pkg]
+# Hard requirement: cmd exists and reports >= min_major.min_minor.
+check_version() {
+    local label="$1" cmd="$2" version_arg="$3" min_major="$4" min_minor="$5"
+    local pkg="${6:-$2}"
+    local found
+    if ! command -v "$cmd" >/dev/null 2>&1; then
+        record fail "$label" "not installed" "sudo dnf install -y $pkg"
+        return
+    fi
+    found="$($cmd $version_arg 2>&1 | head -1 | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1)"
+    if [[ -z "$found" ]]; then
+        record fail "$label" "unknown version" "verify with: $cmd $version_arg"
+        return
+    fi
+    local fmaj="${found%%.*}"
+    local fmin="${found#*.}"; fmin="${fmin%%.*}"
+    if (( fmaj > min_major )) || { (( fmaj == min_major )) && (( fmin >= min_minor )); }; then
+        record ok "$label" "$found"
+    else
+        record fail "$label" "$found" "Need >= $min_major.$min_minor; upgrade $pkg."
+    fi
+}
+
+# ── Distro ───────────────────────────────────────────────────────────────
+if [[ -r /etc/os-release ]]; then
+    # shellcheck disable=SC1091
+    . /etc/os-release
+    if [[ "${ID:-}" == fedora ]]; then
+        record ok "fedora baseline" "$PRETTY_NAME"
+    else
+        record warn "fedora baseline" \
+            "$PRETTY_NAME" \
+            "The book targets Fedora 44; expect package-name differences."
+    fi
+fi
+
+# ── C/C++ toolchain ──────────────────────────────────────────────────────
+check_version "gcc >= 14"    gcc   --version 14 0  gcc
+check_version "g++ >= 14"    g++   --version 14 0  gcc-c++
+check_version "cmake >= 3.25" cmake --version 3 25 cmake
+
+if command -v clang >/dev/null 2>&1; then
+    record ok "clang" "$(clang --version | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
+else
+    record fail "clang" "not installed" "sudo dnf install -y clang"
+fi
+
+if command -v ninja >/dev/null 2>&1; then
+    record ok "ninja" "$(ninja --version 2>/dev/null | head -1)"
+else
+    record fail "ninja" "not installed" "sudo dnf install -y ninja-build"
+fi
+
+# ── Go ───────────────────────────────────────────────────────────────────
+# Any modern go works to bootstrap: the go.mod toolchain directive
+# auto-downloads go1.26.5 on first build.
+if command -v go >/dev/null 2>&1; then
+    GO_VER="$(go version 2>/dev/null | grep -oE 'go[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1)"
+    if [[ "$GO_VER" == go1.26* ]]; then
+        record ok "go 1.26.x" "$GO_VER"
+    else
+        record warn "go 1.26.x" \
+            "${GO_VER:-unknown}" \
+            "toolchain directive auto-downloads go1.26.5 on first build."
+    fi
+else
+    record fail "go 1.26.x" "not installed" "sudo dnf install -y golang"
+fi
+
+# ── Rust ─────────────────────────────────────────────────────────────────
+# rustc must come from rustup so the pinned channel in rust-toolchain.toml
+# takes effect (Fedora's system rustc ignores it).
+if command -v rustup >/dev/null 2>&1 && command -v rustc >/dev/null 2>&1; then
+    RUSTC_VER="$(rustc --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
+    if [[ "$RUSTC_VER" == "1.97.1" ]]; then
+        record ok "rustc via rustup" "$RUSTC_VER"
+    else
+        record warn "rustc via rustup" \
+            "${RUSTC_VER:-unknown} (book pins 1.97.1)" \
+            "rust-toolchain.toml installs 1.97.1 on first build; or: rustup toolchain install 1.97.1"
+    fi
+else
+    record fail "rustc via rustup" \
+        "rustup and/or rustc not installed" \
+        "curl https://sh.rustup.rs -sSf | sh   (do not use Fedora's system rust)"
+fi
+
+if command -v cargo >/dev/null 2>&1; then
+    record ok "cargo" "$(cargo --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
+else
+    record fail "cargo" "not installed" "installed by rustup alongside rustc"
+fi
+
+# ── Lua / Python ─────────────────────────────────────────────────────────
+check_version "lua >= 5.4" lua -v 5 4 lua
+
+if command -v python3 >/dev/null 2>&1; then
+    record ok "python3" "$(python3 --version 2>&1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
+else
+    record fail "python3" "not installed" "sudo dnf install -y python3"
+fi
+
+# ── Containers ───────────────────────────────────────────────────────────
+check_version "podman >= 5.0" podman --version 5 0
+
+# ── KVM lab (libvirt) ────────────────────────────────────────────────────
+for pair in virsh:libvirt-client virt-install:virt-install qemu-img:qemu-img cloud-localds:cloud-utils; do
+    cmd="${pair%%:*}"; pkg="${pair##*:}"
+    if command -v "$cmd" >/dev/null 2>&1; then
+        record ok "$cmd" "$(command -v "$cmd")"
+    else
+        record fail "$cmd" "not installed" "sudo dnf install -y $pkg"
+    fi
+done
+
+if [[ -e /dev/kvm ]]; then
+    record ok "/dev/kvm" "present"
+else
+    record fail "/dev/kvm" \
+        "missing" \
+        "Enable VT-x/AMD-V in firmware; on a VM host, enable nested virt."
+fi
+
+# Warn-only: without libvirt group membership every virsh call needs sudo.
+if id -nG 2>/dev/null | tr ' ' '\n' | grep -qx libvirt; then
+    record ok "libvirt group" "$(id -un) is a member"
+else
+    record warn "libvirt group" \
+        "$(id -un) not a member" \
+        "sudo usermod -aG libvirt $(id -un) && re-login."
+fi
+
+# ── Misc tooling ─────────────────────────────────────────────────────────
+for tool in git gh; do
+    if command -v "$tool" >/dev/null 2>&1; then
+        record ok "$tool" "$(command -v "$tool")"
+    else
+        record fail "$tool" "not installed" "sudo dnf install -y $tool"
+    fi
+done
+
+# ── Soft requirements (warn only) ────────────────────────────────────────
+# Conan 2.x — only some C++ demos use it.
+if command -v conan >/dev/null 2>&1; then
+    CONAN_VER="$(conan --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
+    if [[ "${CONAN_VER%%.*}" == "2" ]]; then
+        record ok "conan 2.x" "$CONAN_VER"
+    else
+        record warn "conan 2.x" "${CONAN_VER:-unknown} (need 2.x)" \
+            "pip install --user 'conan>=2.0,<3.0'"
+    fi
+else
+    record warn "conan 2.x" "not installed" "pip install --user 'conan>=2.0,<3.0'"
+fi
+
+# ruby + bundler — only for previewing the Jekyll site locally.
+if command -v ruby >/dev/null 2>&1 && command -v bundler >/dev/null 2>&1; then
+    record ok "ruby + bundler" "$(ruby --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
+else
+    record warn "ruby + bundler" "not installed" \
+        "sudo dnf install -y ruby rubygem-bundler   (local Jekyll preview only)"
+fi
+
+# Go linters / debugger — used by CI; nice to have locally.
+for pair in "golangci-lint:see golangci-lint.run/docs/welcome/install" \
+            "staticcheck:go install honnef.co/go/tools/cmd/staticcheck@latest" \
+            "dlv:go install github.com/go-delve/delve/cmd/dlv@latest"; do
+    cmd="${pair%%:*}"; hint="${pair#*:}"
+    if command -v "$cmd" >/dev/null 2>&1; then
+        record ok "$cmd" "$(command -v "$cmd")"
+    else
+        record warn "$cmd" "not installed" "$hint"
+    fi
+done
+
+# ── Print the table ──────────────────────────────────────────────────────
+echo
+printf '%s\n' "${TABLE[@]}"
+echo
+TOTAL=$((PASS + FAIL))
+if (( FAIL == 0 )); then
+    log_ok "All ${TOTAL} required checks passed."
+    if (( WARN > 0 )); then
+        log_warn "${WARN} optional check(s) flagged warnings — review the table."
+    fi
+    exit 0
+else
+    log_err "${FAIL} of ${TOTAL} required checks failed. See messages above."
+    if (( WARN > 0 )); then
+        log_warn "Plus ${WARN} optional warning(s)."
+    fi
+    exit 1
+fi
diff --git a/scripts/lab/cloud-init/meta-data b/scripts/lab/cloud-init/meta-data
new file mode 100644
index 0000000..05c59a4
--- /dev/null
+++ b/scripts/lab/cloud-init/meta-data
@@ -0,0 +1 @@
+instance-id: systems-lab-001
diff --git a/scripts/lab/cloud-init/user-data.tmpl b/scripts/lab/cloud-init/user-data.tmpl
new file mode 100644
index 0000000..4da4c14
--- /dev/null
+++ b/scripts/lab/cloud-init/user-data.tmpl
@@ -0,0 +1,88 @@
+#cloud-config
+# cloud-init user-data template for the linux-systems-programming lab guests
+# (systems-target / systems-peer). Placeholders __HOSTNAME__ and __SSH_PUBKEY__
+# are filled by provision-vm.sh.
+hostname: __HOSTNAME__
+fqdn: __HOSTNAME__.lab
+
+users:
+  - name: fedora
+    sudo: ALL=(ALL) NOPASSWD:ALL
+    groups: [wheel]
+    shell: /bin/bash
+    lock_passwd: true
+    ssh_authorized_keys:
+      - __SSH_PUBKEY__
+
+# Grow the root filesystem to fill the overlay disk.
+growpart:
+  mode: auto
+  devices: ['/']
+
+package_update: true
+
+# --- Toolset -----------------------------------------------------------------
+# Observation-first: this book uses eBPF as tooling (bcc/bpftrace/bpftool), not
+# as a build target, so there is no clang/llvm/libbpf-devel build chain here.
+# The guest can BUILD all three languages locally for demos that must compile
+# in-VM (privilege, namespaces, glibc-parity fallback).
+packages:
+  # observation tooling (the point of the lab)
+  - kernel-headers
+  - bcc-tools
+  - bpftrace
+  - bpftool
+  - libbpf-tools          # precompiled CO-RE tools: opensnoop, execsnoop, biolatency...
+  - perf
+  - kernel-tools          # turbostat / cpupower
+  - strace
+  - ltrace
+  - gdb
+  - gdb-gdbserver
+  - valgrind
+  - sysstat
+  # analysis suites (Chapter 45; PCP runs from its container image, not here)
+  - cockpit
+  - cockpit-podman
+  - systemtap
+  - systemtap-runtime
+  # per-language toolchains for in-VM builds
+  - gcc
+  - gcc-c++
+  - clang
+  - cmake
+  - ninja-build
+  - golang
+  - rust
+  - cargo
+  - lua
+  # containers ON the guest (container/cgroup chapters)
+  - podman
+  - podman-compose
+  - crun
+  # networking (two-host demos + inspection)
+  - nmap-ncat
+  - socat
+  - iproute
+  - iputils
+  - tcpdump
+  - curl
+  # utility
+  - jq
+  - git
+  - tar
+
+# Installed ON DEMAND, not here — keep the base lean; a demo may lazily
+# `dnf install` what it alone needs, then re-snapshot 'lab-ready' to bake it in.
+# Candidates for this book: fio (block-IO load), cyclictest/rt-tests (ch 24/40),
+# numactl (ch 40).
+
+runcmd:
+  # Enable the Cockpit socket so the web console is reachable at :9090.
+  - [ systemctl, enable, --now, cockpit.socket ]
+  # Readiness stamp: bpftrace works and which kernel we're on.
+  - [ bash, -c, "bpftrace --version > /var/log/lab-ready 2>&1 || echo 'bpftrace: MISSING' > /var/log/lab-ready" ]
+  - [ bash, -c, "uname -r >> /var/log/lab-ready" ]
+  - [ bash, -c, "touch /var/lib/cloud/lab-provisioned" ]
+
+final_message: "lab guest __HOSTNAME__ is up after $UPTIME seconds"
diff --git a/scripts/lab/deploy-to-vm.sh b/scripts/lab/deploy-to-vm.sh
new file mode 100755
index 0000000..98b32f6
--- /dev/null
+++ b/scripts/lab/deploy-to-vm.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# deploy-to-vm.sh — copy a compiled binary to a lab guest and run it.
+#
+#   ./deploy-to-vm.sh systems-target ./build/release/app
+#   ./deploy-to-vm.sh systems-target ./build/release/app -- --port 9000
+#   SUDO=1 ./deploy-to-vm.sh systems-target ./build/release/pmon   # run as root
+#
+# Everything after `--` is passed to the binary on the guest. Most demos in
+# this book run unprivileged; set SUDO=1 for the ones that genuinely need root
+# (capabilities, namespaces, cgroup writes). The lab user has passwordless sudo.
+set -euo pipefail
+VM="${1:?usage: deploy-to-vm.sh <vm-name> <local-binary> [-- args...]}"
+BIN="${2:?need a local binary path}"
+shift 2
+[[ "${1:-}" == "--" ]] && shift || true
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+IP="$("$SCRIPT_DIR/vm-ip.sh" "$VM")"
+SSH_OPTS="-o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=$HOME/.ssh/known_hosts"
+REMOTE="/home/fedora/$(basename "$BIN")"
+
+echo "→ copying $(basename "$BIN") to fedora@$IP:$REMOTE"
+scp $SSH_OPTS "$BIN" "fedora@$IP:$REMOTE"
+ssh $SSH_OPTS "fedora@$IP" "chmod +x '$REMOTE'"
+
+# Demos set OTEL_ENDPOINT to the host stack (http://<gateway>:4318). sudo strips
+# the environment, so forward it explicitly as OTEL_EXPORTER_OTLP_ENDPOINT via
+# `env` — otherwise the guest binary falls back to its own localhost and no
+# telemetry reaches the host stack.
+RENV=""
+[[ -n "${OTEL_ENDPOINT:-}" ]] && RENV="OTEL_EXPORTER_OTLP_ENDPOINT='$OTEL_ENDPOINT'"
+
+echo "→ running on $VM (Ctrl-C to stop):"
+if [[ "${SUDO:-0}" == "1" ]]; then
+  exec ssh -t $SSH_OPTS "fedora@$IP" "sudo env $RENV '$REMOTE' $*"
+else
+  exec ssh -t $SSH_OPTS "fedora@$IP" "env $RENV '$REMOTE' $*"
+fi
diff --git a/scripts/lab/destroy-vm.sh b/scripts/lab/destroy-vm.sh
new file mode 100755
index 0000000..6238a70
--- /dev/null
+++ b/scripts/lab/destroy-vm.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# destroy-vm.sh — tear a guest all the way down, including its disks.
+#   ./destroy-vm.sh myproject-target
+set -euo pipefail
+export LIBVIRT_DEFAULT_URI="${LIBVIRT_DEFAULT_URI:-qemu:///system}"
+LAB_PREFIX="${LAB_PREFIX:-systems}"
+CACHE_DIR="${LAB_CACHE:-$HOME/.cache/${LAB_PREFIX}-lab}"
+VM="${1:?usage: destroy-vm.sh <vm-name>}"
+virsh destroy "$VM" 2>/dev/null || true
+virsh undefine "$VM" --remove-all-storage --nvram 2>/dev/null \
+  || virsh undefine "$VM" 2>/dev/null || true
+rm -f "$CACHE_DIR/${VM}.qcow2" "$CACHE_DIR/${VM}-seed.img"
+echo "destroyed $VM"
diff --git a/scripts/lab/lab-down.sh b/scripts/lab/lab-down.sh
new file mode 100755
index 0000000..6f33fef
--- /dev/null
+++ b/scripts/lab/lab-down.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# lab-down.sh — gracefully shut down the lab guests so nothing is left running.
+#   ./lab-down.sh            # ACPI shutdown of <prefix>-target and <prefix>-peer
+#   FORCE=1 ./lab-down.sh    # hard power-off any guest that ignores the ACPI request
+#
+# Run this when you're done. It does NOT delete anything — disks and snapshots
+# survive; bring the lab back with ./lab-up.sh.
+set -euo pipefail
+export LIBVIRT_DEFAULT_URI="${LIBVIRT_DEFAULT_URI:-qemu:///system}"
+LAB_PREFIX="${LAB_PREFIX:-systems}"
+TARGET="${TARGET_VM:-${LAB_PREFIX}-target}"; PEER="${PEER_VM:-${LAB_PREFIX}-peer}"
+
+for VM in "$TARGET" "$PEER"; do
+  virsh dominfo "$VM" >/dev/null 2>&1 || { echo "skip $VM (not defined)"; continue; }
+  state="$(virsh domstate "$VM" 2>/dev/null || echo unknown)"
+  if [ "$state" != "running" ]; then echo "$VM already $state"; continue; fi
+  echo "shutting down $VM ..."
+  virsh shutdown "$VM" >/dev/null 2>&1 || true
+done
+
+echo "waiting up to 60s for graceful shutdown ..."
+for _ in $(seq 1 60); do
+  running=0
+  for VM in "$TARGET" "$PEER"; do
+    [ "$(virsh domstate "$VM" 2>/dev/null || true)" = "running" ] && running=1
+  done
+  [ "$running" = 0 ] && break
+  sleep 1
+done
+
+for VM in "$TARGET" "$PEER"; do
+  [ "$(virsh domstate "$VM" 2>/dev/null || true)" = "running" ] || continue
+  if [ "${FORCE:-0}" = "1" ]; then
+    echo "forcing off $VM"; virsh destroy "$VM" >/dev/null 2>&1 || true
+  else
+    echo "WARNING: $VM still running (guest ignored ACPI). Re-run with FORCE=1 to power it off." >&2
+  fi
+done
+
+virsh list --all
+echo
+echo "note: if you run an observability stack (or any other container) on the host,"
+echo "      it is separate from these guests — stop it however you started it."
diff --git a/scripts/lab/lab-ips.sh b/scripts/lab/lab-ips.sh
new file mode 100755
index 0000000..e2c5dd3
--- /dev/null
+++ b/scripts/lab/lab-ips.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# lab-ips.sh — print the IPs of the two lab guests, for tests that drive traffic
+# between them.
+#   eval "$(./lab-ips.sh)"   # exports TARGET_IP and PEER_IP
+set -euo pipefail
+export LIBVIRT_DEFAULT_URI="${LIBVIRT_DEFAULT_URI:-qemu:///system}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LAB_PREFIX="${LAB_PREFIX:-systems}"
+TARGET="${TARGET_VM:-${LAB_PREFIX}-target}"; PEER="${PEER_VM:-${LAB_PREFIX}-peer}"
+ti="$("$SCRIPT_DIR/vm-ip.sh" "$TARGET" 2>/dev/null || true)"
+pi="$("$SCRIPT_DIR/vm-ip.sh" "$PEER" 2>/dev/null || true)"
+echo "export TARGET_IP=${ti}"
+echo "export PEER_IP=${pi}"
+[ -z "$pi" ] && echo "# peer '$PEER' has no IP — provision it: ./provision-vm.sh $PEER" >&2 || true
diff --git a/scripts/lab/lab-up.sh b/scripts/lab/lab-up.sh
new file mode 100755
index 0000000..a007240
--- /dev/null
+++ b/scripts/lab/lab-up.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# lab-up.sh — start the lab guests and print their IPs.
+#   export LAB_PREFIX=myproject
+#   ./lab-up.sh
+#   eval "$(./lab-up.sh --export)"   # also export TARGET_IP / PEER_IP into your shell
+#
+# Starts <prefix>-target and <prefix>-peer if defined but not running, then waits
+# for DHCP leases. If a guest isn't defined yet, it tells you to provision it.
+set -euo pipefail
+export LIBVIRT_DEFAULT_URI="${LIBVIRT_DEFAULT_URI:-qemu:///system}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LAB_PREFIX="${LAB_PREFIX:-systems}"
+TARGET="${TARGET_VM:-${LAB_PREFIX}-target}"; PEER="${PEER_VM:-${LAB_PREFIX}-peer}"
+
+for VM in "$TARGET" "$PEER"; do
+  if ! virsh dominfo "$VM" >/dev/null 2>&1; then
+    echo "skip $VM (not defined — provision it: $SCRIPT_DIR/provision-vm.sh $VM)" >&2
+    continue
+  fi
+  state="$(virsh domstate "$VM" 2>/dev/null || echo unknown)"
+  if [ "$state" = "running" ]; then echo "$VM already running"; else echo "starting $VM"; virsh start "$VM" >/dev/null 2>&1 || true; fi
+done
+
+echo "waiting for DHCP leases ..." >&2
+for _ in $(seq 1 30); do
+  ti="$("$SCRIPT_DIR/vm-ip.sh" "$TARGET" 2>/dev/null || true)"
+  [ -n "$ti" ] && break
+  sleep 2
+done
+
+if [ "${1:-}" = "--export" ]; then
+  exec "$SCRIPT_DIR/lab-ips.sh"
+fi
+"$SCRIPT_DIR/vm-ip.sh" "$TARGET" >/dev/null 2>&1 && echo "$TARGET: $("$SCRIPT_DIR/vm-ip.sh" "$TARGET")" || echo "$TARGET: no lease yet"
+"$SCRIPT_DIR/vm-ip.sh" "$PEER"   >/dev/null 2>&1 && echo "$PEER:   $("$SCRIPT_DIR/vm-ip.sh" "$PEER")"   || echo "$PEER:   no lease / not provisioned"
diff --git a/scripts/lab/provision-vm.sh b/scripts/lab/provision-vm.sh
new file mode 100755
index 0000000..016e085
--- /dev/null
+++ b/scripts/lab/provision-vm.sh
@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+#
+# provision-vm.sh — provision a Fedora KVM guest via cloud-init for a
+# systems-programming / kernel test lab.
+#
+#   export LAB_PREFIX=myproject          # names everything (default: lab)
+#   ./provision-vm.sh "$LAB_PREFIX-target"   # the deploy target
+#   ./provision-vm.sh "$LAB_PREFIX-peer"     # optional 2nd host for networking tests
+#
+# The VM name is just the argument — pass whatever you like; LAB_PREFIX only
+# provides sensible defaults elsewhere (lifecycle scripts, cache dir).
+#
+# Refuses to clobber an existing domain of the same name; run ./destroy-vm.sh
+# <name> first for a clean rebuild.
+#
+# Requires (host): virt-install, qemu-img, cloud-localds, libvirtd running, your
+# user in the `libvirt` group (or wrap via `sg libvirt -c '...'`). See
+# references/vm-lab.md.
+#
+# Downloads the Fedora Cloud Base qcow2 once into ~/.cache, then layers a per-VM
+# overlay disk so re-provisioning is cheap and the base stays pristine.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" && cd "$SCRIPT_DIR"
+export LIBVIRT_DEFAULT_URI="${LIBVIRT_DEFAULT_URI:-qemu:///system}"
+
+# ---- Config -----------------------------------------------------------------
+LAB_PREFIX="${LAB_PREFIX:-systems}"
+VM_NAME="${1:?usage: provision-vm.sh <vm-name>  (e.g. $LAB_PREFIX-target)}"
+VCPUS="${VCPUS:-2}"
+RAM_MB="${RAM_MB:-4096}"
+DISK_GB="${DISK_GB:-20}"
+NETWORK="${NETWORK:-default}"          # libvirt NAT network shared by all guests
+SSH_PUBKEY="${SSH_PUBKEY:-$HOME/.ssh/id_ed25519.pub}"
+
+# Fedora Cloud Base. Pin the exact image you tested; bump deliberately.
+FEDORA_VER="${FEDORA_VER:-44}"
+BASE_URL="https://download.fedoraproject.org/pub/fedora/linux/releases/${FEDORA_VER}/Cloud/x86_64/images"
+BASE_IMG="${BASE_IMG:-Fedora-Cloud-Base-Generic-${FEDORA_VER}-1.7.x86_64.qcow2}"  # verify exact name at the URL above
+CACHE_DIR="${LAB_CACHE:-$HOME/.cache/${LAB_PREFIX}-lab}"
+
+RED=$'\033[0;31m'; GRN=$'\033[0;32m'; CYN=$'\033[0;36m'; YLW=$'\033[1;33m'; RST=$'\033[0m'
+step() { echo "${CYN}━━ $*${RST}"; }
+ok()   { echo "${GRN}✓ $*${RST}"; }
+warn() { echo "${YLW}⚠ $*${RST}"; }
+die()  { echo "${RED}✗ $*${RST}" >&2; exit 1; }
+
+# ---- Pre-flight -------------------------------------------------------------
+command -v virt-install >/dev/null || die "virt-install not found (dnf install virt-install)"
+command -v cloud-localds >/dev/null || die "cloud-localds not found (dnf install cloud-utils)"
+[[ -f "$SSH_PUBKEY" ]] || die "no SSH public key at $SSH_PUBKEY — generate one: ssh-keygen -t ed25519"
+virsh dominfo "$VM_NAME" >/dev/null 2>&1 && \
+  die "domain '$VM_NAME' already exists — run ./destroy-vm.sh $VM_NAME first"
+
+mkdir -p "$CACHE_DIR"
+
+# ---- Base image -------------------------------------------------------------
+step "ensuring Fedora ${FEDORA_VER} Cloud Base image is cached"
+if [[ ! -f "$CACHE_DIR/$BASE_IMG" ]]; then
+  warn "downloading $BASE_IMG (verify the exact filename at $BASE_URL)"
+  curl -fL --retry 3 -o "$CACHE_DIR/$BASE_IMG" "$BASE_URL/$BASE_IMG"
+fi
+ok "base image present: $CACHE_DIR/$BASE_IMG"
+
+# ---- Per-VM overlay disk ----------------------------------------------------
+step "creating ${DISK_GB}G overlay disk for $VM_NAME"
+OVERLAY="$CACHE_DIR/${VM_NAME}.qcow2"
+qemu-img create -f qcow2 -F qcow2 -b "$CACHE_DIR/$BASE_IMG" "$OVERLAY" "${DISK_GB}G"
+ok "overlay: $OVERLAY"
+
+# ---- cloud-init seed --------------------------------------------------------
+step "building cloud-init seed for $VM_NAME"
+PUBKEY_CONTENT="$(cat "$SSH_PUBKEY")"
+TMP_USERDATA="$(mktemp)"
+sed -e "s|__HOSTNAME__|${VM_NAME}|g" \
+    -e "s|__SSH_PUBKEY__|${PUBKEY_CONTENT}|g" \
+    cloud-init/user-data.tmpl > "$TMP_USERDATA"
+SEED="$CACHE_DIR/${VM_NAME}-seed.img"
+cloud-localds "$SEED" "$TMP_USERDATA" cloud-init/meta-data
+rm -f "$TMP_USERDATA"
+ok "seed: $SEED"
+
+# ---- Boot the domain --------------------------------------------------------
+step "starting domain $VM_NAME ($VCPUS vCPU / ${RAM_MB}MB / ${DISK_GB}G) on network '$NETWORK'"
+virt-install \
+  --name "$VM_NAME" \
+  --memory "$RAM_MB" \
+  --vcpus "$VCPUS" \
+  --cpu host-passthrough \
+  --import \
+  --disk "path=$OVERLAY,format=qcow2,bus=virtio" \
+  --disk "path=$SEED,device=cdrom" \
+  --os-variant fedora-unknown \
+  --network "network=$NETWORK,model=virtio" \
+  --graphics none \
+  --noautoconsole
+
+ok "domain $VM_NAME created"
+echo
+echo "Wait ~60s for cloud-init, then find its IP:"
+echo "    ./vm-ip.sh $VM_NAME"
+echo "confirm it's ready (expect 'BTF: present'):"
+echo "    ssh fedora@\$(./vm-ip.sh $VM_NAME) 'cat /var/log/lab-ready'"
+echo "then snapshot the tooled baseline:"
+echo "    ./snapshot-vm.sh $VM_NAME"
diff --git a/scripts/lab/revert-vm.sh b/scripts/lab/revert-vm.sh
new file mode 100755
index 0000000..cf2f583
--- /dev/null
+++ b/scripts/lab/revert-vm.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# revert-vm.sh — restore a lab guest to a snapshot (default: lab-ready).
+#   ./revert-vm.sh myproject-target                 # revert to "lab-ready"
+#   ./revert-vm.sh myproject-target clean-updated   # revert to a named snapshot
+#
+# Use this to undo destructive/offensive demos, or to get back to a clean tooled
+# baseline. Reverting to a running-state snapshot restores it running.
+set -euo pipefail
+export LIBVIRT_DEFAULT_URI="${LIBVIRT_DEFAULT_URI:-qemu:///system}"
+VM="${1:?usage: revert-vm.sh <vm-name> [snapshot-name]}"
+SNAP="${2:-lab-ready}"
+virsh snapshot-info "$VM" "$SNAP" >/dev/null 2>&1 \
+  || { echo "no snapshot '$SNAP' on $VM — list with: virsh snapshot-list $VM" >&2; exit 1; }
+virsh snapshot-revert "$VM" "$SNAP"
+echo "$VM reverted to snapshot '$SNAP'"
diff --git a/scripts/lab/snapshot-vm.sh b/scripts/lab/snapshot-vm.sh
new file mode 100755
index 0000000..7550db0
--- /dev/null
+++ b/scripts/lab/snapshot-vm.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# snapshot-vm.sh — capture a named snapshot of a lab guest (default: lab-ready).
+#   ./snapshot-vm.sh myproject-target                 # snapshot named "lab-ready"
+#   ./snapshot-vm.sh myproject-target clean-updated   # a differently-named snapshot
+#
+# Take a snapshot after the guest is fully provisioned + tooled (cloud-init done,
+# your extra packages installed) so you can revert to a known-good state in
+# seconds instead of re-provisioning. Snapshots of a running guest capture RAM +
+# disk, so a revert restores it running.
+#
+# Uses the system libvirt instance; if your login shell isn't in the `libvirt`
+# group yet, run via: sg libvirt -c '...'.
+set -euo pipefail
+export LIBVIRT_DEFAULT_URI="${LIBVIRT_DEFAULT_URI:-qemu:///system}"
+VM="${1:?usage: snapshot-vm.sh <vm-name> [snapshot-name]}"
+SNAP="${2:-lab-ready}"
+virsh dominfo "$VM" >/dev/null 2>&1 || { echo "no such domain: $VM" >&2; exit 1; }
+# Replace an existing snapshot of the same name so re-running is idempotent.
+virsh snapshot-delete "$VM" "$SNAP" >/dev/null 2>&1 || true
+virsh snapshot-create-as "$VM" "$SNAP" \
+  --description "lab snapshot taken $(date -u +%FT%TZ)" --atomic
+echo "snapshot '$SNAP' created for $VM"
+virsh snapshot-list "$VM"
diff --git a/scripts/lab/vm-ip.sh b/scripts/lab/vm-ip.sh
new file mode 100755
index 0000000..a5cabbf
--- /dev/null
+++ b/scripts/lab/vm-ip.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# vm-ip.sh — print the IPv4 address libvirt leased to a guest.
+#   ./vm-ip.sh myproject-target
+set -euo pipefail
+export LIBVIRT_DEFAULT_URI="${LIBVIRT_DEFAULT_URI:-qemu:///system}"
+VM="${1:?usage: vm-ip.sh <vm-name>}"
+# Try the DHCP lease via the domain's interface; fall back to guest agent.
+ip=$(virsh -q domifaddr "$VM" 2>/dev/null | awk '/ipv4/ {sub(/\/.*/,"",$4); print $4; exit}')
+if [[ -z "${ip:-}" ]]; then
+  ip=$(virsh -q domifaddr "$VM" --source agent 2>/dev/null | awk '/ipv4/ {sub(/\/.*/,"",$4); print $4; exit}')
+fi
+[[ -n "${ip:-}" ]] || { echo "no lease yet for $VM — wait for cloud-init and retry" >&2; exit 1; }
+echo "$ip"
diff --git a/scripts/lib/_demo-bg.sh b/scripts/lib/_demo-bg.sh
new file mode 100755
index 0000000..c8241ad
--- /dev/null
+++ b/scripts/lib/_demo-bg.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# _demo-bg.sh — auto-cleanup for guest-side background jobs a demo starts.
+#
+# Demos sometimes drive a workload on the lab VM(s) in the background (nohup
+# load-generators, ncat listeners, churn loops). Those outlive the demo's
+# foreground process, so a plain Ctrl-C leaves them running and pinning the
+# VM's CPU. Source this and call `reap <ssh-target> <pattern>` once per
+# background workload the demo launches; on exit (normal or Ctrl-C) every
+# registered pattern is killed on its host.
+#
+#   reap "fedora@$TIP" target-app          # a named binary  -> pkill -x
+#   reap "fedora@$TIP" 'while true; do curl -s http://127.0.0.1:8080/'   # a loop -> pkill -f
+#
+# `reap` tries both `pkill -x` (exact process name) and `pkill -f` (command-line
+# substring), so either style of pattern works. The launch lines themselves stay
+# exactly as they are — this only registers what to clean up.
+
+_REAP_LIST=()
+reap() { _REAP_LIST+=("$1"$'\t'"$2"); }
+
+_reap_all() {
+    [ "${_REAPED:-0}" = 1 ] && return; _REAPED=1
+    [ ${#_REAP_LIST[@]} -eq 0 ] && return
+    local entry host pat ssho="-o StrictHostKeyChecking=accept-new -o ConnectTimeout=8"
+    for entry in "${_REAP_LIST[@]}"; do
+        host="${entry%%$'\t'*}"; pat="${entry#*$'\t'}"
+        ssh $ssho "$host" "pkill -f -- \"$pat\" 2>/dev/null; pkill -x -- \"$pat\" 2>/dev/null; true" \
+            </dev/null >/dev/null 2>&1 || true
+    done
+}
+
+# EXIT covers normal exit and `set -e` failures; INT/TERM route through exit so
+# the EXIT trap fires exactly once (guarded by _REAPED).
+trap _reap_all EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
diff --git a/scripts/lib/_helpers.sh b/scripts/lib/_helpers.sh
new file mode 100755
index 0000000..e4b14e0
--- /dev/null
+++ b/scripts/lib/_helpers.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Shared helpers for example demo scripts and the aggregator. Source this;
+# don't execute it directly. Handles colors, repo-root resolution, and
+# HTTP readiness waiting.
+
+if [[ -t 1 ]]; then
+    GREEN='\033[0;32m'; RED='\033[0;31m'; YELLOW='\033[1;33m'
+    CYAN='\033[0;36m'; BOLD='\033[1m'; NC='\033[0m'
+else
+    GREEN=''; RED=''; YELLOW=''; CYAN=''; BOLD=''; NC=''
+fi
+
+step()  { echo -e "${CYAN}━━ $*${NC}"; }
+pass()  { echo -e "${GREEN}✓ $*${NC}"; }
+fail()  { echo -e "${RED}✗ $*${NC}" >&2; exit 1; }
+info()  { echo -e "${YELLOW}  $*${NC}"; }
+
+repo_root() {
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        git rev-parse --show-toplevel
+    else
+        cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd
+    fi
+}
+
+# Wait up to N seconds for an HTTP endpoint. Use 127.0.0.1 not localhost.
+wait_for_http() {
+    local url="$1" timeout="${2:-30}" i
+    for ((i = 0; i < timeout; i++)); do
+        curl -fsS "$url" >/dev/null 2>&1 && return 0
+        sleep 1
+    done
+    return 1
+}
diff --git a/scripts/lib/checks.lua b/scripts/lib/checks.lua
new file mode 100644
index 0000000..f99fe6b
--- /dev/null
+++ b/scripts/lib/checks.lua
@@ -0,0 +1,84 @@
+-- checks.lua — tiny assertion helpers for verify.lua scripts (Lua 5.4, no deps).
+-- Failures print "FAIL: label" and are counted; nothing is fatal until finish().
+--
+--   local checks = require("checks")
+--   local r = checks.run("./demo.sh cpp run")
+--   checks.expect_exit(r, 0, "demo exits cleanly")
+--   checks.expect_match(r.out, "pid %d+ on Linux", "prints pid/uname line")
+--   checks.finish()
+
+local M = {}
+
+local npass, nfail = 0, 0
+
+local function ok(label)
+  npass = npass + 1
+  print("ok: " .. label)
+end
+
+local function bad(label, detail)
+  nfail = nfail + 1
+  print("FAIL: " .. label)
+  if detail then print("  " .. detail) end
+end
+
+-- Run a shell command; return {exit=<int>, out=<combined stdout+stderr>}.
+function M.run(cmd)
+  -- Subshell so the redirect covers every command in a compound cmd string.
+  local f = assert(io.popen("( " .. cmd .. " ) 2>&1", "r"))
+  local out = f:read("*a") or ""
+  local _, how, code = f:close()
+  local exit
+  if how == "exit" then
+    exit = code
+  elseif how == "signal" then
+    exit = 128 + code
+  else
+    exit = 0
+  end
+  return { exit = exit, out = out }
+end
+
+function M.expect_exit(r, code, label)
+  if r.exit == code then
+    ok(label)
+  else
+    bad(label, string.format("expected exit %d, got %d", code, r.exit))
+  end
+end
+
+-- pattern is a Lua pattern, not a regex.
+function M.expect_match(out, pattern, label)
+  if string.find(out, pattern) then
+    ok(label)
+  else
+    bad(label, "output did not match pattern: " .. pattern)
+  end
+end
+
+-- Probe a TCP port via nc when available, else bash's /dev/tcp.
+function M.expect_port_open(host, port, label)
+  local probe = string.format(
+    "if command -v nc >/dev/null 2>&1; then nc -z -w 2 '%s' %d; " ..
+    "else bash -c 'exec 3<>\"/dev/tcp/%s/%d\"'; fi",
+    host, port, host, port)
+  local r = M.run(probe)
+  if r.exit == 0 then
+    ok(label)
+  else
+    bad(label, string.format("port %s:%d not reachable", host, port))
+  end
+end
+
+-- Exit 77 (automake convention) so the aggregator can distinguish skips.
+function M.skip(reason)
+  print("SKIP: " .. reason)
+  os.exit(77)
+end
+
+function M.finish()
+  print(string.format("PASS %d / FAIL %d", npass, nfail))
+  os.exit(nfail > 0 and 1 or 0)
+end
+
+return M
diff --git a/scripts/new-example.sh b/scripts/new-example.sh
new file mode 100755
index 0000000..3dcd77e
--- /dev/null
+++ b/scripts/new-example.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo "usage: $(basename "$0") NN-slug    e.g. $(basename "$0") 02-hello-syscall" >&2
+  exit 2
+}
+
+[[ $# -eq 1 ]] || usage
+name="$1"
+[[ "$name" =~ ^[0-9]{2}-[a-z0-9][a-z0-9-]*$ ]] || usage
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+src="$repo_root/examples/_template"
+dst="$repo_root/examples/$name"
+
+[[ -d "$src" ]] || { echo "error: template not found: $src" >&2; exit 1; }
+[[ -e "$dst" ]] && { echo "error: refusing to overwrite existing $dst" >&2; exit 1; }
+
+cp -r "$src" "$dst"
+
+if [[ -f "$dst/go/go.mod" ]]; then
+  sed -i "s|_template|$name|g" "$dst/go/go.mod"
+else
+  echo "warning: $dst/go/go.mod not found; go module path not updated" >&2
+fi
+
+echo "Created examples/$name"
+echo "Next steps:"
+echo "  - add an entry for '$name' to examples/manifest.yaml"
+echo "  - update the matching chapter in _docs/"
diff --git a/scripts/test-all-examples.py b/scripts/test-all-examples.py
new file mode 100755
index 0000000..5d7949b
--- /dev/null
+++ b/scripts/test-all-examples.py
@@ -0,0 +1,429 @@
+#!/usr/bin/env python3
+"""Test orchestrator for the book's runnable examples.
+
+Reads examples/manifest.yaml, builds each selected example x language with
+"./demo.sh <lang> build" (optionally in parallel), then verifies sequentially
+with "lua verify.lua" (env LSP_LANG / EXAMPLE_DIR / REPO_ROOT; exit 77 = SKIP).
+
+VM-mode examples (mode: vm | vm-peer) verify STRICTLY serially against the lab
+guests; the lab is preflighted with scripts/lab/vm-ip.sh and an unreachable
+guest turns the example into a SKIP ("lab down"), never a FAIL. Examples with
+requires: [lgtm] are skipped when the local OTLP endpoint (localhost:4318)
+does not answer. Stdlib only.
+
+Usage:
+  scripts/test-all-examples.py [--only ID]... [--lang cpp|go|rust]...
+      [--mode local|vm|all] [--revert-between] [--junit PATH] [--jobs N]
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+MANIFEST = REPO_ROOT / "examples" / "manifest.yaml"
+LOG_DIR = REPO_ROOT / "build-logs"  # gitignored scratch output
+
+LANGS = ("cpp", "go", "rust")
+LAB_PREFIX = os.environ.get("LAB_PREFIX", "systems")
+TARGET_VM = f"{LAB_PREFIX}-target"
+PEER_VM = f"{LAB_PREFIX}-peer"
+LGTM_PROBE_URL = "http://localhost:4318"
+# Lua interpreter for verify.lua: $LUA overrides; else lua, else luajit.
+LUA = os.environ.get("LUA") or shutil.which("lua") or shutil.which("luajit") or "lua"
+
+BUILD_TIMEOUT = 900  # seconds per example-lang build
+VERIFY_TIMEOUT = 300  # seconds per verify.lua run
+
+
+# ---------------------------------------------------------------------------
+# Manifest parsing
+# ---------------------------------------------------------------------------
+
+class ManifestError(Exception):
+    pass
+
+
+def parse_manifest_subset(text: str) -> list[dict]:
+    """Strict-subset YAML parser used when PyYAML is unavailable.
+
+    Supports exactly the documented manifest schema and nothing more:
+      * full-line comments (#...) and blank lines
+      * one top-level key "examples:" introducing a list
+      * list items "- key: value" with further "key: value" lines indented
+        to the same column
+      * values are plain/quoted scalars or flow lists like [cpp, go]
+    No nested mappings, block lists, multiline scalars, anchors, or tags.
+    """
+    item_re = re.compile(r"^(\s*)-\s+([A-Za-z0-9_-]+):\s*(.*)$")
+    kv_re = re.compile(r"^(\s*)([A-Za-z0-9_-]+):\s*(.*)$")
+
+    def unquote(s: str) -> str:
+        if len(s) >= 2 and s[0] == s[-1] and s[0] in "'\"":
+            return s[1:-1]
+        return s
+
+    def parse_value(v: str, lineno: int):
+        v = v.strip()
+        if v.startswith("[") and v.endswith("]"):
+            inner = v[1:-1].strip()
+            return [unquote(p.strip()) for p in inner.split(",")] if inner else []
+        if not v:
+            raise ManifestError(f"manifest line {lineno}: empty value (block collections unsupported)")
+        return unquote(v)
+
+    examples: list[dict] = []
+    current: dict | None = None
+    in_examples = False
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        stripped = raw.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if not raw[0].isspace() and stripped != "examples:" and not stripped.startswith("- "):
+            in_examples = False  # some other top-level key: ignore its content
+            continue
+        if stripped == "examples:" and not raw[0].isspace():
+            in_examples = True
+            current = None
+            continue
+        if not in_examples:
+            continue
+        m = item_re.match(raw)
+        if m:
+            current = {m.group(2): parse_value(m.group(3), lineno)}
+            examples.append(current)
+            continue
+        m = kv_re.match(raw)
+        if m and current is not None:
+            current[m.group(2)] = parse_value(m.group(3), lineno)
+            continue
+        raise ManifestError(f"manifest line {lineno}: unsupported syntax: {stripped!r}")
+    return examples
+
+
+def load_manifest() -> list[dict]:
+    if not MANIFEST.is_file():
+        sys.exit(f"error: {MANIFEST} not found")
+    text = MANIFEST.read_text(encoding="utf-8")
+    try:
+        import yaml  # type: ignore
+        data = yaml.safe_load(text) or {}
+        raw = data.get("examples") or []
+    except ImportError:
+        raw = parse_manifest_subset(text)
+
+    examples = []
+    for i, ex in enumerate(raw):
+        if not isinstance(ex, dict) or "id" not in ex:
+            raise ManifestError(f"examples[{i}]: each entry needs at least 'id'")
+        langs = ex.get("langs", list(LANGS))
+        if isinstance(langs, str):
+            langs = [langs]
+        requires = ex.get("requires", [])
+        if isinstance(requires, str):
+            requires = [requires]
+        examples.append({
+            "id": str(ex["id"]),
+            "dir": str(ex.get("dir", f"examples/{ex['id']}")),
+            "langs": [str(l) for l in langs],
+            "mode": str(ex.get("mode", "local")),
+            "requires": [str(r) for r in requires],
+        })
+    return examples
+
+
+# ---------------------------------------------------------------------------
+# Result bookkeeping
+# ---------------------------------------------------------------------------
+
+class Result:
+    def __init__(self) -> None:
+        self.status = "PASS"  # PASS | FAIL | SKIP
+        self.reason = ""
+        self.seconds = 0.0
+        self.log: Path | None = None
+
+    def mark(self, status: str, reason: str = "") -> None:
+        self.status = status
+        self.reason = reason
+
+
+def log_tail(path: Path | None, max_chars: int = 4000) -> str:
+    if path is None or not path.is_file():
+        return ""
+    text = path.read_text(encoding="utf-8", errors="replace")
+    return text[-max_chars:]
+
+
+# ---------------------------------------------------------------------------
+# Build phase
+# ---------------------------------------------------------------------------
+
+def build_one(ex: dict, lang: str, res: Result) -> None:
+    ex_dir = REPO_ROOT / ex["dir"]
+    log = LOG_DIR / f"{ex['id']}-{lang}.log"
+    res.log = log
+    start = time.monotonic()
+    try:
+        p = subprocess.run(
+            ["./demo.sh", lang, "build"], cwd=ex_dir,
+            stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+            timeout=BUILD_TIMEOUT,
+        )
+        log.write_bytes(p.stdout)
+        if p.returncode != 0:
+            res.mark("FAIL", f"build exit {p.returncode}")
+    except subprocess.TimeoutExpired as e:
+        log.write_bytes(e.stdout or b"")
+        res.mark("FAIL", f"build timed out after {BUILD_TIMEOUT}s")
+    except OSError as e:
+        log.write_text(str(e), encoding="utf-8")
+        res.mark("FAIL", f"build could not start: {e}")
+    finally:
+        res.seconds = time.monotonic() - start
+
+
+# ---------------------------------------------------------------------------
+# Verify phase helpers
+# ---------------------------------------------------------------------------
+
+_vm_cache: dict[str, bool] = {}
+
+
+def vm_reachable(vm: str) -> bool:
+    if vm not in _vm_cache:
+        try:
+            p = subprocess.run(
+                [str(REPO_ROOT / "scripts" / "lab" / "vm-ip.sh"), vm],
+                stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=30,
+            )
+            _vm_cache[vm] = p.returncode == 0 and bool(p.stdout.strip())
+        except (OSError, subprocess.TimeoutExpired):
+            _vm_cache[vm] = False
+    return _vm_cache[vm]
+
+
+_lgtm_up: bool | None = None
+
+
+def lgtm_up() -> bool:
+    global _lgtm_up
+    if _lgtm_up is None:
+        try:
+            urllib.request.urlopen(LGTM_PROBE_URL, timeout=3)
+            _lgtm_up = True
+        except urllib.error.HTTPError:
+            _lgtm_up = True  # any HTTP response (incl. 4xx) means it is listening
+        except (urllib.error.URLError, OSError):
+            _lgtm_up = False
+    return _lgtm_up
+
+
+def revert_target() -> bool:
+    p = subprocess.run(
+        [str(REPO_ROOT / "scripts" / "lab" / "revert-vm.sh"), TARGET_VM, "lab-ready"],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+    )
+    if p.returncode != 0:
+        print(f"warning: revert-vm.sh failed:\n{p.stdout.decode(errors='replace')}", file=sys.stderr)
+    return p.returncode == 0
+
+
+def verify_one(ex: dict, lang: str, res: Result) -> None:
+    ex_dir = REPO_ROOT / ex["dir"]
+    env = os.environ.copy()
+    env.update(LSP_LANG=lang, EXAMPLE_DIR=str(ex_dir), REPO_ROOT=str(REPO_ROOT))
+    if ex["mode"] in ("vm", "vm-peer"):
+        env["TARGET"] = TARGET_VM  # demo.sh run deploys via deploy-to-vm.sh
+    start = time.monotonic()
+    try:
+        p = subprocess.run(
+            [LUA, "verify.lua"], cwd=ex_dir, env=env,
+            stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+            timeout=VERIFY_TIMEOUT,
+        )
+        out = p.stdout.decode(errors="replace")
+        if res.log:
+            with res.log.open("a", encoding="utf-8") as f:
+                f.write(f"\n--- verify ({lang}) exit {p.returncode} ---\n{out}")
+        if p.returncode == 77:
+            m = re.search(r"SKIP:\s*(.+)", out)
+            res.mark("SKIP", m.group(1).strip() if m else "verify skipped")
+        elif p.returncode != 0:
+            res.mark("FAIL", f"verify exit {p.returncode}")
+    except subprocess.TimeoutExpired:
+        res.mark("FAIL", f"verify timed out after {VERIFY_TIMEOUT}s")
+    except OSError as e:
+        res.mark("FAIL", f"verify could not start: {e}")
+    finally:
+        res.seconds += time.monotonic() - start
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--only", action="append", metavar="ID", default=[],
+                    help="run only this example id (repeatable)")
+    ap.add_argument("--lang", action="append", choices=LANGS, default=[],
+                    help="restrict to this language (repeatable)")
+    ap.add_argument("--mode", choices=("local", "vm", "all"), default="local",
+                    help="which examples to run (default: local)")
+    ap.add_argument("--revert-between", action="store_true",
+                    help="revert the target VM to 'lab-ready' between VM examples")
+    ap.add_argument("--junit", metavar="PATH", help="write JUnit XML report")
+    ap.add_argument("--jobs", type=int, default=1, metavar="N",
+                    help="parallel builds (build phase only; verify is sequential)")
+    return ap.parse_args(argv)
+
+
+def select(examples: list[dict], args: argparse.Namespace) -> list[dict]:
+    known = {ex["id"] for ex in examples}
+    for only in args.only:
+        if only not in known:
+            sys.exit(f"error: --only {only}: no such example in manifest")
+    out = []
+    for ex in examples:
+        if args.only and ex["id"] not in args.only:
+            continue
+        if args.mode == "local" and ex["mode"] != "local":
+            continue
+        if args.mode == "vm" and ex["mode"] not in ("vm", "vm-peer"):
+            continue
+        langs = [l for l in ex["langs"] if not args.lang or l in args.lang]
+        if not langs:
+            continue
+        ex = dict(ex, langs=langs)
+        out.append(ex)
+    return out
+
+
+def print_table(selected: list[dict], results: dict) -> None:
+    cols = [l for l in LANGS if any(l in ex["langs"] for ex in selected)]
+    id_w = max([len("example")] + [len(ex["id"]) for ex in selected])
+    print()
+    print("  ".join(["example".ljust(id_w)] + [c.ljust(4) for c in cols]))
+    for ex in selected:
+        cells = [(results[(ex["id"], l)].status if l in ex["langs"] else "-").ljust(4)
+                 for l in cols]
+        print("  ".join([ex["id"].ljust(id_w)] + cells))
+    reasons = [(ex["id"], l, results[(ex["id"], l)])
+               for ex in selected for l in ex["langs"]
+               if results[(ex["id"], l)].reason]
+    if reasons:
+        print()
+        for ex_id, lang, r in reasons:
+            print(f"  {r.status} {ex_id} [{lang}]: {r.reason}")
+
+
+def write_junit(path: str, selected: list[dict], results: dict) -> None:
+    cases = [(ex, l, results[(ex["id"], l)]) for ex in selected for l in ex["langs"]]
+    suite = ET.Element("testsuite", {
+        "name": "examples",
+        "tests": str(len(cases)),
+        "failures": str(sum(1 for _, _, r in cases if r.status == "FAIL")),
+        "skipped": str(sum(1 for _, _, r in cases if r.status == "SKIP")),
+        "time": f"{sum(r.seconds for _, _, r in cases):.1f}",
+    })
+    for ex, lang, r in cases:
+        tc = ET.SubElement(suite, "testcase", {
+            "classname": ex["id"], "name": lang, "time": f"{r.seconds:.1f}",
+        })
+        if r.status == "FAIL":
+            fail = ET.SubElement(tc, "failure", {"message": r.reason})
+            fail.text = log_tail(r.log)
+        elif r.status == "SKIP":
+            ET.SubElement(tc, "skipped", {"message": r.reason})
+    ET.indent(suite)
+    ET.ElementTree(suite).write(path, encoding="utf-8", xml_declaration=True)
+
+
+def main(argv: list[str]) -> int:
+    args = parse_args(argv)
+    try:
+        examples = load_manifest()
+    except ManifestError as e:
+        sys.exit(f"error: {e}")
+    selected = select(examples, args)
+    if not selected:
+        print("nothing selected")
+        return 0
+
+    LOG_DIR.mkdir(exist_ok=True)
+    results = {(ex["id"], l): Result() for ex in selected for l in ex["langs"]}
+
+    # Build phase (parallelizable).
+    jobs = [(ex, l) for ex in selected for l in ex["langs"]]
+    print(f"building {len(jobs)} example-lang combinations (jobs={args.jobs})...")
+    with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, args.jobs)) as pool:
+        futs = {pool.submit(build_one, ex, l, results[(ex["id"], l)]): (ex, l)
+                for ex, l in jobs}
+        for fut in concurrent.futures.as_completed(futs):
+            ex, l = futs[fut]
+            fut.result()
+            r = results[(ex["id"], l)]
+            state = "ok" if r.status == "PASS" else "FAILED"
+            print(f"  build {ex['id']} [{l}]: {state}")
+
+    # Verify phase — strictly sequential; VM examples serial by construction.
+    print("\nverifying...")
+    vm_examples_run = 0
+    for ex in selected:
+        langs = [l for l in ex["langs"] if results[(ex["id"], l)].status == "PASS"]
+        if not langs:
+            continue
+
+        if "lgtm" in ex["requires"] and not lgtm_up():
+            for l in langs:
+                results[(ex["id"], l)].mark("SKIP", "lgtm down")
+            print(f"  {ex['id']}: SKIP (lgtm down)")
+            continue
+
+        if ex["mode"] in ("vm", "vm-peer"):
+            needed = [TARGET_VM] + ([PEER_VM] if ex["mode"] == "vm-peer" else [])
+            if not all(vm_reachable(vm) for vm in needed):
+                for l in langs:
+                    results[(ex["id"], l)].mark("SKIP", "lab down")
+                print(f"  {ex['id']}: SKIP (lab down)")
+                continue
+            if args.revert_between and vm_examples_run > 0 and not revert_target():
+                for l in langs:
+                    results[(ex["id"], l)].mark("SKIP", "revert failed")
+                continue
+            vm_examples_run += 1
+
+        for l in langs:
+            r = results[(ex["id"], l)]
+            verify_one(ex, l, r)
+            print(f"  verify {ex['id']} [{l}]: {r.status}"
+                  + (f" ({r.reason})" if r.reason else ""))
+
+    print_table(selected, results)
+    all_r = [results[(ex["id"], l)] for ex in selected for l in ex["langs"]]
+    passed = sum(1 for r in all_r if r.status == "PASS")
+    failed = sum(1 for r in all_r if r.status == "FAIL")
+    skipped = sum(1 for r in all_r if r.status == "SKIP")
+    print(f"\n{passed} passed, {failed} failed, {skipped} skipped"
+          f" (logs in {LOG_DIR.relative_to(REPO_ROOT)}/)")
+
+    if args.junit:
+        write_junit(args.junit, selected, results)
+        print(f"junit report: {args.junit}")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/scripts/validate.py b/scripts/validate.py
new file mode 100755
index 0000000..95d8289
--- /dev/null
+++ b/scripts/validate.py
@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""Static site validator for linux-systems-programming.
+
+Checks (each finding printed as "file: message"; exit 1 if any):
+  1. _docs/*.md and _parts/*.md front matter parses (simple YAML subset).
+  2. every _docs "part:" matches some _parts "part_name:".
+  3. no unguarded literal {{ / {% in prose (outside fences and {% raw %}).
+  4. codetabs contract: include marker followed by exactly N fenced blocks.
+  5. assets/diagrams: *.svg parse as XML, *.excalidraw parse as JSON;
+     every excalidraw include in _docs has both NAME.svg and NAME.excalidraw.
+  6. bash -n every *.sh under scripts/ and examples/.
+  7. if lua/luac is on PATH, syntax-check every *.lua there too.
+
+Stdlib only. Run from anywhere: paths resolve relative to the repo root.
+"""
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+findings: list[str] = []
+
+
+def flag(path: Path, message: str) -> None:
+    try:
+        rel = path.resolve().relative_to(ROOT)
+    except ValueError:
+        rel = path
+    findings.append(f"{rel}: {message}")
+
+
+# ---------------------------------------------------------------- front matter
+
+KEY_RE = re.compile(r"^([A-Za-z0-9_-]+):(?:\s+(.*))?$")
+
+
+def parse_front_matter(path: Path, lines: list[str]) -> tuple[dict[str, str], int]:
+    """Return ({key: unquoted value}, index of line after closing ---).
+
+    Flags findings for malformed front matter. Body starts at the returned
+    index even on error (0 meaning: treat the whole file as body).
+    """
+    if not lines or lines[0].strip() != "---":
+        flag(path, "front matter: missing opening --- fence")
+        return {}, 0
+    fm: dict[str, str] = {}
+    for i in range(1, len(lines)):
+        line = lines[i].rstrip("\n")
+        if line.strip() == "---":
+            return fm, i + 1
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        m = KEY_RE.match(line)
+        if not m:
+            flag(path, f"front matter line {i + 1}: not a 'key: value' line: {line.strip()!r}")
+            continue
+        key, value = m.group(1), (m.group(2) or "").strip()
+        quoted = len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'"
+        if quoted:
+            value = value[1:-1]
+        elif ": " in value:
+            flag(path, f"front matter line {i + 1}: unquoted value for {key!r} contains ': ' — quote it")
+        fm[key] = value
+    flag(path, "front matter: unterminated (no closing --- fence)")
+    return fm, 0
+
+
+# --------------------------------------------------- body scanning (fences/raw)
+
+FENCE_RE = re.compile(r"^(\s*)(`{3,}|~{3,})")
+RAW_OPEN_RE = re.compile(r"\{%-?\s*raw\s*-?%\}")
+RAW_CLOSE_RE = re.compile(r"\{%-?\s*endraw\s*-?%\}")
+
+
+def annotate_body(lines: list[str], start: int) -> tuple[list[bool], list[bool]]:
+    """Per line: (guarded, fence_open) — guarded means inside a fence or raw
+    region (delimiter lines count as guarded); fence_open marks lines that
+    open a fenced code block outside raw."""
+    n = len(lines)
+    guarded = [False] * n
+    fence_open = [False] * n
+    fence: tuple[str, int] | None = None  # (char, length)
+    in_raw = False
+    for i in range(start, n):
+        line = lines[i]
+        if fence:
+            guarded[i] = True
+            m = FENCE_RE.match(line)
+            if m and m.group(2)[0] == fence[0] and len(m.group(2)) >= fence[1]:
+                fence = None
+            continue
+        if in_raw:
+            guarded[i] = True
+            if RAW_CLOSE_RE.search(line):
+                in_raw = False
+            continue
+        if RAW_OPEN_RE.search(line):
+            guarded[i] = True
+            if not RAW_CLOSE_RE.search(line[RAW_OPEN_RE.search(line).end():]):
+                in_raw = True
+            continue
+        m = FENCE_RE.match(line)
+        if m:
+            guarded[i] = True
+            fence_open[i] = True
+            fence = (m.group(2)[0], len(m.group(2)))
+    return guarded, fence_open
+
+
+# ---------------------------------------------------------- check 3: liquid
+
+TAG_ALLOWED_RE = re.compile(r"\{%-?\s*(include|assign|raw|endraw)\b")
+VAR_ALLOWED_RE = re.compile(r"\{\{-?\s*(site|page|part|include)\.")
+
+
+def check_liquid(path: Path, lines: list[str], start: int, guarded: list[bool]) -> None:
+    for i in range(start, len(lines)):
+        if guarded[i]:
+            continue
+        line = lines[i]
+        for m in re.finditer(r"\{\{|\{%", line):
+            tok = m.group(0)
+            if tok == "{%":
+                if TAG_ALLOWED_RE.match(line, m.start()):
+                    continue
+            else:
+                if VAR_ALLOWED_RE.match(line, m.start()):
+                    continue
+                end = line.find("}}", m.end())
+                if end != -1 and "| relative_url" in line[m.start():end]:
+                    continue
+            flag(path, f"line {i + 1}: unguarded literal {tok!r} — fence it, {{% raw %}}-guard it, or use an allowed form")
+
+
+# -------------------------------------------------------- check 4: codetabs
+
+CODETABS_RE = re.compile(r'\{%-?\s*include\s+codetabs\.html\s+langs="([^"]*)"')
+
+
+def check_codetabs(path: Path, lines: list[str], start: int,
+                   guarded: list[bool], fence_open: list[bool]) -> None:
+    n = len(lines)
+    for i in range(start, n):
+        if guarded[i]:
+            continue
+        m = CODETABS_RE.search(lines[i])
+        if not m:
+            continue
+        labels = [s for s in m.group(1).split("|") if s.strip()]
+        want = len(labels)
+        if want == 0:
+            flag(path, f"line {i + 1}: codetabs include has empty langs=")
+            continue
+        got = 0
+        j = i + 1
+        while j < n:
+            if not lines[j].strip():
+                j += 1
+                continue
+            if fence_open[j]:
+                got += 1
+                j += 1
+                while j < n and guarded[j] and not fence_open[j]:
+                    j += 1
+                if got == want:
+                    # exactly N: an immediately adjacent extra fence would be
+                    # absorbed into the tab group too
+                    k = j
+                    while k < n and not lines[k].strip():
+                        k += 1
+                    if k < n and fence_open[k]:
+                        flag(path, f"line {i + 1}: codetabs langs={want} but an extra adjacent code block follows (line {k + 1})")
+                    break
+                continue
+            flag(path, f"line {i + 1}: codetabs langs={want} but only {got} code block(s) before prose resumes (line {j + 1})")
+            break
+        else:
+            if got < want:
+                flag(path, f"line {i + 1}: codetabs langs={want} but only {got} code block(s) before end of file")
+
+
+# -------------------------------------------------------- checks 1-4 driver
+
+def md_files(dirname: str) -> list[Path]:
+    d = ROOT / dirname
+    return sorted(d.glob("*.md")) if d.is_dir() else []
+
+
+def check_markdown() -> None:
+    part_names: set[str] = set()
+    doc_parts: list[tuple[Path, str]] = []
+
+    for path in md_files("_parts") + md_files("_docs"):
+        lines = path.read_text(encoding="utf-8").splitlines()
+        fm, body_start = parse_front_matter(path, lines)
+        if path.parent.name == "_parts":
+            if "part_name" in fm:
+                part_names.add(fm["part_name"])
+            else:
+                flag(path, "front matter: missing 'part_name:'")
+        else:
+            if "part" in fm:
+                doc_parts.append((path, fm["part"]))
+            else:
+                flag(path, "front matter: missing 'part:'")
+        guarded, fence_open = annotate_body(lines, body_start)
+        check_liquid(path, lines, body_start, guarded)
+        check_codetabs(path, lines, body_start, guarded, fence_open)
+
+    for path, part in doc_parts:
+        if part not in part_names:
+            flag(path, f"part: {part!r} matches no _parts part_name: (known: {', '.join(sorted(part_names)) or 'none'})")
+
+
+# ------------------------------------------------------- check 5: diagrams
+
+EXCALIDRAW_INCLUDE_RE = re.compile(r"\{%-?\s*include\s+excalidraw\.html(.*?)-?%\}", re.DOTALL)
+FILE_PARAM_RE = re.compile(r'file="([^"]+)"')
+
+
+def check_diagrams() -> None:
+    diagrams = ROOT / "assets" / "diagrams"
+    if diagrams.is_dir():
+        for svg in sorted(diagrams.glob("*.svg")):
+            try:
+                ET.parse(svg)
+            except ET.ParseError as e:
+                flag(svg, f"SVG does not parse: {e}")
+        for exc in sorted(diagrams.glob("*.excalidraw")):
+            try:
+                json.loads(exc.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, UnicodeDecodeError) as e:
+                flag(exc, f"excalidraw is not valid JSON: {e}")
+
+    for path in md_files("_docs"):
+        text = path.read_text(encoding="utf-8")
+        for m in EXCALIDRAW_INCLUDE_RE.finditer(text):
+            fp = FILE_PARAM_RE.search(m.group(1))
+            line = text.count("\n", 0, m.start()) + 1
+            if not fp:
+                flag(path, f"line {line}: excalidraw include without file=\"NAME\"")
+                continue
+            name = fp.group(1)
+            for ext in (".svg", ".excalidraw"):
+                if not (diagrams / f"{name}{ext}").is_file():
+                    flag(path, f"line {line}: excalidraw include references missing assets/diagrams/{name}{ext}")
+
+
+# ----------------------------------------------------- checks 6-7: scripts
+
+def script_files(pattern: str) -> list[Path]:
+    out: list[Path] = []
+    for dirname in ("scripts", "examples"):
+        d = ROOT / dirname
+        if d.is_dir():
+            out.extend(sorted(d.rglob(pattern)))
+    return out
+
+
+def first_line(text: str) -> str:
+    return text.strip().splitlines()[0] if text.strip() else "syntax error"
+
+
+def check_shell() -> None:
+    for sh in script_files("*.sh"):
+        r = subprocess.run(["bash", "-n", str(sh)], capture_output=True, text=True)
+        if r.returncode != 0:
+            flag(sh, f"bash -n: {first_line(r.stderr)}")
+
+
+def check_lua() -> None:
+    luac = shutil.which("luac")
+    lua = shutil.which("lua")
+    if not luac and not lua:
+        print("note: lua not on PATH; skipping .lua syntax checks", file=sys.stderr)
+        return
+    stdin_check = "local f, e = loadfile(arg[1]) if not f then io.stderr:write(tostring(e) .. '\\n') os.exit(1) end"
+    for luafile in script_files("*.lua"):
+        if luac:
+            r = subprocess.run([luac, "-p", str(luafile)], capture_output=True, text=True)
+        else:
+            r = subprocess.run([lua, "-", str(luafile)], input=stdin_check,
+                               capture_output=True, text=True)
+        if r.returncode != 0:
+            flag(luafile, f"lua syntax: {first_line(r.stderr)}")
+
+
+# ----------------------------------------------------------------------- main
+
+def main() -> int:
+    check_markdown()
+    check_diagrams()
+    check_shell()
+    check_lua()
+    for f in findings:
+        print(f)
+    if findings:
+        print(f"validate: {len(findings)} finding(s)", file=sys.stderr)
+        return 1
+    print("validate: OK")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())