diff --git a/src/attach/frame.rs b/src/attach/frame.rs
index c196729..76160fa 100644
--- a/src/attach/frame.rs
+++ b/src/attach/frame.rs
@@ -4,6 +4,7 @@
 //! (not the `Event` NDJSON control plane) because full-screen repaints are
 //! high-volume and base64-in-JSON would hurt — the same data/control split
 //! orca uses. See `docs/attach-transport.md` for the frame table.
+// Context: doc://pillbox/attach-frame-protocol@0001#attach-frame-protocol
 
 use std::io::{self, Read, Write};
 
diff --git a/src/commands/dispatch.rs b/src/commands/dispatch.rs
index 99586f0..a4bbc61 100644
--- a/src/commands/dispatch.rs
+++ b/src/commands/dispatch.rs
@@ -26,6 +26,7 @@
 //! precisely for this. The loop sits behind [`WorkerDriver`] so the selection /
 //! retry **policy** is unit-tested over a mock, while the live [`CliDriver`] is
 //! exercised by the GHOST-004 smoke.
+// Context: doc://pillbox/adr-008-ghost-extraction-trigger@0001#ghost-extraction-trigger
 
 use std::path::PathBuf;
 use std::process::Command;
diff --git a/src/commands/session/mod.rs b/src/commands/session/mod.rs
index 4486d99..2354f1a 100644
--- a/src/commands/session/mod.rs
+++ b/src/commands/session/mod.rs
@@ -5,6 +5,8 @@
 //!
 //! Lives in `commands/` (not the registry-storage `session.rs`) so
 //! the CLI surface stays decoupled from the on-disk record format.
+// Context: doc://pillbox/dx-zero-config-local@0001#dx-zero-config-local
+// Context: doc://pillbox/optimization-external-substrate-primitives@0001#optimization-external-substrate-primitives
 
 use anyhow::Result;
 
diff --git a/src/contract.rs b/src/contract.rs
index 2619d0d..ef4c6f8 100644
--- a/src/contract.rs
+++ b/src/contract.rs
@@ -13,6 +13,7 @@
 //! `pillbox sandbox` runtime (`commands::sandbox`) is the per-emitter producer
 //! today; the per-session [`crate::events::log::SessionLog`] is the durable
 //! spine new producers target (see docs/session-event-log.md).
+// Context: doc://pillbox/agent-io-pty-free-contract@0001#agent-io-pty-free-contract
 
 // Contract surface lands ahead of its first producer (contract-first).
 #![allow(dead_code)]
diff --git a/src/gateway.rs b/src/gateway.rs
index 942fb02..f991f00 100644
--- a/src/gateway.rs
+++ b/src/gateway.rs
@@ -15,6 +15,7 @@
 //! Lifetime: serves until Ctrl-C. An ephemeral exit-when-the-session-ends
 //! (watching the log for a terminal event) is a follow-up, as is auth — today
 //! it binds localhost only.
+// Context: doc://pillbox/gateway-no-daemon@0001#gateway-no-daemon
 
 use std::net::{TcpListener, TcpStream};
 use std::sync::atomic::AtomicBool;
diff --git a/src/registry.rs b/src/registry.rs
index 5ba75f6..d4cf078 100644
--- a/src/registry.rs
+++ b/src/registry.rs
@@ -31,6 +31,7 @@
 //! - **Sessions' no-inheritance** is encoded by not implementing
 //!   [`InheritedRegistry`], so the project→global `read_inherited`
 //!   walk never applies to them.
