@vielzeug/codex 26.11.1 → 26.11.3

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug: Full Documentation
 
-> Complete documentation for 43 packages. Version: 26.11.0
+> Complete documentation for 43 packages. Version: 26.11.2
 
 ---
 
@@ -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
 

package/data/llms.txt

@@ -1,6 +1,6 @@
 # Vielzeug
 
-> 43 focused TypeScript packages. Version: 26.11.0
+> 43 focused TypeScript packages. Version: 26.11.2
 
 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.0"
+  "version": "26.11.2"
 }

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';"
   }
 }