@vielzeug/codex 26.11.2 → 26.11.4

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug: Full Documentation
 
-> Complete documentation for 43 packages. Version: 26.11.1
+> Complete documentation for 43 packages. Version: 26.11.3
 
 ---
 
@@ -4262,15 +4262,15 @@ npx -y @vielzeug/codex
 | `loadSnapshot` | Read validated snapshot metadata | Sync | Content chunks load lazily |
 | `SnapshotCatalog` | Query package corpus | Sync | Construct from loaded snapshot |
 | `createMcpServer` | MCP adapter factory (generic tools) | Sync | Requires catalog and version |
+| `createMcpServerWithRefine` | MCP adapter factory (all package and Refine tools) | Sync | Import from `@vielzeug/codex/refine` |
 | `startHttpHost` | Loopback Streamable HTTP host | Async | HTTP remains local-only |
-| `registerRefineTools` | Opt-in Refine tool registration | Sync | Import from `@vielzeug/codex/refine` |
 
 ## Package Entry Points
 
 | Import | Purpose |
 | --- | --- |
 | `@vielzeug/codex` | `Catalog`, `SnapshotCatalog`, `loadSnapshot`, MCP server, and HTTP host |
-| `@vielzeug/codex/refine` | Opt-in Refine component tools (`registerRefineTools`) |
+| `@vielzeug/codex/refine` | Refine catalog and MCP server with component tools |
 
 ## Snapshot
 
@@ -4304,21 +4304,23 @@ Registers generic package tools over `Catalog`. Refine tools are opt-in through
 
 ## Refine tools (`@vielzeug/codex/refine`)
 
-### `SnapshotRefineCatalog`
+### `createMcpServerWithRefine`
 
 ```ts
-new SnapshotRefineCatalog(snapshot: LoadedSnapshot)
+createMcpServerWithRefine(catalog: RefineCatalog, options: { version: string; debug?: boolean }): Server;
 ```
 
-Extends `SnapshotCatalog` with `getComponent()` and `listComponents()`.
+Creates a server with the general Vielzeug package catalog tools and the additional `refine-*` component tools.
 
-### `registerRefineTools`
+### `SnapshotRefineCatalog`
 
 ```ts
-registerRefineTools(server: Server, catalog: RefineCatalog, debug?: boolean): void;
+new SnapshotRefineCatalog(snapshot: LoadedSnapshot)
 ```
 
-Upgrades a server created by `createMcpServer()` with the combined generic and `refine-*` tool set. `refineTools` is exported as a readonly registry.
+Extends `SnapshotCatalog` with `getComponent()` and `listComponents()`.
+
+Component declarations and their nested data use readonly TypeScript types.
 
 ## HTTP
 
@@ -4328,22 +4330,22 @@ Upgrades a server created by `createMcpServer()` with the combined generic and `
 startHttpHost(options: HttpHostOptions): Promise;
 ```
 
-Starts Streamable HTTP on `127.0.0.1` by default. Runtime validation accepts only `127.0.0.1` or `::1`; every request must also pass localhost Host and Origin checks. `configureServer` runs once for each lazily created MCP request server and is not called during host startup.
+Starts Streamable HTTP on `127.0.0.1` by default. Runtime validation accepts only `127.0.0.1` or `::1`; every request must also pass localhost Host and Origin checks. `createServer` must return a fresh, unconnected server with its request handlers registered.
 
 ## Types
 
 ```ts
 interface SnapshotPointer {
-  directory: string;
+  readonly directory: string;
 }
 
 interface SnapshotManifest {
-  catalog: 'catalog.json';
-  contentDirectory: 'packages';
-  refine: 'refine.json' | null;
-  schemaVersion: typeof SNAPSHOT_SCHEMA_VERSION;
-  search: 'search.json';
-  version: string;
+  readonly catalog: 'catalog.json';
+  readonly contentDirectory: 'packages';
+  readonly refine: 'refine.json' | null;
+  readonly schemaVersion: typeof SNAPSHOT_SCHEMA_VERSION;
+  readonly search: 'search.json';
+  readonly version: string;
 }
 ```
 
@@ -4351,88 +4353,82 @@ Dev snapshots use `SnapshotPointer` (via `current.json`); published snapshots ar
 
 ```ts
 interface LoadedSnapshot {
-  catalog: CatalogFile;
-  contentDirectory: string;
-  manifest: SnapshotManifest;
-  refineComponents: CemDeclaration[];
-  search: SearchRecord[];
+  readonly catalog: CatalogFile;
+  readonly contentDirectory: string;
+  readonly manifest: SnapshotManifest;
+  readonly refineComponents: readonly CemDeclaration[];
+  readonly search: readonly SearchRecord[];
 }
 ```
 
 ```ts
 interface CatalogFile {
-  packages: PackageMeta[];
-  version: string;
+  readonly packages: readonly PackageMeta[];
+  readonly version: string;
 }
 
 interface SearchRecord {
-  category: string;
-  description: string;
-  docs: Partial>;
-  examples: Array;
-  exports: string;
-  keywords: string;
-  name: string;
-  related: string;
-  slug: string;
-  source: string | null;
+  readonly category: string;
+  readonly description: string;
+  readonly docs: Readonly>>;
+  readonly examples: readonly { readonly id: string; readonly text: string }[];
+  readonly exports: string;
+  readonly keywords: string;
+  readonly name: string;
+  readonly related: string;
+  readonly slug: string;
+  readonly source: string | null;
 }
 
 interface PackageMeta {
-  availableDocPages: DocPage[];
-  category: string;
-  description: string;
-  exampleIds: string[];
-  exports: string[];
-  hasSource: boolean;
-  keywords: string[];
-  name: string;
-  related: string[];
-  slug: string;
-  version: string;
-}
-
-interface PackageContent {
-  apiSource: string | null;
-  docs: Partial>;
-  examples: Example[];
-  typeSignatures: Record;
+  readonly availableDocPages: readonly DocPage[];
+  readonly category: string;
+  readonly description: string;
+  readonly exampleIds: readonly string[];
+  readonly exports: readonly string[];
+  readonly hasSource: boolean;
+  readonly keywords: readonly string[];
+  readonly name: string;
+  readonly related: readonly string[];
+  readonly slug: string;
+  readonly version: string;
 }
 
 interface Example {
-  code: string;
-  id: string;
-  name: string;
+  readonly code: string;
+  readonly id: string;
+  readonly name: string;
 }
 ```
 
 ```ts
 interface Catalog {
-  getContent(slug: string): PackageContent;
   getDocs(slug: string, page: DocPage): string;
   getExample(slug: string, exampleId: string): Example;
   getPackage(slug: string): PackageMeta;
   getSource(slug: string): string;
   getTypeSignature(slug: string, symbol: string): string;
-  listExamples(slug: string): Array>;
-  listPackages(): PackageMeta[];
-  search(query: string): SearchHit[];
+  listExamples(slug: string): readonly Pick[];
+  listPackages(): readonly PackageMeta[];
+  search(query: string): readonly SearchHit[];
 }
 
 interface RefineCatalog extends Catalog {
   getComponent(tagName: string): CemDeclaration;
-  listComponents(): CemDeclaration[];
+  listComponents(): readonly CemDeclaration[];
 }
 
 interface SearchHit {
-  matchedExamples?: string[];
-  matchedIn: Array;
-  matchedPages?: DocPage[];
-  name: string;
-  slug: string;
+  readonly matchedExamples?: readonly string[];
+  readonly matchedIn: readonly ('docs' | 'examples' | 'exports' | 'keywords' | 'metadata' | 'related' | 'source')[];
+  readonly matchedPages?: readonly DocPage[];
+  readonly name: string;
+  readonly slug: string;
 }
 ```
 
