diff --git a/CLAUDE.md b/CLAUDE.md
index 62335441..28418089 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -112,7 +112,13 @@ Dispatch `.github/workflows/publish.yaml` (workflow_dispatch) with no version in
 - Docs are **bullet-heavy and code-heavy, not prose-heavy.** Default to scannable bullet lists in the `- **Foo**: Bar` form (bolded term, then the one-line explanation) instead of paragraphs. Lead with a code snippet wherever a concept has an API, and link to a runnable example under `examples/docs/*` whenever one exists. Avoid long paragraphs; if you find yourself writing more than two or three sentences in a row, convert it to bullets or a code block. Prose is the exception, used only to connect ideas that genuinely cannot be a list.
 - The docs theme matches the Rivet docs (rivet.dev) 1:1: light-only "porcelain" palette, Manrope + JetBrains Mono, dark code blocks.
 - Docs prose must not use em dashes (`—`). Rephrase with commas, colons, parentheses, or separate sentences. This applies to all content under `website/src/content/docs`.
-- Every substantial documentation code block must be backed by a runnable example package under `examples/docs/*` that is verified end-to-end (it actually runs against the sidecar), with the doc code copied verbatim from that example and a `*[See Full Example](…)*` link to it. Tiny illustrative snippets (a line or two showing a signature or option shape) are exempt; anything a reader could copy and run should come from a real, passing example. Keep the doc block and the example in sync.
+- **Docs code blocks MUST embed real example files via `<CodeSnippet>` — never hand-write checked code inline.** All runnable code shown in docs lives as a file under `examples/docs/*` (a real example package, verified end-to-end against the sidecar) and is embedded at build time, so the rendered code is always the exact code we ship, and each block auto-links to its source on GitHub. This **replaces** the old "copy the code verbatim into the page + add a manual `*[See Full Example](…)*` link" convention — `<CodeSnippet>` embeds the source and generates the GitHub link automatically. Authoring:
+  - Embed a whole file: `<CodeSnippet file="examples/docs/feat-typescript/src/index.mts" />` (repo-relative path). `remarkCodeSnippet` (in `@rivet-dev/docs-theme`) inlines the content; the language is inferred from the extension (override with `lang=`), the tab label is the basename (override with `title=`).
+  - Embed only part of a file with `region="name"`, delimiting it in the source with `// docs:start name` … `// docs:end name` (markers are stripped, the region is dedented).
+  - `<CodeSnippet>` is the ONLY embed API. A bare ```` ```ts file="server.ts" ```` fence (no slash) is just a CodeGroup tab label, not an embed.
+  - Paths resolve from the repo root (override via `DOCS_EMBED_ROOT`). If the referenced code doesn't exist yet, add it as a proper runnable example under `examples/docs/*` rather than inlining unchecked code.
+  - Non-runnable snippets (shell commands, config fragments, illustrative pseudo-code) may stay inline — the rule is about code a reader could copy and run.
+  - This convention is owned by the shared `@rivet-dev/docs-theme` and applies to every site built on it (secure-exec AND agent-os).
 - Docs styling is owned by the shared **`@rivet-dev/docs-theme`** repo (`github.com/rivet-dev/docs-theme`), consumed via `github:rivet-dev/docs-theme#<tag>` and wired in via `...docsTheme(starlight, siteConfig)` in `astro.config.mjs`. **To change any docs styling** (header, sidebar, code blocks, fonts, palette), edit that repo and follow its CLAUDE.md release workflow — never restyle docs in `website/src`. When iterating on theme styling locally, add a `pnpm.overrides` `link:` to the local docs-theme checkout (kept through local commits while iterating), but **remove it before pushing** — a pushed consumer must pin `github:rivet-dev/docs-theme#<tag>`, never a path. To change *this site's* identity/nav/sidebar/landing, edit `website/docs.config.mjs` (sidebar icons via each item's `attrs['data-icon']`). Re-test with `pnpm --dir website build`.
 
 - The proper product title is **"Secure Exec"** (two words, capitalized); use it in docs PROSE. Use the lowercase "secure-exec" only for code identifiers, package names (`@secure-exec/*`), the repo, and URLs.