+// Context: doc://pillbox/adr-007-runner-image-tags-name-roles@0001#runner-image-tags-name-roles
 
 use std::{
     fs,
diff --git a/src/sandbox/docker.rs b/src/sandbox/docker.rs
index 6a5f29b..332fe23 100644
--- a/src/sandbox/docker.rs
+++ b/src/sandbox/docker.rs
@@ -4,6 +4,7 @@
 //! state come from the right scope. Auth currently always resolves to
 //! global; vault state lives per-pillbox so a project's leases never
 //! collide with another's.
+// Context: doc://pillbox/adr-002-docker-backend-deleted@0001#docker-backend-deleted
 
 use std::time::SystemTime;
 
diff --git a/src/sandbox/libkrun/mod.rs b/src/sandbox/libkrun/mod.rs
index c3ab6b2..4b77415 100644
--- a/src/sandbox/libkrun/mod.rs
+++ b/src/sandbox/libkrun/mod.rs
@@ -30,6 +30,7 @@
 //! ```
 //! Re-codesign after every build (cargo invalidates the signature). Select at
 //! runtime with `PILLBOX_BACKEND=libkrun`.
+// Context: doc://pillbox/adr-001-libkrun-is-the-backend@0001#libkrun-is-the-backend
 
 use std::ffi::CString;
 use std::os::raw::{c_char, c_int};
diff --git a/src/sandbox/libkrun/session.rs b/src/sandbox/libkrun/session.rs
index aed0bd5..98e5573 100644
--- a/src/sandbox/libkrun/session.rs
+++ b/src/sandbox/libkrun/session.rs
@@ -6,6 +6,7 @@
 //! `--detach`, and the opencode server path), reattach/kill, and the §0/opencode
 //! accessors `commands::session` calls. The VMM child entry, the spec types, and
 //! the CoW/stub/rootfs helpers stay in [`super`] (shared with `vmm_child_main`).
+// Context: doc://pillbox/libkrun-env-fork-substrate@0001#libkrun-env-fork-substrate
 
 use std::os::unix::net::{UnixListener, UnixStream};
 use std::path::{Path, PathBuf};
diff --git a/src/sandbox/managed.rs b/src/sandbox/managed.rs
index fe8ccab..a4619d2 100644
--- a/src/sandbox/managed.rs
+++ b/src/sandbox/managed.rs
@@ -59,6 +59,8 @@
 //!   - **Token provisioning / trust.** Where a real user's token/secret comes
 //!     from (vs the spike's `/tmp` file) is unresolved; the env config above is
 //!     the interim surface.
+// Context: doc://pillbox/managed-store-of-record@0001#managed-store-of-record
+// Context: doc://pillbox/managed-tier-do-gateway@0001#managed-tier-do-gateway
 
 use std::path::PathBuf;
 
diff --git a/src/sandbox/mod.rs b/src/sandbox/mod.rs
index 4c30b66..a2ad2af 100644
--- a/src/sandbox/mod.rs
+++ b/src/sandbox/mod.rs
@@ -10,6 +10,7 @@
 //!   `libkrun`; the default on that build).
 //! - [`docker::DockerBackend`] — host Docker daemon (the no-KVM compat
 //!   backend; opt in via `PILLBOX_BACKEND=docker`).
+// Context: doc://pillbox/adr-003-qemu-parked@0001#qemu-parked
 
 pub(crate) mod appserver;
 pub(crate) mod appserver_client;
diff --git a/src/sandboxes.rs b/src/sandboxes.rs
index 785ac20..ff3db0f 100644
--- a/src/sandboxes.rs
+++ b/src/sandboxes.rs
@@ -11,6 +11,7 @@
 //! `<pillbox>/sandboxes/<id>.toml`, single-scope (no inheritance — a sandbox
 //! is concrete runtime state tied to the pillbox that spawned it), via the
 //! shared [`crate::registry::Registry`] plumbing.
+// Context: doc://pillbox/remote-backend-plane-removed@0001#remote-backend-plane-removed
 
 use anyhow::Result;
 use serde::{Deserialize, Serialize};
diff --git a/src/vault/egress.rs b/src/vault/egress.rs
index 6cfeb85..231c374 100644
--- a/src/vault/egress.rs
+++ b/src/vault/egress.rs
@@ -18,6 +18,7 @@
 //! leaving for the wrong host is never swapped (it ships as a worthless stub) —
 //! and under default-deny that wrong-host request is blocked outright. The
 //! credential is released only on the host it's bound to.
+// Context: doc://pillbox/vault-egress-default-deny@0001#vault-egress-default-deny
 
 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};