+Catalog exposes semantic reads. It does not expose its cached content chunks.
+
 ```ts
 interface HttpHost {
   readonly disposalSignal: AbortSignal;
@@ -4444,9 +4440,7 @@ interface HttpHost {
 }
 
 interface HttpHostOptions {
-  catalog: Catalog;
-  configureServer?: (server: Server) => void;
-  debug?: boolean;
+  createServer: () => Server;
   host?: '127.0.0.1' | '::1';
   port: number;
   version: string;
@@ -4464,54 +4458,54 @@ CEM types and `RefineCatalog` are exported from `/refine`.
 
 ```ts
 interface CemDeclaration {
-  attributes?: CemAttribute[];
-  cssParts?: CemCssPart[];
-  cssProperties?: CemCssProperty[];
-  description?: string;
-  events?: CemEvent[];
-  members?: CemMember[];
-  name?: string;
-  slots?: CemSlot[];
-  superclass?: { name: string; package?: string };
-  tagName?: string;
-  [key: string]: unknown;
+  readonly attributes?: readonly CemAttribute[];
+  readonly cssParts?: readonly CemCssPart[];
+  readonly cssProperties?: readonly CemCssProperty[];
+  readonly description?: string;
+  readonly events?: readonly CemEvent[];
+  readonly members?: readonly CemMember[];
+  readonly name?: string;
+  readonly slots?: readonly CemSlot[];
+  readonly superclass?: { readonly name: string; readonly package?: string };
+  readonly tagName?: string;
+  readonly [key: string]: unknown;
 }
 
 interface CemAttribute {
-  default?: string;
-  description?: string;
-  fieldName?: string;
-  name: string;
-  type?: { text: string };
+  readonly default?: string;
+  readonly description?: string;
+  readonly fieldName?: string;
+  readonly name: string;
+  readonly type?: { readonly text: string };
 }
 
 interface CemCssPart {
-  description?: string;
-  name: string;
+  readonly description?: string;
+  readonly name: string;
 }
 
 interface CemCssProperty {
-  default?: string;
-  description?: string;
-  name: string;
+  readonly default?: string;
+  readonly description?: string;
+  readonly name: string;
 }
 
 interface CemEvent {
-  description?: string;
-  name: string;
-  type?: { text: string };
+  readonly description?: string;
+  readonly name: string;
+  readonly type?: { readonly text: string };
 }
 
 interface CemMember {
-  description?: string;
-  kind?: 'field' | 'method';
-  name: string;
-  type?: { text: string };
+  readonly description?: string;
+  readonly kind?: 'field' | 'method';
+  readonly name: string;
+  readonly type?: { readonly text: string };
 }
 
 interface CemSlot {
-  description?: string;
-  name: string;
+  readonly description?: string;
+  readonly name: string;
 }
 ```
 
@@ -4540,7 +4534,7 @@ npx -y @vielzeug/codex --port=3100
 curl http://127.0.0.1:3100/health
 ```
 
-Response includes snapshot version. Runtime bind validation and Host/Origin allowlists restrict access to localhost; no remote host mode exists. Programmatic `configureServer` hooks run once per MCP request server, not at host startup. Dispose the host asynchronously and observe `disposed` or `disposalSignal` when coordinating shutdown.
+Response includes snapshot version. Runtime bind validation and Host/Origin allowlists restrict access to localhost; no remote host mode exists. Programmatic HTTP hosting takes a `createServer` factory that returns a fresh, unconnected server with its request handlers registered. Dispose the host asynchronously and observe `disposed` or `disposalSignal` when coordinating shutdown.
 
 ## Agent Skill
 
@@ -4590,16 +4584,15 @@ const catalog = new SnapshotCatalog(snapshot);
 await createMcpServer(catalog, { version: snapshot.manifest.version }).connect(new StdioServerTransport());
 ```
 
-To include Refine component tools, upgrade the server with the `@vielzeug/codex/refine` subpath:
+To include Refine component tools, create a server with the `@vielzeug/codex/refine` subpath:
 
 ```ts
-import { StdioServerTransport, createMcpServer, loadSnapshot } from '@vielzeug/codex';
-import { SnapshotRefineCatalog, registerRefineTools } from '@vielzeug/codex/refine';
+import { StdioServerTransport, loadSnapshot } from '@vielzeug/codex';
+import { createMcpServerWithRefine, SnapshotRefineCatalog } from '@vielzeug/codex/refine';
 
 const snapshot = loadSnapshot();
 const catalog = new SnapshotRefineCatalog(snapshot);
-const server = createMcpServer(catalog, { version: snapshot.manifest.version });
-registerRefineTools(server, catalog);
+const server = createMcpServerWithRefine(catalog, { version: snapshot.manifest.version });
 await server.connect(new StdioServerTransport());
 ```
 
@@ -4609,7 +4602,7 @@ await server.connect(new StdioServerTransport());
 - Use `get-type-signature` before loading full source.
 - Published package snapshots are static directories; local dev snapshots are immutable generations selected by `.dev/current.json`.
 - Pass `validateContents: true` to `loadSnapshot()` for artifact verification; normal startup keeps package chunks lazy.
-- Treat `configureServer` as a per-request factory hook and avoid process-global side effects.
+- Return a fresh configured server from `startHttpHost`'s `createServer` factory.
 - Keep HTTP local. Use stdio for normal client integration.
 - Run `pnpm test:unit` before `pnpm test:integration`.
 
@@ -15466,7 +15459,7 @@ animation.dispose();
 - `animate()`: Native element animation with lifecycle ownership and direct native access
 - `animateEach()`: Group ownership with stable keyframe factories and `stagger`
 - `captureLayout()`: One-shot FLIP transition with additive `translate` (position) and `scale` (size)
-- `motion`: `'system'` reduced-motion support with explicit reduced outcomes
+- `motion`: `'system'` reduced-motion support with the same keyframes on instant timing
 - Native timing: Omitted timing fields retain Web Animations API behavior
 - `signal`: Abort a handle from its parent lifecycle
 - `dispose()`: Idempotent cleanup with `[Symbol.dispose]()`
@@ -15480,7 +15473,7 @@ Necromancer owns explicit WAAPI keyframes. It does not generate CSS keyframes, o
 - [Usage Guide](./usage.md)
 - [API Reference](./api.md)
 - [Examples](./examples.md)
-- [3.0 Migration](./migration.md)
+- [Migration Guide](./migration.md)
 
 ## See Also
 
@@ -15638,11 +15631,10 @@ type MotionMode = 'full' | 'reduced' | 'system';
 ```ts
 type AnimationResult =
   | { readonly status: 'finished' }
