docs(site): nav parity, bibliography/examples pages, unpublish plans

CLAUDE.md

@@ -29,9 +29,12 @@ Ruby), examples in `examples/NN-slug/{cpp,go,rust}/`, chapters in
 
 - Front matter: `title/order/part/description/duration`; `part:` must equal a
   `_parts` `part_name` exactly; quote values containing colons.
-- Spine: hook → figure → concept → "How the code works" → "Errors, three ways"
-  → "Concurrency lens" → "Build, run, observe" → cross-check → "What you
-  learned" → status footer.
+- Spine: "Learning objectives" → "Why this matters" → hook → figure → concept →
+  "How the code works" → "Errors, three ways" → "Concurrency lens" → "Build, run,
+  observe" → cross-check → "What you learned". ("Learning objectives" is "By the
+  end of this chapter you can:" + action-verb capability bullets; both it and
+  "Why this matters" are the first two H2s after the front matter on body
+  chapters. Intro/prerequisites/lab-setup/outline/appendix chapters are exempt.)
 - **Tools used box (required)**: immediately after the intro/figure, a callout
   listing every tool the chapter invokes and where it runs, e.g.
   `> **Tools used** — `strace` (host), `gdbserver` (systems-target VM),
@@ -81,12 +84,13 @@ Ruby), examples in `examples/NN-slug/{cpp,go,rust}/`, chapters in
 - CI (`validate.yml`) checks site integrity + build smoke only; the
   authoritative gate is a host run of the runner with the lab up, recorded in
   `_plans/`.
-- `_plans` is a **published** collection (`output: true`), and
-  `_plans/iteration-plan.md` is reader-facing — it is linked as "Roadmap" from
-  `_includes/footer.html` and `_layouts/part_index.html`, so never unpublish or
-  rename it without fixing both links. **Internal working plans and capture
-  dumps must set `published: false` in their front matter** so they stay in git
-  for resumability without shipping to the site.
+- `_plans` is an **unpublished** collection (`output: false`): iteration plans,
+  roadmap, and capture dumps stay in git for resumability but never ship to the
+  site (site chrome links only reader content: chapters, examples, bibliography).
+  The former "Roadmap" links in `_includes/footer.html` and
+  `_layouts/part_index.html` were removed; the part-index "Coming soon" callout
+  now points at the outline instead. Verification-status records are banked in
+  `_plans/verification-log.md`.
 
 ## Publishing rule: nothing identifies the machine or its owner
 

_config.yml

@@ -41,7 +41,7 @@ collections:
     output: true
     permalink: /docs/:name/
   plans:
-    output: true
+    output: false
     permalink: /plans/:name/
   example_pages:
     output: true

_example_pages/index.md

@@ -0,0 +1,70 @@
+---
+title: "Examples"
+layout: plan
+permalink: /examples/
+description: "Every runnable example in this repo. Each ships the same behavior in C++23, Go, and Rust."
+---
+
+Each hands-on chapter has a matching runnable example under
+[`examples/`](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples).
+Every example ships the **same observable behavior in C++23, Go, and Rust**, with one
+`verify.lua` asserting that behavior across all three. Run one with
+`./demo.sh [cpp|go|rust] [build|run]` from its directory; see
+[Lab setup]({{ '/docs/02-lab-setup/' | relative_url }}) for the examples that need the KVM lab.
+
+| Example | What it shows |
+|---|---|
+| [01-hello-syscalls](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/01-hello-syscalls) | Hello syscalls |
+| [04-syscalls-and-the-abi](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/04-syscalls-and-the-abi) | Syscalls and the abi |
+| [05-errors-three-ways](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/05-errors-three-ways) | Errors three ways |
+| [06-concurrency-three-ways](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/06-concurrency-three-ways) | Concurrency three ways |
+| [07-fds-raii-and-the-vfs](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/07-fds-raii-and-the-vfs) | Fds raii and the vfs |
+| [08-page-cache-and-durability](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/08-page-cache-and-durability) | Page cache and durability |
+| [09-event-loops-epoll-inotify](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/09-event-loops-epoll-inotify) | Event loops epoll inotify |
+| [10-io-uring](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/10-io-uring) | Io uring |
+| [11-process-lifecycle](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/11-process-lifecycle) | Process lifecycle |
+| [12-signals-and-safe-handling](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/12-signals-and-safe-handling) | Signals and safe handling |
+| [13-pidfd-modern-process-mgmt](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/13-pidfd-modern-process-mgmt) | Pidfd modern process mgmt |
+| [14-identity-and-privilege](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/14-identity-and-privilege) | Identity and privilege |
+| [15-virtual-memory](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/15-virtual-memory) | Virtual memory |
+| [16-mmap-and-shared-mappings](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/16-mmap-and-shared-mappings) | Mmap and shared mappings |
+| [17-allocators-and-gc-runtimes](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/17-allocators-and-gc-runtimes) | Allocators and gc runtimes |
+| [18-pipes-fifos-splice](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/18-pipes-fifos-splice) | Pipes fifos splice |
+| [19-unix-sockets-fd-passing](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/19-unix-sockets-fd-passing) | Unix sockets fd passing |
+| [20-shared-memory-coordination](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/20-shared-memory-coordination) | Shared memory coordination |
+| [21-tcp-sockets](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/21-tcp-sockets) | Tcp sockets |
+| [22-scaling-the-server](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/22-scaling-the-server) | Scaling the server |
+| [23-udp-and-peer-discovery](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/23-udp-and-peer-discovery) | Udp and peer discovery |
+| [24-time-timers-deadlines](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/24-time-timers-deadlines) | Time timers deadlines |
+| [25-shared-state-and-the-futex](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/25-shared-state-and-the-futex) | Shared state and the futex |
+| [26-atomics-and-lock-free](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/26-atomics-and-lock-free) | Atomics and lock free |
+| [27-async-runtimes-and-coroutines](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/27-async-runtimes-and-coroutines) | Async runtimes and coroutines |
+| [28-gdb-and-remote-debugging](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/28-gdb-and-remote-debugging) | Gdb and remote debugging |
+| [29-valgrind-sanitizers-miri](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/29-valgrind-sanitizers-miri) | Valgrind sanitizers miri |
+| [30-ebpf-observation-toolkit](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/30-ebpf-observation-toolkit) | Ebpf observation toolkit |
+| [31-per-language-toolbelts](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/31-per-language-toolbelts) | Per language toolbelts |
+| [32-namespaces-and-cgroups](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/32-namespaces-and-cgroups) | Namespaces and cgroups |
+| [33-seccomp-and-landlock](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/33-seccomp-and-landlock) | Seccomp and landlock |
+| [34-our-programs-in-containers](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/34-our-programs-in-containers) | Our programs in containers |
+| [35-virtualization-and-kvm](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/35-virtualization-and-kvm) | Virtualization and kvm |
+| [36-proc-sys-and-the-agent](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/36-proc-sys-and-the-agent) | Proc sys and the agent |
+| [37-use-method-60s-analysis](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/37-use-method-60s-analysis) | Use method 60s analysis |
+| [38-opentelemetry-to-lgtm](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/38-opentelemetry-to-lgtm) | Opentelemetry to lgtm |
+| [39-benchmarking-without-lies](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/39-benchmarking-without-lies) | Benchmarking without lies |
+| [40-low-latency-fastpath](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/40-low-latency-fastpath) | Low latency fastpath |
+| [41-capstone-fleet](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/41-capstone-fleet) | Final-project fleet |
+| [42-embedded-lua-scripting](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/42-embedded-lua-scripting) | Embedded lua scripting |
+| [43-rust-macros-for-systems](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/43-rust-macros-for-systems) | Rust macros for systems |
+| [44-go-runtime-for-systems](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/44-go-runtime-for-systems) | Go runtime for systems |
+| [45-linux-analysis-suites](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/45-linux-analysis-suites) | Linux analysis suites |
+| [46-cpp-toolbox](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/46-cpp-toolbox) | Cpp toolbox |
+| [47-go-toolbox](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/47-go-toolbox) | Go toolbox |
+| [48-rust-toolbox](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/48-rust-toolbox) | Rust toolbox |
+| [49-concurrency-vs-parallelism](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/49-concurrency-vs-parallelism) | Concurrency vs parallelism |
+| [50-pthreads](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/50-pthreads) | Pthreads |
+| [51-std-threading](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/51-std-threading) | Std threading |
+| [52-boost-thread](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/52-boost-thread) | Boost thread |
+| [53-coroutines](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/53-coroutines) | Coroutines |
+| [54-boost-fiber](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/54-boost-fiber) | Boost fiber |
+| [55-boost-asio](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/55-boost-asio) | Boost asio |
+| [56-capstone-comparison](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/main/examples/56-capstone-comparison) | Final-project comparison |

_includes/footer.html

@@ -8,10 +8,9 @@ <h4>{{ site.title | default: "Tutorial" }}</h4>
       <div class="footer-col">
         <h4>Tutorial</h4>
         <ul>
-          <li><a href="{{ '/docs/00-outline/' | relative_url }}">Outline</a></li>
-          <li><a href="{{ '/docs/01-prerequisites/' | relative_url }}">Prerequisites</a></li>
-          <li><a href="{{ '/docs/02-lab-setup/' | relative_url }}">Lab setup</a></li>
-          <li><a href="{{ '/plans/iteration-plan/' | relative_url }}">Roadmap</a></li>
+          <li><a href="{{ '/docs/00-outline/' | relative_url }}">Chapters</a></li>
+          <li><a href="{{ '/examples/' | relative_url }}">Examples</a></li>
+          <li><a href="{{ '/bibliography/' | relative_url }}">Bibliography</a></li>
         </ul>
       </div>
       <div class="footer-col">

_includes/header.html

@@ -6,8 +6,11 @@
     </a>
     <nav class="site-nav" aria-label="Primary">
       <a href="{{ '/docs/00-outline/' | relative_url }}"
-         {% if page.url contains '/docs/' %}aria-current="page"{% endif %}>Tutorial</a>
-      <a href="{{ '/docs/01-prerequisites/' | relative_url }}">Prerequisites</a>
+         {% if page.url contains '/docs/' %}aria-current="page"{% endif %}>Chapters</a>
+      <a href="{{ '/examples/' | relative_url }}"
+         {% if page.url contains '/examples/' %}aria-current="page"{% endif %}>Examples</a>
+      <a href="{{ '/bibliography/' | relative_url }}"
+         {% if page.url contains '/bibliography/' %}aria-current="page"{% endif %}>Bibliography</a>
       <a href="https://github.com/{{ site.github_username }}/{{ site.github_repo }}"
          rel="noopener">GitHub ↗</a>
     </nav>

_layouts/part_index.html

@@ -4,7 +4,7 @@
 
 {%- comment -%}
   Part landing page. Lists the docs whose `part` matches this page's
-  `part_name`, sorted by `order`, as a card grid — the second level of the
+  `part_name`, sorted by `order`, as a card grid: the second level of the
   two-level navigation (Home → Part → Chapter).
 {%- endcomment -%}
 {%- assign part_docs = site.docs | where: "part", page.part_name | sort: "order" -%}
@@ -37,8 +37,8 @@ <h1>{{ page.title }}</h1>
         <div class="callout">
           <p class="callout__title">Coming soon</p>
           <p>The chapters for this part haven’t shipped yet. See the
-          <a href="{{ '/plans/iteration-plan/' | relative_url }}">roadmap</a>
-          for what’s planned and which iteration delivers it.</p>
+          <a href="{{ '/docs/00-outline/' | relative_url }}">outline</a>
+          for the full chapter plan.</p>
         </div>
       {%- else -%}
         <div class="cards">

bibliography.md

@@ -0,0 +1,33 @@
+---
+title: "Bibliography"
+layout: plan
+permalink: /bibliography/
+description: "The reference works and primary documentation this tutorial's coverage and rigor draw on."
+---
+
+This tutorial teaches Linux systems programming in C++23, Go, and Rust against
+the kernel's own interfaces. The works below are the field's standard references
+and the authoritative documentation it follows. They are reference works, not
+sources: no text or code from any of them is reproduced here. Where you want to
+go deeper than a chapter does, these are where to go.
+
+| Title | Author(s) | Publisher | Year | Focus |
+|---|---|---|---|---|
+| [*The Linux Programming Interface*](https://man7.org/tlpi/) | Michael Kerrisk | No Starch Press | 2010 | The comprehensive reference for the Linux and POSIX system-call API |
+| [*Advanced Programming in the UNIX Environment*, 3rd ed.](https://www.oreilly.com/library/view/advanced-programming-in/9780321638014/) | W. Richard Stevens, Stephen A. Rago | Addison-Wesley | 2013 | Files, processes, signals, and IPC at the UNIX system-call layer |
+| [*Linux Kernel Development*, 3rd ed.](https://www.oreilly.com/library/view/linux-kernel-development/9780768696974/) | Robert Love | Addison-Wesley | 2010 | How the kernel schedules, manages memory, and services system calls |
+| [*Systems Performance*, 2nd ed.](https://www.brendangregg.com/systems-performance-2nd-edition-book.html) | Brendan Gregg | Addison-Wesley | 2020 | Methodologies and tools for observing and tuning Linux performance |
+
+## Primary references
+
+The tutorial follows the current specifications and documentation for the
+interfaces and tools it uses. These are the authoritative sources to check
+against:
+
+- [Linux man-pages project](https://man7.org/linux/man-pages/): the system-call and library-function reference (sections 2 and 3).
+- [Linux kernel documentation](https://docs.kernel.org/): the kernel's own docs, including the io_uring, cgroup, and namespaces references.
+- [liburing](https://github.com/axboe/liburing): the io_uring user-space library and examples.
+- [cppreference](https://en.cppreference.com/) (C++23), [Go documentation](https://go.dev/doc/), and [The Rust Reference](https://doc.rust-lang.org/reference/): the three language standards the examples are written against.
+
+Nothing in these chapters or the runnable examples copies text or code from
+these works.