diff --git a/content/docs/guide/plugin-development.md b/content/docs/guide/plugin-development.md
index 4de811c8b5..4b29340e55 100644
--- a/content/docs/guide/plugin-development.md
+++ b/content/docs/guide/plugin-development.md
@@ -95,6 +95,7 @@ export interface BoardProps {
 
 ### 2. Build the Implementation
 
+<!-- doc-snippet: fragment — step 2 of the tutorial: this is the plugin package's own src/BoardImpl.tsx and it imports ./types, the sibling module step 1 tells the reader to write, so it cannot resolve in isolation -->
 ```tsx
 // src/BoardImpl.tsx
 import React from 'react';
@@ -133,6 +134,7 @@ export default function BoardImpl({ schema, className }: BoardProps) {
 
 ### 3. Create the Entry Point
 
+<!-- doc-snippet: fragment — step 3 of the tutorial: the plugin package's own src/index.tsx, importing ./BoardImpl and ./types — both are files the reader created in steps 1 and 2 -->
 ```tsx
 // src/index.tsx
 import React, { Suspense } from 'react';
@@ -180,6 +182,8 @@ Field widgets follow the `FieldWidgetComponentProps` interface from `@object-ui/
 
 ```typescript
 // FieldWidgetComponentProps<T> shape (from packages/fields/src/widgets/types.ts)
+import type { FieldMetadata } from '@object-ui/types';
+
 type FieldWidgetComponentProps<T = any> = {
   value: T;
   onChange: (val: T) => void;
@@ -209,6 +213,7 @@ grids, reports). That is precisely why a **field widget** needs an adapter when
 it is rendered from a schema node instead of from a form. Wrap it once, at
 registration, and the widget only ever implements one contract:
 
+<!-- doc-snippet: fragment — registration excerpt: ColorPickerField is the widget the reader writes in the next section, shown here first so the registration call reads in one piece -->
 ```tsx
 import { ComponentRegistry } from '@object-ui/core';
 import { withFieldCarrier } from '@object-ui/fields';
@@ -292,6 +297,7 @@ export function ColorPickerField({
 
 Register it as a field widget:
 
+<!-- doc-snippet: fragment — the plugin package's own src/index.tsx again, importing ./ColorPickerField — the file written in the block immediately above -->
 ```tsx
 // src/index.tsx
 import { ComponentRegistry } from '@object-ui/core';
@@ -317,6 +323,7 @@ export { ColorPickerField };
 
 Namespaces prevent type collisions between plugins:
 
+<!-- doc-snippet: fragment — continues the board example: BoardRenderer is the component defined in step 3's src/index.tsx, not re-declared here -->
 ```tsx
 import { ComponentRegistry } from '@object-ui/core';
 
@@ -337,6 +344,8 @@ Use `skipFallback: true` in the metadata if you do **not** want the component to
 ### Querying Registered Components
 
 ```tsx
+import { ComponentRegistry } from '@object-ui/core';
+
 ComponentRegistry.has('board');                              // boolean
 ComponentRegistry.getAllTypes();                              // string[]
 ComponentRegistry.getNamespaceComponents('plugin-board');     // ComponentConfig[]
@@ -346,6 +355,7 @@ ComponentRegistry.getNamespaceComponents('plugin-board');     // ComponentConfig
 
 Define your schema interface in `types.ts` and extend `BaseSchema`:
 
+<!-- doc-snippet: fragment — abridged restatement of step 1's src/types.ts — BoardColumn and BoardItem are the interfaces declared alongside it there, elided to keep the extends BaseSchema line in focus -->
 ```typescript
 import type { BaseSchema } from '@object-ui/types';
 
@@ -358,6 +368,7 @@ export interface BoardSchema extends BaseSchema {
 
 Declare `ComponentInput` entries when registering so the visual designer can offer a property panel:
 
+<!-- doc-snippet: fragment — continues the board example: ComponentRegistry and BoardRenderer both come from step 3's src/index.tsx; this block shows only the inputs metadata -->
 ```tsx
 ComponentRegistry.register('board', BoardRenderer, {
   inputs: [
@@ -378,10 +389,14 @@ ComponentRegistry.register('board', BoardRenderer, {
 
 ObjectUI uses **Vitest + React Testing Library**. Place tests next to the implementation.
 
+<!-- doc-snippet: fragment — the plugin package's own src/BoardImpl.test.tsx, importing ./BoardImpl — the implementation the reader wrote in step 2 -->
 ```tsx
 // src/BoardImpl.test.tsx
 import { describe, it, expect } from 'vitest';
 import { render, screen } from '@testing-library/react';
+// `toBeInTheDocument` is a jest-dom matcher, not a Vitest one — without this
+// import the assertions below do not type-check and do not run.
+import '@testing-library/jest-dom';
 import BoardImpl from './BoardImpl';
 
 const schema = {
@@ -458,6 +473,7 @@ npm publish --access public
 pnpm add @object-ui/plugin-board
 ```
 
+<!-- doc-snippet: fragment — consumer-side excerpt: @object-ui/plugin-board is the package the reader has just been taught to build and publish, so it does not resolve from this repo -->
 ```tsx
 // app/main.tsx — import once, auto-registers
 import '@object-ui/plugin-board';
diff --git a/content/docs/guide/schema-rendering.md b/content/docs/guide/schema-rendering.md
index 33f4bacb07..c273d987ae 100644
--- a/content/docs/guide/schema-rendering.md
+++ b/content/docs/guide/schema-rendering.md
@@ -31,7 +31,7 @@ function App() {
   const schema = {
     type: "page",
     title: "My Dashboard",
-    body: { /* ... */ }
+    body: { type: "text", value: "Hello" }
   }
   
   return <SchemaRenderer schema={schema} />
@@ -43,6 +43,8 @@ function App() {
 Every schema object must have at minimum a `type` field:
 
 ```typescript
+import type { CSSProperties } from 'react'
+
 interface BaseSchema {
   type: string           // Component type identifier
   id?: string           // Optional unique identifier
@@ -74,6 +76,7 @@ interface BaseSchema {
 
 The `SchemaRenderer` accepts a `data` prop that provides context for expressions:
 
+<!-- doc-snippet: fragment — continues the block above — SchemaRenderer and schema are already in scope there; the closing JSX line is the call shown in place, not a statement that parses on its own -->
 ```tsx
 const data = {
   user: { name: "John", role: "admin" },
@@ -98,6 +101,7 @@ Use expression syntax `${}` to reference data:
 
 The schema renderer uses a component registry to map schema types to React components:
 
+<!-- doc-snippet: fragment — MyComponent is the reader's own React component, named here to show what register() takes as its second argument -->
 ```tsx
 import { ComponentRegistry } from '@object-ui/core'
 
@@ -212,6 +216,7 @@ Object UI includes a powerful expression system for dynamic behavior:
 
 Components can emit events that you handle in React:
 
+<!-- doc-snippet: fragment — prop excerpt: the JSX call is shown alone to isolate onAction and onSubmit; schema and SchemaRenderer come from the first example on this page -->
 ```tsx
 <SchemaRenderer 
   schema={schema}
@@ -263,6 +268,7 @@ The renderer automatically memoizes components to prevent unnecessary re-renders
 
 Use dynamic imports for heavy components:
 
+<!-- doc-snippet: fragment — code-splitting excerpt: ./HeavyChart is the reader's own component file, and registry is whichever registry instance the host already holds -->
 ```tsx
 import { lazy } from 'react'
 
@@ -275,6 +281,7 @@ registry.register('heavy-chart', HeavyChart)
 
 The renderer includes built-in error boundaries:
 
+<!-- doc-snippet: fragment — prop excerpt: the JSX call is shown alone to isolate onError; schema and SchemaRenderer come from the first example on this page -->
 ```tsx
 <SchemaRenderer 
   schema={schema}
@@ -330,6 +337,7 @@ const pageSchema = {
 
 Pass all necessary data upfront:
 
+<!-- doc-snippet: fragment — best-practice excerpt: userData, userSettings and dashboardStats are the reader's own values, and the closing JSX line is shown in place rather than as a parseable statement -->
 ```tsx
 // ✅ Good
 const data = {
@@ -345,6 +353,7 @@ const data = {
 
 Move logic to expressions instead of creating conditional schemas:
 
+<!-- doc-snippet: fragment — a bad/good contrast pair in one fence: schema is deliberately declared twice so the two spellings sit side by side, and user, adminSchema and userSchema are the reader's own values -->
 ```tsx
 // ❌ Bad
 const schema = user.isAdmin ? adminSchema : userSchema
diff --git a/content/docs/guide/theming.md b/content/docs/guide/theming.md
index 2466055583..a3e026bca0 100644
--- a/content/docs/guide/theming.md
+++ b/content/docs/guide/theming.md
@@ -55,6 +55,7 @@ ObjectUI follows the Shadcn convention. Design tokens are defined as HSL channel
 
 Components reference these tokens through Tailwind:
 
+<!-- doc-snippet: fragment — two sibling elements shown without a parent: the fence deliberately holds two JSX roots because the point is the Tailwind class names, not a renderable tree -->
 ```tsx
 <div className="bg-background text-foreground border-border" />
 <button className="bg-primary text-primary-foreground" />
@@ -87,6 +88,7 @@ To recolour ObjectUI, override the token values rather than the utilities — ei
 
 ObjectUI uses [class-variance-authority](https://cva.style) to define type-safe component variants. Each component exports a `*Variants` function alongside the component itself:
 
+<!-- doc-snippet: fragment — quotes the published Badge source: it imports class-variance-authority, which the reader installs in their own app but which is not a dependency of this repository's root, so the specifier does not resolve here -->
 ```tsx
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "@object-ui/components";
@@ -119,6 +121,7 @@ function Badge({ className, variant, ...props }: BadgeProps) {
 
 To add a custom variant to an existing component, wrap it:
 
+<!-- doc-snippet: fragment — continues the block above — cva, Badge and cn are already imported there; this block shows only the wrapper -->
 ```tsx
 const statusVariants = cva("", {
   variants: {
@@ -139,6 +142,7 @@ function StatusBadge({ status, className, ...props }: { status: "active" | "pend
 
 The `cn()` utility from `@object-ui/components` combines `clsx` and `tailwind-merge` so that later classes win over earlier ones without producing duplicate utilities:
 
+<!-- doc-snippet: fragment — usage excerpt for cn(): isActive and className are the reader's own values, shown bare so the merge behaviour is the only thing on screen -->
 ```tsx
 import { cn } from "@object-ui/components";
 
@@ -152,6 +156,7 @@ cn("base-class", isActive && "bg-primary", className);
 
 Every ObjectUI component accepts a `className` prop that is merged via `cn()`, so consumers can always override styles:
 
+<!-- doc-snippet: fragment — prop excerpt: a single Button usage, shown to demonstrate that className is merged; Button comes from the reader's own import of @object-ui/components -->
 ```tsx
 <Button className="rounded-full px-8" variant="outline">
   Custom Shape
@@ -162,6 +167,7 @@ Every ObjectUI component accepts a `className` prop that is merged via `cn()`, s
 
 ObjectUI supports three modes: `light`, `dark`, and `auto` (follows system preference). The `ThemeProvider` applies a `light` or `dark` class to the root element and listens for `prefers-color-scheme` changes.
 
+<!-- doc-snippet: fragment — MyApp is the reader's own root component — the block shows where ThemeProvider goes, not what it wraps -->
 ```tsx
 import { ThemeProvider } from "@object-ui/react";
 
@@ -196,23 +202,33 @@ There is no `darkMode` option to set on your side. ObjectUI declares the class-b
 
 Register one or more theme definitions with `ThemeProvider`. Each theme is a plain JSON object:
 
+<!-- doc-snippet: fragment — App is the reader's own root component; the trailing ThemeProvider usage is shown in place so the theme object and its consumer read as one unit -->
 ```tsx
 import type { Theme } from "@object-ui/types";
 
 const corporateTheme: Theme = {
   name: "corporate",
+  label: "Corporate",
+  // `colors` keys are ColorPalette keys, NOT Shadcn variable names. The engine
+  // maps them: text → --foreground, surface → --card, error → --destructive,
+  // textSecondary → --muted-foreground. A key that is not on ColorPalette is
+  // dropped, so the *-foreground pairs go through `customVars` below.
   colors: {
     primary: "220 70% 50%",
-    "primary-foreground": "0 0% 100%",
     background: "0 0% 100%",
-    foreground: "220 20% 10%",
+    text: "220 20% 10%",
     accent: "200 80% 55%",
+  },
+  // Emitted verbatim as `--<key>: <value>` — the declared door for any custom
+  // property that has no ColorPalette key.
+  customVars: {
+    "primary-foreground": "0 0% 100%",
     "accent-foreground": "0 0% 100%",
   },
-  fonts: {
-    sans: "IBM Plex Sans, system-ui",
+  typography: {
+    fontFamily: { base: "IBM Plex Sans, system-ui" },
   },
-  radius: "0.375rem",
+  borderRadius: { base: "0.375rem" },
 };
 
 <ThemeProvider themes={[corporateTheme]} defaultTheme="corporate">
@@ -222,13 +238,16 @@ const corporateTheme: Theme = {
 
 Themes support **inheritance** via the `extends` field. A child theme only needs to declare its overrides:
 
+<!-- doc-snippet: fragment — continues the block above — corporateTheme is declared there; App is the reader's own root component -->
 ```tsx
 const darkCorporate: Theme = {
   name: "corporate-dark",
+  label: "Corporate Dark",
   extends: "corporate",
   colors: {
+    primary: "220 70% 50%",
     background: "220 20% 8%",
-    foreground: "0 0% 95%",
+    text: "0 0% 95%",
   },
 };
 
@@ -242,26 +261,36 @@ const darkCorporate: Theme = {
 Start from HSL values and define both light and dark variants:
 
 ```tsx
-const brand: Theme = {
+import type { Theme } from "@object-ui/types";
+
+export const brand: Theme = {
   name: "brand",
+  label: "Brand",
   colors: {
-    // Light palette
-    primary: "262 83% 58%",        // Purple
+    // Every key here is a ColorPalette key; the comment is the CSS variable
+    // the engine emits it as.
+    primary: "262 83% 58%",         // --primary          (Purple)
+    secondary: "262 30% 94%",       // --secondary
+    accent: "160 84% 39%",          // --accent           (Teal accent)
+    background: "0 0% 100%",        // --background
+    surface: "0 0% 100%",           // --card
+    text: "262 20% 10%",            // --foreground
+    textSecondary: "262 10% 45%",   // --muted-foreground
+    disabled: "262 20% 95%",        // --muted
+    border: "262 20% 90%",          // --border
+    error: "0 84% 60%",             // --destructive
+  },
+  // Shadcn pairs the palette with foreground/ring variables that have no
+  // ColorPalette key of their own. Author those here — they are emitted
+  // verbatim as `--<key>: <value>`.
+  customVars: {
     "primary-foreground": "0 0% 100%",
-    secondary: "262 30% 94%",
     "secondary-foreground": "262 83% 30%",
-    accent: "160 84% 39%",          // Teal accent
     "accent-foreground": "0 0% 100%",
-    background: "0 0% 100%",
-    foreground: "262 20% 10%",
-    muted: "262 20% 95%",
-    "muted-foreground": "262 10% 45%",
-    border: "262 20% 90%",
-    ring: "262 83% 58%",
-    destructive: "0 84% 60%",
     "destructive-foreground": "0 0% 100%",
+    ring: "262 83% 58%",
   },
-  radius: "0.5rem",
+  borderRadius: { base: "0.5rem" },  // --radius
 };
 ```
 
@@ -289,6 +318,7 @@ function ThemeSwitcher() {
 
 Enable **persistence** so the user's choice survives page reloads:
 
+<!-- doc-snippet: fragment — persistence excerpt: lightTheme, darkTheme and brandTheme are the reader's own theme objects and App is their root component -->
 ```tsx
 <ThemeProvider
   themes={[lightTheme, darkTheme, brandTheme]}
@@ -308,6 +338,7 @@ ObjectUI components use **logical CSS properties** (`ms-`, `me-`, `ps-`, `pe-`)
 
 1. Set the `dir` attribute on your root element:
 
+<!-- doc-snippet: fragment — an opening tag on its own, shown to isolate the dir and lang attributes — it is deliberately unclosed because the reader's document supplies the rest -->
 ```tsx
 <html dir="rtl" lang="ar">
 ```
diff --git a/scripts/check-doc-snippet-types.mjs b/scripts/check-doc-snippet-types.mjs
index 057cd7db93..d87ec80496 100644
--- a/scripts/check-doc-snippet-types.mjs
+++ b/scripts/check-doc-snippet-types.mjs
@@ -227,7 +227,7 @@ const TS_FENCE_LANGUAGES = new Set(['ts', 'tsx', 'typescript']);
  * Documents whose snippets are NOT compiled, each with the reason. The default
  * is covered; this list is the debt, by name, and it can only shrink.
  *
- * ⚠️ 5 of these entries are `.md` pages under `content/docs` that objectui#5174
+ * ⚠️ 2 of these entries are `.md` pages under `content/docs` that objectui#5174
  * made visible: the collector now reads `.md`, and an entry with a measured reason
  * is what a page that cannot pass yet is owed. They are DISCLOSED debt, not new
  * debt — every one of them was equally unverified before, just unnamed. Their
@@ -242,7 +242,10 @@ const TS_FENCE_LANGUAGES = new Set(['ts', 'tsx', 'typescript']);
  * `notifications`, `public-forms`, `schema-overview`, `troubleshooting` and
  * `user-state-persistence`. Batch 2 took four more — `guide/plugins`,
  * `guide/building-crud-app`, `rfcs/0001-clipboard-paste` and `guide/architecture`
- * — clearing 89 diagnostics. Each page reached zero the honest two ways — a block
+ * — clearing 89 diagnostics. Batch 3 took three — `guide/plugin-development`,
+ * `guide/schema-rendering` and `guide/theming` — clearing 81, and left
+ * `guide/layout` and `guide/component-registry` as the final pair.
+ * Each page reached zero the honest two ways — a block
  * that should compile was made self-contained against the built `dist/`, and a
  * block that genuinely cannot compile got a `FRAGMENT_MARKER` declaration with a
  * written reason. Nothing about this gate's strictness moved to get them there.
@@ -259,6 +262,34 @@ const TS_FENCE_LANGUAGES = new Set(['ts', 'tsx', 'typescript']);
  * titled "Type Safety", marked `// ✅ Type-checked`, set `ButtonSchema.onClick` to
  * the STRING `'handleClick'` where the declared type is `() => void | Promise<void>`.
  * The pages that are mostly fragments are mostly fragments for a stated reason:
+ * Batch 3 in the same terms: 38 blocks brought under the gate — 26 declared
+ * fragments and 12 that compile, of which 7 already compiled untouched and 5 were
+ * edited to. Its defect was the largest single one this card has surfaced, and it
+ * was hidden the way objectui#5138 describes: `guide/theming`'s three `Theme`
+ * objects were annotated `Theme` but the annotation itself errored (`Theme` was
+ * never imported in two of them), so TypeScript never excess-checked the literals
+ * underneath. With the annotation resolving, the `brand` palette alone had TEN of
+ * its fourteen `colors` keys off `ColorPalette` — `"primary-foreground"`,
+ * `foreground`, `muted`, `ring`, `destructive` and the other `*-foreground` pairs
+ * are Shadcn CSS VARIABLE names, not palette keys — plus `radius` and `fonts`,
+ * neither of which is a `Theme` key, and no `label`, which is required. Every one
+ * of those is dropped in silence at runtime: `generateColorVars` iterates
+ * `COLOR_TO_CSS_MAP`, so it can only ever emit the keys `ColorPalette` declares.
+ * The pages were teaching theme JSON most of which the engine ignores. The fix
+ * routes them through the two doors that do work — the real palette keys, each
+ * annotated with the variable it emits, and `customVars` for the rest, which the
+ * engine emits verbatim as `--<key>: <value>`.
+ *
+ * `guide/plugin-development` also had the documented Vitest example asserting
+ * `toBeInTheDocument()` with no `@testing-library/jest-dom` import, the matcher's
+ * own package — a reader copying that test got neither the types nor the matcher.
+ *
+ * The pages that are mostly fragments are mostly fragments for a stated reason:
+ * `guide/plugin-development` walks the reader through building a plugin package,
+ * so its blocks import `./types` and `./BoardImpl` — files the reader has just
+ * been told to write — and `guide/theming` quotes the published `Badge` source,
+ * which imports `class-variance-authority`, a peer that resolves in the reader's
+ * app but is not a root dependency here.
  * `guide/plugins` and the clipboard-paste RFC document packages the reader is being
  * taught to create, and an RFC's signature excerpts have no bodies by design.
  *
@@ -314,25 +345,6 @@ const UNGATED_DOCS = {
     'this page still needs the 8 parse-failing blocks re-fenced or declared, the undefined-name ' +
     'blocks made self-contained, and the `@objectstack/*` runtime imports resolvable — none of ' +
     'which this repo can do from here.',
-  'content/docs/guide/plugin-development.md':
-    '10 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the ' +
-    'page never defines; 6 unresolved-module diagnostic(s); plus TS2339x5 TS2882x1 TS7006x3 — ' +
-    'candidate real defects, un-triaged',
-  'content/docs/guide/schema-rendering.md':
-    '8 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies; ' +
-    '10 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the ' +
-    'page never defines; 1 unresolved-module diagnostic(s); plus TS2322x1 TS2451x2 TS7006x5 — ' +
-    'candidate real defects, un-triaged. This entry read TS2305x4 until objectui#5343: ' +
-    '`registerDefaultRenderers` (@object-ui/components) → `initializeComponents()` plus the ' +
-    'side-effect `@object-ui/fields` import, `getComponentRegistry` (@object-ui/react) → the ' +
-    '`ComponentRegistry` singleton @object-ui/core exports, and `PageSchema` / `FormSchema` were ' +
-    'claimed from @object-ui/core while they live in @object-ui/types (`PageNodeSchema` there, ' +
-    'whose `body` is `SchemaNode[]` — the typed example is written as an array now)',
-  'content/docs/guide/theming.md':
-    '3 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies; ' +
-    '23 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the ' +
-    'page never defines; 1 unresolved-module diagnostic(s); plus TS2339x1 TS2353x1 — candidate ' +
-    'real defects, un-triaged',
   'content/docs/plugins/plugin-calendar-view.mdx':
     '2 unresolved-module diagnostic(s) — and NOT a defect: the page is a migration guide whose ' +
     '"Before" blocks quote the retired `@object-ui/plugin-calendar-view` import on purpose. Covering ' +