-  | { readonly status: 'reduced' }
   | { readonly reason?: unknown; readonly status: 'cancelled' };
 ```
 
-`cancelled` describes native cancellation and includes its native rejection reason. A reason passed to `dispose()` or an abort signal takes precedence. The independent `disposed` property becomes `true` only when the lifecycle owner is explicitly disposed.
+A reduced animation finishes: reduction is decided at call time and `shouldReduceMotion()` answers it, so the result reports only what the caller could not know. `cancelled` carries the reason the animation was cancelled: the value passed to `dispose()`, the abort reason of the owning `signal`, or the native rejection reason when something outside Necromancer cancelled the animation. A bare `dispose()` carries no reason. The independent `disposed` property becomes `true` only when the lifecycle owner is explicitly disposed.
 
 ### `AnimateOptions`
 
@@ -15838,7 +15830,7 @@ const result = await handle.result;
 handle.dispose();
 ```
 
-`result` distinguishes natural completion, reduced timing, and cancellation. `disposed` reports only whether the owner was explicitly disposed.
+`result` distinguishes natural completion from cancellation. `disposed` reports only whether the owner was explicitly disposed.
 
 Omitted timing fields retain native Web Animations API behavior. Pass an explicit `duration` when the animation should run over time.
 
@@ -15857,7 +15849,7 @@ const result = await handle.result;
 
 `'system'` is the default and reduces movement when `prefers-reduced-motion: reduce` matches. `'full'` preserves the requested timing, while `'reduced'` always reduces it.
 
-Reduced motion keeps the supplied keyframes but normalizes delay, duration, and end delay to zero and iterations to one. The result is `{ status: 'reduced' }`, and `handle.animation` still represents the requested visual transition.
+Reduced motion keeps the supplied keyframes but normalizes delay, duration, and end delay to zero and iterations to one. The animation finishes immediately, so its result is `{ status: 'finished' }`; call `shouldReduceMotion()` with the same mode when your own code needs to know whether movement was reduced. `handle.animation` still represents the requested visual transition.
 
 ## Parent Cancellation
 
@@ -21860,6 +21852,8 @@ Classification guides discovery and bundle selection. It is not a reason to remo
 | `@vielzeug/refine/frameworks/react` | Register typed React JSX elements | Types only | Does not provide runtime wrappers |
 | `@vielzeug/refine/frameworks/vue` | Register typed Vue global components | Types only | Does not install a Vue plugin |
 | `@vielzeug/refine/theme` | `createThemeController()`: light/dark/system document theme | Sync | Does not persist the preference or set an accent color |
+| `@vielzeug/refine/blueprint` | `parseUiBlueprint()`: validate a model-authored UI document against a fixed registry | Sync | Pure contract only: it registers no components and renders nothing |
+| `@vielzeug/refine/blueprint/render` | `renderUiBlueprint()`: render a validated document with registered components | Sync | Registers its thirteen components on import; rejects before touching the container |
 | `eventFieldValue()` / `eventFieldChecked()` | Read a form control's value/checked from `event.currentTarget` | Sync | Exported from the package root; guards non-field targets |
 | `animateReflow()` | Token-driven FLIP reflow for keyed lists | Async (next frame) | Exported from the package root; elements need stable keys or it correctly does nothing |
 | `setMotionMode()` / `getMotionMode()` | Read/write the `data-motion` attribute on `` | Sync | Exported from the package root; an unknown mode throws `RangeError` |
@@ -21872,6 +21866,8 @@ Classification guides discovery and bundle selection. It is not a reason to remo
 | `@vielzeug/refine` | Export `registerIcons`, icon definition types, `RefineError`, `animateReflow`, the motion-mode functions, and the field readers without registering components |
 | `@vielzeug/refine/` | Register one component and export its tag constant, props, events, and related types |
 | `@vielzeug/refine/theme` | `createThemeController()` and its theme types |
+| `@vielzeug/refine/blueprint` | On-demand UI document contract: `parseUiBlueprint()`, the node types, bounds, `UI_BLUEPRINT_REGISTRY`, and `UI_BLUEPRINT_JSON_SCHEMA` |
+| `@vielzeug/refine/blueprint/render` | `renderUiBlueprint()` and the thirteen component tags it registers |
 | `@vielzeug/refine/tokens.css` | Required global design contract |
 | `@vielzeug/refine/fouc.css` | Optional pre-upgrade visibility rule |
 | `@vielzeug/refine/styles/*` | Focused theme, animation, layer, and preflight stylesheets |
@@ -22043,6 +22039,68 @@ setMotionMode('reduced'); // returns the applied mode
 
 Read/write the `data-motion` attribute on `` (`'full' | 'reduced' | 'system'`; `'system'` removes the attribute). An unknown mode throws `RangeError`. The attribute drives the token layer: see [Animation & Motion → Motion Mode](./animation#motion-mode).
 
+## On-Demand UI Documents
+
+`@vielzeug/refine/blueprint` is the trusted boundary for UI that a model writes. A harness asks a model to describe a small UI in JSON, and this contract decides whether that JSON may be rendered. It is data only: no code, no HTML, no callbacks, no styles, no URLs. See [On-Demand UI Documents](./on-demand-ui) for the full guide.
+
+```ts
+import { parseUiBlueprint, safeParseUiBlueprint } from '@vielzeug/refine/blueprint';
+
+const result = safeParseUiBlueprint(JSON.parse(modelOutput)); // model output stays `unknown`
+if (!result.success) showError(result.issues); // safe to display: field paths, no secrets
+else renderValidated(result.document);
+```
+
+| Export | Purpose |
+| --- | --- |
+| `UI_BLUEPRINT_VERSION` | The only document version accepted (`1`) |
+| `parseUiBlueprint(value)` | Validate `unknown`. Returns the document unchanged, or throws `UiBlueprintError`. Nothing is repaired or partially accepted |
+| `safeParseUiBlueprint(value)` | Non-throwing form: `{ success: true, document }` or `{ success: false, issues }` |
+| `UiBlueprintError` | `RefineError` subclass carrying `issues: readonly string[]`, each a field path such as `root.children[0].size` |
+| `UI_BLUEPRINT_COMPONENTS` | The thirteen accepted component names: `text`, `box`, `card`, `button`, `badge`, `separator`, `slider`, `switch`, `checkbox`, `number-input`, `alert`, `progress`, `icon` |
+| `UI_BLUEPRINT_REGISTRY` | The same registry as data: element tag, child policy, attribute names, slot-text fields, and accepted values per component |
+| `UI_BLUEPRINT_JSON_SCHEMA` | JSON Schema (draft 2020-12) for the contract, for harnesses with structured output |
+| `BlueprintDocument`, `BlueprintNode`, and the node interfaces | TypeScript types for the document shape. Every node accepts an optional bounded `id` through `BlueprintNodeMeta` |
+| `MAX_BLUEPRINT_NODES`, `MAX_BLUEPRINT_DEPTH`, `MAX_BLUEPRINT_CHILDREN`, `MAX_BLUEPRINT_TEXT_LENGTH`, `MAX_BLUEPRINT_LABEL_LENGTH`, `MAX_BLUEPRINT_NUMBER`, `MAX_BLUEPRINT_ID_LENGTH` | Document bounds, not user-configurable |
+
+`@vielzeug/refine/blueprint` imports nothing but `RefineError`: it is pure, DOM-free, and safe to run in a model harness, a worker, or CI. It registers no components.
+
+`UI_BLUEPRINT_JSON_SCHEMA` constrains generation but cannot express the tree-wide node and depth bounds, so runtime validation stays mandatory. Treat the schema as a generation aid, never as the trust boundary.
+
+### `renderUiBlueprint(container, value, options?)`
+
+```ts
+import { renderUiBlueprint } from '@vielzeug/refine/blueprint/render';
+
+try {
+  const { element, nodes } = renderUiBlueprint(host, JSON.parse(modelOutput), { label: 'Generated summary' });
+  nodes.get('rate')?.addEventListener('change', () => recalculate());
+} catch (error) {
+  // The container is untouched: the previous preview is still on screen.
+}
+```
+
+Validate `value`, then render it into `container` using only registry components. Importing the entry registers those thirteen components, so no separate component imports are needed.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `container` | `HTMLElement` | Element that receives the rendered tree |
+| `value` | `unknown` | Untrusted model output. Validated before anything is rendered |
+| `options.label` | `string?` | Accessible name for a `role="group"` wrapper. Host-owned: a document cannot set it |
+| `options.replace` | `boolean?` | Clear the container first. Default `true`; `false` appends |
+
+**Returns** a `UiBlueprintRenderResult`: `{ element, nodes }`, the rendered root and a `ReadonlyMap` keyed by each node's optional `id` so the host can wire behaviour to addressable controls. `id` is host-facing metadata: the renderer never writes it to the DOM. Validation runs first, so a rejected document throws `UiBlueprintError` before the container is read or written: an invalid response can never partially render or erase a valid preview. Text becomes a text node, never markup.
+
+### `createUiBlueprintElement(node, owner?, nodes?)`
+
+```ts
+import { createUiBlueprintElement } from '@vielzeug/refine/blueprint/render';
+
+const element = createUiBlueprintElement(document.root, 'root', nodeMap);
+```
+
+Build one element for an already-validated node. Pass a `Map` as `nodes` to collect every id-tagged element it creates, including nested ones; `owner` labels the node's position in rejection messages. This is the component registry: adding a component means adding a rule in the contract and a case here, and nothing else. It throws `TypeError` for an unregistered node type, so a hand-built node cannot bypass validation either. Embedders that place nodes themselves use this; `renderUiBlueprint()` is the normal entry point.
+
 ## Types
 
 Component props follow the `OreProps` naming pattern. Event maps follow `OreEvents`. Import both from the component subpath that owns them.
@@ -22063,6 +22121,16 @@ class RefineError extends Error {
 
 Base class for public Refine errors. It preserves `cause` through `ErrorOptions`.
 
+### `UiBlueprintError`
+
+```ts
+class UiBlueprintError extends RefineError {
+  readonly issues: readonly string[];
+}
+```
+
+Thrown by `parseUiBlueprint()` and `renderUiBlueprint()` for a rejected on-demand UI document. Every rejection is collected first, so `issues` lists all of them at once, each as a field path plus a plain reason (`root.children[0].size: expected one of sm, md, lg, received string.`). The messages name fields and allowed values, report a wrong-typed value only as its *type*, and echo an accepted-type value only as a truncated snippet, so they are safe to display to a user. See [On-Demand UI Documents](./on-demand-ui).
+
 ### Usage Guide
 
 ## Basic Usage
@@ -22307,6 +22375,7 @@ Use Necromancer directly when you need animation handles, groups, or explicit ke
 - **Dispose** application-owned Ripple effects and service handles.
 - **Guard** DOM-dependent component registration during SSR.
 - **Working with AI agents?** Install the `vielzeug` skill (`npx -y @vielzeug/codex skills install`) so agents reach for Refine components and tokens instead of custom widgets: see the [Codex usage guide](../codex/usage.md#agent-skill).
+- **Rendering model-authored UI?** Validate it through the [on-demand UI document contract](./on-demand-ui) instead of trusting model output; never build DOM from unvalidated JSON.
 
 ---
 

package/data/llms.txt

@@ -1,6 +1,6 @@
 # Vielzeug
 
-> 43 focused TypeScript packages. Version: 26.11.1
+> 43 focused TypeScript packages. Version: 26.11.3
 
 Install any package independently: `pnpm add @vielzeug/<name>`
 

package/data/manifest.json

@@ -4,5 +4,5 @@
   "refine": "refine.json",
   "schemaVersion": 1,
   "search": "search.json",
-  "version": "26.11.1"
+  "version": "26.11.3"
 }

package/data/packages/codex.json

@@ -1,9 +1,9 @@
 {
-  "apiSource": "/**\n * `@vielzeug/codex`: supported public contract.\n *\n * Exposes the generic catalog, snapshot loader, errors, and server hosts.\n * Refine catalog types and tools live behind `@vielzeug/codex/refine`.\n */\nexport { StdioServerTransport } from '@modelcontextprotocol/server/stdio';\nexport { type Catalog, CatalogError, type SearchHit, SnapshotCatalog } from './catalog.js';\nexport { CodexError } from './errors.js';\nexport { type HttpHost, type HttpHostOptions, startHttpHost } from './http.js';\nexport { createMcpServer } from './server.js';\nexport { type LoadedSnapshot, loadSnapshot } from './snapshot.js';\nexport type {\n  DocPage,\n  Example,\n  PackageContent,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';\n",
+  "apiSource": "/**\n * `@vielzeug/codex`: supported public contract.\n *\n * Exposes the generic catalog, snapshot loader, errors, and server hosts.\n * Refine catalog types and tools live behind `@vielzeug/codex/refine`.\n */\nexport { StdioServerTransport } from '@modelcontextprotocol/server/stdio';\nexport { type Catalog, CatalogError, type SearchHit, SnapshotCatalog } from './catalog.js';\nexport { CodexError } from './errors.js';\nexport { type HttpHost, type HttpHostOptions, startHttpHost } from './http.js';\nexport { createMcpServer } from './server.js';\nexport { type LoadedSnapshot, loadSnapshot } from './snapshot.js';\nexport type {\n  DocPage,\n  Example,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';\n",
   "docs": {
-    "index": "---\ntitle: Codex\ndescription: Local MCP access to Vielzeug documentation and package metadata.\npackage: codex\ncategory: AI\nkeywords: [mcp, docs, ai]\nrelated: [refine]\nexports: [loadSnapshot, SnapshotCatalog, createMcpServer, startHttpHost, StdioServerTransport, CatalogError, CodexError]\nenvironments: [node]\n---\n\n<PackageHero package=\"codex\" />\n\n## Why Codex?\n\nCodex exposes current Vielzeug catalog data through MCP without scanning source at request time.\n\n## Installation\n\n```sh\npnpm add @vielzeug/codex\n```\n\n## Quick Start\n\n```sh\nnpx -y @vielzeug/codex\n```\n\n## Features\n\n- `loadSnapshot` validates chunked snapshot metadata.\n- `SnapshotCatalog` loads package content only when requested.\n- `createMcpServer` registers generic package tools; `/refine` adds component tools explicitly.\n- Root and `/refine` entry points publish TypeScript declarations.\n- `startHttpHost` enforces loopback binding plus localhost Host and Origin validation.\n\n## Documentation\n\n- [Usage](./usage.md)\n- [API](./api.md)\n- [Examples](./examples.md)\n- [Migration Guide](./migration.md)\n\n## See Also\n\n- [Refine](../refine/) provides component metadata bundled by Codex.\n",
-    "api": "---\ntitle: Codex API\ndescription: Snapshot, catalog, MCP server, and local HTTP host APIs.\n---\n\n[[toc]]\n\n## API Overview\n\n| Symbol | Purpose | Execution mode | Common gotcha |\n| --- | --- | --- | --- |\n| `loadSnapshot` | Read validated snapshot metadata | Sync | Content chunks load lazily |\n| `SnapshotCatalog` | Query package corpus | Sync | Construct from loaded snapshot |\n| `createMcpServer` | MCP adapter factory (generic tools) | Sync | Requires catalog and version |\n| `startHttpHost` | Loopback Streamable HTTP host | Async | HTTP remains local-only |\n| `registerRefineTools` | Opt-in Refine tool registration | Sync | Import from `@vielzeug/codex/refine` |\n\n## Package Entry Points\n\n| Import | Purpose |\n| --- | --- |\n| `@vielzeug/codex` | `Catalog`, `SnapshotCatalog`, `loadSnapshot`, MCP server, and HTTP host |\n| `@vielzeug/codex/refine` | Opt-in Refine component tools (`registerRefineTools`) |\n\n## Snapshot\n\n### `loadSnapshot`\n\n```ts\nloadSnapshot(snapshotRoot?: string, options?: { validateContents?: boolean }): LoadedSnapshot;\n```\n\nLoads catalog/search metadata and Refine metadata. `snapshotRoot` defaults to bundled `data/`. Package content chunks stay lazy unless `validateContents: true`, which validates every package content chunk during loading.\n\n### `SnapshotCatalog`\n\n```ts\nnew SnapshotCatalog(snapshot: LoadedSnapshot)\n```\n\nProvides generic package lookup, docs/source/example/signature access, and deterministic search. Use `SnapshotRefineCatalog` from `/refine` when component methods are needed.\n\n---\n\n## MCP\n\n### `createMcpServer`\n\n```ts\ncreateMcpServer(catalog: Catalog, options: { version: string; debug?: boolean }): Server;\n```\n\nRegisters generic package tools over `Catalog`. Refine tools are opt-in through `/refine`. The root also re-exports `StdioServerTransport` for connecting the server without a second package import.\n\n## Refine tools (`@vielzeug/codex/refine`)\n\n### `SnapshotRefineCatalog`\n\n```ts\nnew SnapshotRefineCatalog(snapshot: LoadedSnapshot)\n```\n\nExtends `SnapshotCatalog` with `getComponent()` and `listComponents()`.\n\n### `registerRefineTools`\n\n```ts\nregisterRefineTools(server: Server, catalog: RefineCatalog, debug?: boolean): void;\n```\n\nUpgrades a server created by `createMcpServer()` with the combined generic and `refine-*` tool set. `refineTools` is exported as a readonly registry.\n\n## HTTP\n\n### `startHttpHost`\n\n```ts\nstartHttpHost(options: HttpHostOptions): Promise<HttpHost>;\n```\n\nStarts Streamable HTTP on `127.0.0.1` by default. Runtime validation accepts only `127.0.0.1` or `::1`; every request must also pass localhost Host and Origin checks. `configureServer` runs once for each lazily created MCP request server and is not called during host startup.\n\n## Types\n\n```ts\ninterface SnapshotPointer {\n  directory: string;\n}\n\ninterface SnapshotManifest {\n  catalog: 'catalog.json';\n  contentDirectory: 'packages';\n  refine: 'refine.json' | null;\n  schemaVersion: typeof SNAPSHOT_SCHEMA_VERSION;\n  search: 'search.json';\n  version: string;\n}\n```\n\nDev snapshots use `SnapshotPointer` (via `current.json`); published snapshots are static directories.\n\n```ts\ninterface LoadedSnapshot {\n  catalog: CatalogFile;\n  contentDirectory: string;\n  manifest: SnapshotManifest;\n  refineComponents: CemDeclaration[];\n  search: SearchRecord[];\n}\n```\n\n```ts\ninterface CatalogFile {\n  packages: PackageMeta[];\n  version: string;\n}\n\ninterface SearchRecord {\n  category: string;\n  description: string;\n  docs: Partial<Record<DocPage, string>>;\n  examples: Array<{ id: string; text: string }>;\n  exports: string;\n  keywords: string;\n  name: string;\n  related: string;\n  slug: string;\n  source: string | null;\n}\n\ninterface PackageMeta {\n  availableDocPages: DocPage[];\n  category: string;\n  description: string;\n  exampleIds: string[];\n  exports: string[];\n  hasSource: boolean;\n  keywords: string[];\n  name: string;\n  related: string[];\n  slug: string;\n  version: string;\n}\n\ninterface PackageContent {\n  apiSource: string | null;\n  docs: Partial<Record<DocPage, string>>;\n  examples: Example[];\n  typeSignatures: Record<string, string>;\n}\n\ninterface Example {\n  code: string;\n  id: string;\n  name: string;\n}\n```\n\n```ts\ninterface Catalog {\n  getContent(slug: string): PackageContent;\n  getDocs(slug: string, page: DocPage): string;\n  getExample(slug: string, exampleId: string): Example;\n  getPackage(slug: string): PackageMeta;\n  getSource(slug: string): string;\n  getTypeSignature(slug: string, symbol: string): string;\n  listExamples(slug: string): Array<Pick<Example, 'id' | 'name'>>;\n  listPackages(): PackageMeta[];\n  search(query: string): SearchHit[];\n}\n\ninterface RefineCatalog extends Catalog {\n  getComponent(tagName: string): CemDeclaration;\n  listComponents(): CemDeclaration[];\n}\n\ninterface SearchHit {\n  matchedExamples?: string[];\n  matchedIn: Array<'docs' | 'examples' | 'exports' | 'keywords' | 'metadata' | 'related' | 'source'>;\n  matchedPages?: DocPage[];\n  name: string;\n  slug: string;\n}\n```\n\n```ts\ninterface HttpHost {\n  readonly disposalSignal: AbortSignal;\n  dispose(): Promise<void>;\n  readonly disposed: boolean;\n  readonly host: string;\n  readonly port: number;\n  [Symbol.asyncDispose](): Promise<void>;\n}\n\ninterface HttpHostOptions {\n  catalog: Catalog;\n  configureServer?: (server: Server) => void;\n  debug?: boolean;\n  host?: '127.0.0.1' | '::1';\n  port: number;\n  version: string;\n}\n```\n\n```ts\nconst DOC_PAGES = ['index', 'api', 'usage', 'examples'] as const;\ntype DocPage = (typeof DOC_PAGES)[number];\n\nconst SNAPSHOT_SCHEMA_VERSION = 1 as const;\n```\n\nCEM types and `RefineCatalog` are exported from `/refine`.\n\n```ts\ninterface CemDeclaration {\n  attributes?: CemAttribute[];\n  cssParts?: CemCssPart[];\n  cssProperties?: CemCssProperty[];\n  description?: string;\n  events?: CemEvent[];\n  members?: CemMember[];\n  name?: string;\n  slots?: CemSlot[];\n  superclass?: { name: string; package?: string };\n  tagName?: string;\n  [key: string]: unknown;\n}\n\ninterface CemAttribute {\n  default?: string;\n  description?: string;\n  fieldName?: string;\n  name: string;\n  type?: { text: string };\n}\n\ninterface CemCssPart {\n  description?: string;\n  name: string;\n}\n\ninterface CemCssProperty {\n  default?: string;\n  description?: string;\n  name: string;\n}\n\ninterface CemEvent {\n  description?: string;\n  name: string;\n  type?: { text: string };\n}\n\ninterface CemMember {\n  description?: string;\n  kind?: 'field' | 'method';\n  name: string;\n  type?: { text: string };\n}\n\ninterface CemSlot {\n  description?: string;\n  name: string;\n}\n```\n\n## Errors\n\n`CodexError` signals malformed snapshots or host failures. `CatalogError` adds `INVALID_ARG`, `NOT_FOUND`, or `UNAVAILABLE` for expected tool failures.\n",
-    "usage": "---\ntitle: 'Codex: Usage Guide'\ndescription: Install, connect, develop, and debug the Vielzeug MCP server.\n---\n\n[[toc]]\n\n## Basic Usage\n\nRun local stdio server:\n\n```sh\nnpx -y @vielzeug/codex\n```\n\nUse shipped `mcp-setup.json` for machine-readable generic configuration. Client-specific configuration must use its documented MCP format.\n\n## HTTP Mode\n\nHTTP uses Streamable HTTP and binds loopback only:\n\n```sh\nnpx -y @vielzeug/codex --port=3100\ncurl http://127.0.0.1:3100/health\n```\n\nResponse includes snapshot version. Runtime bind validation and Host/Origin allowlists restrict access to localhost; no remote host mode exists. Programmatic `configureServer` hooks run once per MCP request server, not at host startup. Dispose the host asynchronously and observe `disposed` or `disposalSignal` when coordinating shutdown.\n\n## Agent Skill\n\nCodex ships a `vielzeug` agent skill: a `SKILL.md` that tells an AI agent working in *your* project to discover packages through the MCP tools instead of guessing, to use the owning `@vielzeug/*` package instead of hand-rolling, and to build UI from Refine components, tokens, and theme whenever `@vielzeug/refine` is installed. Install it into the project:\n\n```sh\nnpx -y @vielzeug/codex skills install\nnpx -y @vielzeug/codex skills install --target=.claude/skills\nnpx -y @vielzeug/codex skills install --force   # overwrite an existing copy\n```\n\nWithout `--target`, the first existing directory among `.agents/skills`, `.github/skills`, and `.claude/skills` is used; when none exists, `.agents/skills` is created. The command refuses to overwrite an installed skill unless `--force` is passed. Rerun after upgrading codex to pick up the current package list, which is generated from the published manifests. The skill pairs with the MCP server: its lookups (`get-docs`, `refine-get-component`, `refine-validate-usage`, …) assume codex is connected, and it documents `node_modules` fallbacks for when it is not.\n\n## Local Development\n\nRequires Node 22+ and root setup:\n\n```sh\npnpm setup\ncd packages/codex\npnpm test:unit\npnpm test:integration\npnpm dev\n```\n\n`test:unit` uses fixtures only. `test:integration` regenerates a current snapshot then checks real monorepo inputs.\n\n`pnpm dev` watches documentation and package inputs, atomically publishes snapshots, then restarts server when snapshot changes.\n\n## Debugging\n\n```sh\npnpm dev\nnode src/cli.ts --port=3100 --debug\ncurl http://127.0.0.1:3100/health\n```\n\n`--debug` logs tool durations and expected catalog errors to stderr. Build `@vielzeug/refine` before generating snapshot when component metadata changes.\n\n## Programmatic Usage\n\n```ts\nimport { SnapshotCatalog, StdioServerTransport, createMcpServer, loadSnapshot } from '@vielzeug/codex';\n\nconst snapshot = loadSnapshot();\nconst catalog = new SnapshotCatalog(snapshot);\nawait createMcpServer(catalog, { version: snapshot.manifest.version }).connect(new StdioServerTransport());\n```\n\nTo include Refine component tools, upgrade the server with the `@vielzeug/codex/refine` subpath:\n\n```ts\nimport { StdioServerTransport, createMcpServer, loadSnapshot } from '@vielzeug/codex';\nimport { SnapshotRefineCatalog, registerRefineTools } from '@vielzeug/codex/refine';\n\nconst snapshot = loadSnapshot();\nconst catalog = new SnapshotRefineCatalog(snapshot);\nconst server = createMcpServer(catalog, { version: snapshot.manifest.version });\nregisterRefineTools(server, catalog);\nawait server.connect(new StdioServerTransport());\n```\n\n## Best Practices\n\n- Use `search-packages` for capability discovery before loading broad source.\n- Use `get-type-signature` before loading full source.\n- Published package snapshots are static directories; local dev snapshots are immutable generations selected by `.dev/current.json`.\n- Pass `validateContents: true` to `loadSnapshot()` for artifact verification; normal startup keeps package chunks lazy.\n- Treat `configureServer` as a per-request factory hook and avoid process-global side effects.\n- Keep HTTP local. Use stdio for normal client integration.\n- Run `pnpm test:unit` before `pnpm test:integration`.\n",
+    "index": "---\ntitle: Codex\ndescription: Local MCP access to Vielzeug documentation and package metadata.\npackage: codex\ncategory: AI\nkeywords: [mcp, docs, ai]\nrelated: [refine]\nexports: [loadSnapshot, SnapshotCatalog, createMcpServer, createMcpServerWithRefine, startHttpHost, StdioServerTransport, CatalogError, CodexError]\nenvironments: [node]\n---\n\n<PackageHero package=\"codex\" />\n\n## Why Codex?\n\nCodex exposes current Vielzeug catalog data through MCP without scanning source at request time.\n\n## Installation\n\n```sh\npnpm add @vielzeug/codex\n```\n\n## Quick Start\n\n```sh\nnpx -y @vielzeug/codex\n```\n\n## Features\n\n- `loadSnapshot` validates chunked snapshot metadata.\n- `SnapshotCatalog` loads package content only when requested.\n- `createMcpServer` registers generic package tools; `/refine` adds component tools explicitly.\n- Root and `/refine` entry points publish TypeScript declarations.\n- `startHttpHost` enforces loopback binding plus localhost Host and Origin validation.\n\n## Documentation\n\n- [Usage](./usage.md)\n- [API](./api.md)\n- [Examples](./examples.md)\n- [Migration Guide](./migration.md)\n\n## See Also\n\n- [Refine](../refine/) provides component metadata bundled by Codex.\n",
+    "api": "---\ntitle: Codex API\ndescription: Snapshot, catalog, MCP server, and local HTTP host APIs.\n---\n\n[[toc]]\n\n## API Overview\n\n| Symbol | Purpose | Execution mode | Common gotcha |\n| --- | --- | --- | --- |\n| `loadSnapshot` | Read validated snapshot metadata | Sync | Content chunks load lazily |\n| `SnapshotCatalog` | Query package corpus | Sync | Construct from loaded snapshot |\n| `createMcpServer` | MCP adapter factory (generic tools) | Sync | Requires catalog and version |\n| `createMcpServerWithRefine` | MCP adapter factory (all package and Refine tools) | Sync | Import from `@vielzeug/codex/refine` |\n| `startHttpHost` | Loopback Streamable HTTP host | Async | HTTP remains local-only |\n\n## Package Entry Points\n\n| Import | Purpose |\n| --- | --- |\n| `@vielzeug/codex` | `Catalog`, `SnapshotCatalog`, `loadSnapshot`, MCP server, and HTTP host |\n| `@vielzeug/codex/refine` | Refine catalog and MCP server with component tools |\n\n## Snapshot\n\n### `loadSnapshot`\n\n```ts\nloadSnapshot(snapshotRoot?: string, options?: { validateContents?: boolean }): LoadedSnapshot;\n```\n\nLoads catalog/search metadata and Refine metadata. `snapshotRoot` defaults to bundled `data/`. Package content chunks stay lazy unless `validateContents: true`, which validates every package content chunk during loading.\n\n### `SnapshotCatalog`\n\n```ts\nnew SnapshotCatalog(snapshot: LoadedSnapshot)\n```\n\nProvides generic package lookup, docs/source/example/signature access, and deterministic search. Use `SnapshotRefineCatalog` from `/refine` when component methods are needed.\n\n---\n\n## MCP\n\n### `createMcpServer`\n\n```ts\ncreateMcpServer(catalog: Catalog, options: { version: string; debug?: boolean }): Server;\n```\n\nRegisters generic package tools over `Catalog`. Refine tools are opt-in through `/refine`. The root also re-exports `StdioServerTransport` for connecting the server without a second package import.\n\n## Refine tools (`@vielzeug/codex/refine`)\n\n### `createMcpServerWithRefine`\n\n```ts\ncreateMcpServerWithRefine(catalog: RefineCatalog, options: { version: string; debug?: boolean }): Server;\n```\n\nCreates a server with the general Vielzeug package catalog tools and the additional `refine-*` component tools.\n\n### `SnapshotRefineCatalog`\n\n```ts\nnew SnapshotRefineCatalog(snapshot: LoadedSnapshot)\n```\n\nExtends `SnapshotCatalog` with `getComponent()` and `listComponents()`.\n\nComponent declarations and their nested data use readonly TypeScript types.\n\n## HTTP\n\n### `startHttpHost`\n\n```ts\nstartHttpHost(options: HttpHostOptions): Promise<HttpHost>;\n```\n\nStarts Streamable HTTP on `127.0.0.1` by default. Runtime validation accepts only `127.0.0.1` or `::1`; every request must also pass localhost Host and Origin checks. `createServer` must return a fresh, unconnected server with its request handlers registered.\n\n## Types\n\n```ts\ninterface SnapshotPointer {\n  readonly directory: string;\n}\n\ninterface SnapshotManifest {\n  readonly catalog: 'catalog.json';\n  readonly contentDirectory: 'packages';\n  readonly refine: 'refine.json' | null;\n  readonly schemaVersion: typeof SNAPSHOT_SCHEMA_VERSION;\n  readonly search: 'search.json';\n  readonly version: string;\n}\n```\n\nDev snapshots use `SnapshotPointer` (via `current.json`); published snapshots are static directories.\n\n```ts\ninterface LoadedSnapshot {\n  readonly catalog: CatalogFile;\n  readonly contentDirectory: string;\n  readonly manifest: SnapshotManifest;\n  readonly refineComponents: readonly CemDeclaration[];\n  readonly search: readonly SearchRecord[];\n}\n```\n\n```ts\ninterface CatalogFile {\n  readonly packages: readonly PackageMeta[];\n  readonly version: string;\n}\n\ninterface SearchRecord {\n  readonly category: string;\n  readonly description: string;\n  readonly docs: Readonly<Partial<Record<DocPage, string>>>;\n  readonly examples: readonly { readonly id: string; readonly text: string }[];\n  readonly exports: string;\n  readonly keywords: string;\n  readonly name: string;\n  readonly related: string;\n  readonly slug: string;\n  readonly source: string | null;\n}\n\ninterface PackageMeta {\n  readonly availableDocPages: readonly DocPage[];\n  readonly category: string;\n  readonly description: string;\n  readonly exampleIds: readonly string[];\n  readonly exports: readonly string[];\n  readonly hasSource: boolean;\n  readonly keywords: readonly string[];\n  readonly name: string;\n  readonly related: readonly string[];\n  readonly slug: string;\n  readonly version: string;\n}\n\ninterface Example {\n  readonly code: string;\n  readonly id: string;\n  readonly name: string;\n}\n```\n\n```ts\ninterface Catalog {\n  getDocs(slug: string, page: DocPage): string;\n  getExample(slug: string, exampleId: string): Example;\n  getPackage(slug: string): PackageMeta;\n  getSource(slug: string): string;\n  getTypeSignature(slug: string, symbol: string): string;\n  listExamples(slug: string): readonly Pick<Example, 'id' | 'name'>[];\n  listPackages(): readonly PackageMeta[];\n  search(query: string): readonly SearchHit[];\n}\n\ninterface RefineCatalog extends Catalog {\n  getComponent(tagName: string): CemDeclaration;\n  listComponents(): readonly CemDeclaration[];\n}\n\ninterface SearchHit {\n  readonly matchedExamples?: readonly string[];\n  readonly matchedIn: readonly ('docs' | 'examples' | 'exports' | 'keywords' | 'metadata' | 'related' | 'source')[];\n  readonly matchedPages?: readonly DocPage[];\n  readonly name: string;\n  readonly slug: string;\n}\n```\n\nCatalog exposes semantic reads. It does not expose its cached content chunks.\n\n```ts\ninterface HttpHost {\n  readonly disposalSignal: AbortSignal;\n  dispose(): Promise<void>;\n  readonly disposed: boolean;\n  readonly host: string;\n  readonly port: number;\n  [Symbol.asyncDispose](): Promise<void>;\n}\n\ninterface HttpHostOptions {\n  createServer: () => Server;\n  host?: '127.0.0.1' | '::1';\n  port: number;\n  version: string;\n}\n```\n\n```ts\nconst DOC_PAGES = ['index', 'api', 'usage', 'examples'] as const;\ntype DocPage = (typeof DOC_PAGES)[number];\n\nconst SNAPSHOT_SCHEMA_VERSION = 1 as const;\n```\n\nCEM types and `RefineCatalog` are exported from `/refine`.\n\n```ts\ninterface CemDeclaration {\n  readonly attributes?: readonly CemAttribute[];\n  readonly cssParts?: readonly CemCssPart[];\n  readonly cssProperties?: readonly CemCssProperty[];\n  readonly description?: string;\n  readonly events?: readonly CemEvent[];\n  readonly members?: readonly CemMember[];\n  readonly name?: string;\n  readonly slots?: readonly CemSlot[];\n  readonly superclass?: { readonly name: string; readonly package?: string };\n  readonly tagName?: string;\n  readonly [key: string]: unknown;\n}\n\ninterface CemAttribute {\n  readonly default?: string;\n  readonly description?: string;\n  readonly fieldName?: string;\n  readonly name: string;\n  readonly type?: { readonly text: string };\n}\n\ninterface CemCssPart {\n  readonly description?: string;\n  readonly name: string;\n}\n\ninterface CemCssProperty {\n  readonly default?: string;\n  readonly description?: string;\n  readonly name: string;\n}\n\ninterface CemEvent {\n  readonly description?: string;\n  readonly name: string;\n  readonly type?: { readonly text: string };\n}\n\ninterface CemMember {\n  readonly description?: string;\n  readonly kind?: 'field' | 'method';\n  readonly name: string;\n  readonly type?: { readonly text: string };\n}\n\ninterface CemSlot {\n  readonly description?: string;\n  readonly name: string;\n}\n```\n\n## Errors\n\n`CodexError` signals malformed snapshots or host failures. `CatalogError` adds `INVALID_ARG`, `NOT_FOUND`, or `UNAVAILABLE` for expected tool failures.\n",
+    "usage": "---\ntitle: 'Codex: Usage Guide'\ndescription: Install, connect, develop, and debug the Vielzeug MCP server.\n---\n\n[[toc]]\n\n## Basic Usage\n\nRun local stdio server:\n\n```sh\nnpx -y @vielzeug/codex\n```\n\nUse shipped `mcp-setup.json` for machine-readable generic configuration. Client-specific configuration must use its documented MCP format.\n\n## HTTP Mode\n\nHTTP uses Streamable HTTP and binds loopback only:\n\n```sh\nnpx -y @vielzeug/codex --port=3100\ncurl http://127.0.0.1:3100/health\n```\n\nResponse includes snapshot version. Runtime bind validation and Host/Origin allowlists restrict access to localhost; no remote host mode exists. Programmatic HTTP hosting takes a `createServer` factory that returns a fresh, unconnected server with its request handlers registered. Dispose the host asynchronously and observe `disposed` or `disposalSignal` when coordinating shutdown.\n\n## Agent Skill\n\nCodex ships a `vielzeug` agent skill: a `SKILL.md` that tells an AI agent working in *your* project to discover packages through the MCP tools instead of guessing, to use the owning `@vielzeug/*` package instead of hand-rolling, and to build UI from Refine components, tokens, and theme whenever `@vielzeug/refine` is installed. Install it into the project:\n\n```sh\nnpx -y @vielzeug/codex skills install\nnpx -y @vielzeug/codex skills install --target=.claude/skills\nnpx -y @vielzeug/codex skills install --force   # overwrite an existing copy\n```\n\nWithout `--target`, the first existing directory among `.agents/skills`, `.github/skills`, and `.claude/skills` is used; when none exists, `.agents/skills` is created. The command refuses to overwrite an installed skill unless `--force` is passed. Rerun after upgrading codex to pick up the current package list, which is generated from the published manifests. The skill pairs with the MCP server: its lookups (`get-docs`, `refine-get-component`, `refine-validate-usage`, …) assume codex is connected, and it documents `node_modules` fallbacks for when it is not.\n\n## Local Development\n\nRequires Node 22+ and root setup:\n\n```sh\npnpm setup\ncd packages/codex\npnpm test:unit\npnpm test:integration\npnpm dev\n```\n\n`test:unit` uses fixtures only. `test:integration` regenerates a current snapshot then checks real monorepo inputs.\n\n`pnpm dev` watches documentation and package inputs, atomically publishes snapshots, then restarts server when snapshot changes.\n\n## Debugging\n\n```sh\npnpm dev\nnode src/cli.ts --port=3100 --debug\ncurl http://127.0.0.1:3100/health\n```\n\n`--debug` logs tool durations and expected catalog errors to stderr. Build `@vielzeug/refine` before generating snapshot when component metadata changes.\n\n## Programmatic Usage\n\n```ts\nimport { SnapshotCatalog, StdioServerTransport, createMcpServer, loadSnapshot } from '@vielzeug/codex';\n\nconst snapshot = loadSnapshot();\nconst catalog = new SnapshotCatalog(snapshot);\nawait createMcpServer(catalog, { version: snapshot.manifest.version }).connect(new StdioServerTransport());\n```\n\nTo include Refine component tools, create a server with the `@vielzeug/codex/refine` subpath:\n\n```ts\nimport { StdioServerTransport, loadSnapshot } from '@vielzeug/codex';\nimport { createMcpServerWithRefine, SnapshotRefineCatalog } from '@vielzeug/codex/refine';\n\nconst snapshot = loadSnapshot();\nconst catalog = new SnapshotRefineCatalog(snapshot);\nconst server = createMcpServerWithRefine(catalog, { version: snapshot.manifest.version });\nawait server.connect(new StdioServerTransport());\n```\n\n## Best Practices\n\n- Use `search-packages` for capability discovery before loading broad source.\n- Use `get-type-signature` before loading full source.\n- Published package snapshots are static directories; local dev snapshots are immutable generations selected by `.dev/current.json`.\n- Pass `validateContents: true` to `loadSnapshot()` for artifact verification; normal startup keeps package chunks lazy.\n- Return a fresh configured server from `startHttpHost`'s `createServer` factory.\n- Keep HTTP local. Use stdio for normal client integration.\n- Run `pnpm test:unit` before `pnpm test:integration`.\n",
     "examples": "---\ntitle: 'Codex: Examples'\ndescription: Practical MCP tool-call examples for package discovery, docs lookup, and Refine component queries.\n---\n\n## Examples\n\n- [Listing Packages](./examples/listing-packages.md)\n- [Searching Packages](./examples/searching-packages.md)\n- [Package Metadata](./examples/package-metadata.md)\n- [Reading Docs](./examples/reading-docs.md)\n- [Running REPL Examples](./examples/running-repl-examples.md)\n- [Looking Up Components](./examples/looking-up-components.md)\n- [Inspector](./examples/inspector.md)\n"
   },
   "examples": [],
@@ -20,10 +20,9 @@
     "createMcpServer": "export { createMcpServer } from './server.js';",
     "LoadedSnapshot": "export { type LoadedSnapshot, loadSnapshot } from './snapshot.js';",
     "loadSnapshot": "export { type LoadedSnapshot, loadSnapshot } from './snapshot.js';",
-    "DocPage": "export type {\n  DocPage,\n  Example,\n  PackageContent,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';",
-    "Example": "export type {\n  DocPage,\n  Example,\n  PackageContent,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';",
-    "PackageContent": "export type {\n  DocPage,\n  Example,\n  PackageContent,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';",
-    "PackageMeta": "export type {\n  DocPage,\n  Example,\n  PackageContent,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';",
-    "SnapshotManifest": "export type {\n  DocPage,\n  Example,\n  PackageContent,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';"
+    "DocPage": "export type {\n  DocPage,\n  Example,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';",
+    "Example": "export type {\n  DocPage,\n  Example,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';",
+    "PackageMeta": "export type {\n  DocPage,\n  Example,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';",
+    "SnapshotManifest": "export type {\n  DocPage,\n  Example,\n  PackageMeta,\n  SnapshotManifest,\n} from './types.js';"
   }
 }