@outfitter/schema 0.2.0

package/README.md

@@ -0,0 +1,126 @@
+# @outfitter/schema
+
+Schema introspection, surface map generation, and drift detection for Outfitter action registries.
+
+**Stability: Active** -- APIs evolving based on usage.
+
+## Installation
+
+```bash
+bun add @outfitter/schema zod
+```
+
+`zod` is a peer dependency because schema generation converts Zod input/output contracts into JSON Schema.
+
+## Quick Start
+
+```typescript
+import { createActionRegistry, defineAction, Result } from "@outfitter/contracts";
+import { generateSurfaceMap } from "@outfitter/schema/surface";
+import { z } from "zod";
+
+const registry = createActionRegistry().add(
+  defineAction({
+    id: "doctor",
+    description: "Validate environment",
+    surfaces: ["cli", "mcp"],
+    input: z.object({ verbose: z.boolean().optional() }),
+    handler: async () => Result.ok({ ok: true }),
+  })
+);
+
+const surface = generateSurfaceMap(registry, {
+  version: "1.0.0",
+  generator: "runtime",
+});
+
+console.log(surface.actions.map((a) => a.id));
+```
+
+## Subpath Exports
+
+| Subpath | What's In It |
+|---------|---------------|
+| `@outfitter/schema` | Full public API from all modules |
+| `@outfitter/schema/manifest` | `generateManifest`, `ActionManifest*` types |
+| `@outfitter/schema/surface` | `generateSurfaceMap`, snapshot path + read/write helpers |
+| `@outfitter/schema/diff` | `diffSurfaceMaps`, diff result types |
+| `@outfitter/schema/markdown` | `formatManifestMarkdown`, markdown formatting options |
+
+## Core Workflows
+
+### 1) Generate a manifest from an action registry
+
+```typescript
+import { generateManifest } from "@outfitter/schema/manifest";
+
+const manifest = generateManifest(registry, {
+  version: "1.0.0",
+  surface: "mcp", // optional: cli | mcp | api
+});
+
+console.log(manifest.errors.validation.exit); // 1
+console.log(manifest.outputModes); // ["human", "json", "jsonl", "tree", "table"]
+```
+
+### 2) Generate and persist a surface map snapshot
+
+```typescript
+import {
+  generateSurfaceMap,
+  resolveSnapshotPath,
+  writeSurfaceMap,
+} from "@outfitter/schema/surface";
+
+const surface = generateSurfaceMap(registry, {
+  version: "1.0.0",
+  generator: "build",
+});
+
+const path = resolveSnapshotPath(process.cwd(), ".outfitter", "v1.0.0");
+await writeSurfaceMap(surface, path);
+```
+
+### 3) Detect schema drift in CI
+
+```typescript
+import { generateSurfaceMap, readSurfaceMap } from "@outfitter/schema/surface";
+import { diffSurfaceMaps } from "@outfitter/schema/diff";
+
+const committed = await readSurfaceMap(".outfitter/snapshots/v1.0.0.json");
+const current = generateSurfaceMap(registry, { version: "1.0.0" });
+
+const diff = diffSurfaceMaps(committed, current);
+if (diff.hasChanges) {
+  console.error("Surface drift detected", diff);
+  process.exit(1);
+}
+```
+
+### 4) Generate markdown reference docs
+
+```typescript
+import { formatManifestMarkdown } from "@outfitter/schema/markdown";
+
+const manifest = generateManifest(registry, { surface: "mcp", version: "1.0.0" });
+
+const markdown = formatManifestMarkdown(manifest, {
+  surface: "mcp",
+  title: "MCP Tool Reference",
+  toc: true,
+  timestamp: false,
+});
+
+await Bun.write("docs/reference/tools.md", markdown);
+```
+
+## API Notes
+
+- `generateManifest()` accepts either an `ActionRegistry` or a plain array of action specs.
+- `generateSurfaceMap()` wraps manifest output with envelope metadata (`$schema`, `generator`).
+- `diffSurfaceMaps()` ignores volatile timestamps and reports granular change categories (`input`, `output`, `surfaces`, `cli`, `mcp`, `api`, metadata changes).
+- `formatManifestMarkdown()` renders either MCP-tool docs or CLI-command docs from the same manifest source.
+
+## License
+
+MIT

package/dist/diff.d.ts

@@ -0,0 +1,4 @@
+import { DiffEntry, ModifiedEntry, SurfaceMapDiff, diffSurfaceMaps } from "./shared/@outfitter/schema-qm3b0skz";
+import "./shared/@outfitter/schema-wgnvy5zh";
+import "./shared/@outfitter/schema-vzq7nzs3";
+export { diffSurfaceMaps, SurfaceMapDiff, ModifiedEntry, DiffEntry };

package/dist/diff.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  diffSurfaceMaps
+} from "./shared/@outfitter/schema-d4xhpz76.js";
+export {
+  diffSurfaceMaps
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { DiffEntry, ModifiedEntry, SurfaceMapDiff, diffSurfaceMaps } from "./shared/@outfitter/schema-qm3b0skz";
+import { GenerateSurfaceMapOptions, SurfaceMap, generateSurfaceMap, readSurfaceMap, resolveSnapshotPath, writeSurfaceMap } from "./shared/@outfitter/schema-wgnvy5zh";
+import { MarkdownFormatOptions, formatManifestMarkdown } from "./shared/@outfitter/schema-xqcdyq2s";
+import { ActionManifest, ActionManifestEntry, ActionSource, GenerateManifestOptions, ManifestApiSpec, ManifestCliOption, ManifestCliSpec, ManifestMcpSpec, generateManifest } from "./shared/@outfitter/schema-vzq7nzs3";
+export { writeSurfaceMap, resolveSnapshotPath, readSurfaceMap, generateSurfaceMap, generateManifest, formatManifestMarkdown, diffSurfaceMaps, SurfaceMapDiff, SurfaceMap, ModifiedEntry, MarkdownFormatOptions, ManifestMcpSpec, ManifestCliSpec, ManifestCliOption, ManifestApiSpec, GenerateSurfaceMapOptions, GenerateManifestOptions, DiffEntry, ActionSource, ActionManifestEntry, ActionManifest };

package/dist/index.js

@@ -0,0 +1,25 @@
+// @bun
+import {
+  generateSurfaceMap,
+  readSurfaceMap,
+  resolveSnapshotPath,
+  writeSurfaceMap
+} from "./shared/@outfitter/schema-cq7f2r5z.js";
+import {
+  diffSurfaceMaps
+} from "./shared/@outfitter/schema-d4xhpz76.js";
+import {
+  formatManifestMarkdown
+} from "./shared/@outfitter/schema-y9k7tad6.js";
+import {
+  generateManifest
+} from "./shared/@outfitter/schema-tnrxpckr.js";
+export {
+  writeSurfaceMap,
+  resolveSnapshotPath,
+  readSurfaceMap,
+  generateSurfaceMap,
+  generateManifest,
+  formatManifestMarkdown,
+  diffSurfaceMaps
+};

package/dist/manifest.d.ts

@@ -0,0 +1,2 @@
+import { ActionManifest, ActionManifestEntry, ActionSource, GenerateManifestOptions, ManifestApiSpec, ManifestCliOption, ManifestCliSpec, ManifestMcpSpec, generateManifest } from "./shared/@outfitter/schema-vzq7nzs3";
+export { generateManifest, ManifestMcpSpec, ManifestCliSpec, ManifestCliOption, ManifestApiSpec, GenerateManifestOptions, ActionSource, ActionManifestEntry, ActionManifest };

package/dist/manifest.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  generateManifest
+} from "./shared/@outfitter/schema-tnrxpckr.js";
+export {
+  generateManifest
+};

package/dist/markdown.d.ts

@@ -0,0 +1,3 @@
+import { MarkdownFormatOptions, formatManifestMarkdown } from "./shared/@outfitter/schema-xqcdyq2s";
+import "./shared/@outfitter/schema-vzq7nzs3";
+export { formatManifestMarkdown, MarkdownFormatOptions };

package/dist/markdown.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  formatManifestMarkdown
+} from "./shared/@outfitter/schema-y9k7tad6.js";
+export {
+  formatManifestMarkdown
+};

package/dist/shared/@outfitter/schema-cq7f2r5z.js

@@ -0,0 +1,32 @@
+// @bun
+import {
+  generateManifest
+} from "./schema-tnrxpckr.js";
+
+// packages/schema/src/surface.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+var SURFACE_MAP_SCHEMA = "https://outfitter.dev/surface/v1";
+function generateSurfaceMap(source, options) {
+  const manifest = generateManifest(source, options);
+  return {
+    ...manifest,
+    $schema: SURFACE_MAP_SCHEMA,
+    generator: options?.generator ?? "runtime"
+  };
+}
+async function writeSurfaceMap(surfaceMap, outputPath) {
+  await mkdir(dirname(outputPath), { recursive: true });
+  const content = `${JSON.stringify(surfaceMap, null, 2)}
+`;
+  await writeFile(outputPath, content, "utf-8");
+}
+async function readSurfaceMap(inputPath) {
+  const content = await readFile(inputPath, "utf-8");
+  return JSON.parse(content);
+}
+function resolveSnapshotPath(cwd, outputDir, version) {
+  return join(cwd, outputDir, "snapshots", `${version}.json`);
+}
+
+export { generateSurfaceMap, writeSurfaceMap, readSurfaceMap, resolveSnapshotPath };

package/dist/shared/@outfitter/schema-d4xhpz76.js

@@ -0,0 +1,91 @@
+// @bun
+// packages/schema/src/diff.ts
+function stableJson(value) {
+  return JSON.stringify(value, (_key, val) => {
+    if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+      const sorted = {};
+      for (const k of Object.keys(val).sort()) {
+        sorted[k] = val[k];
+      }
+      return sorted;
+    }
+    return val;
+  });
+}
+function compareEntries(committed, current) {
+  const changes = [];
+  if (stableJson(committed.input) !== stableJson(current.input)) {
+    changes.push("input");
+  }
+  if (stableJson(committed.output) !== stableJson(current.output)) {
+    changes.push("output");
+  }
+  if (JSON.stringify([...committed.surfaces].sort()) !== JSON.stringify([...current.surfaces].sort())) {
+    changes.push("surfaces");
+  }
+  if (committed.description !== current.description) {
+    changes.push("description");
+  }
+  if (stableJson(committed.cli) !== stableJson(current.cli)) {
+    changes.push("cli");
+  }
+  if (stableJson(committed.mcp) !== stableJson(current.mcp)) {
+    changes.push("mcp");
+  }
+  if (stableJson(committed.api) !== stableJson(current.api)) {
+    changes.push("api");
+  }
+  return changes;
+}
+function diffSurfaceMaps(committed, current) {
+  const metadataChanges = [];
+  if (committed.version !== current.version) {
+    metadataChanges.push("version");
+  }
+  if (JSON.stringify([...committed.surfaces].sort()) !== JSON.stringify([...current.surfaces].sort())) {
+    metadataChanges.push("surfaces");
+  }
+  if (stableJson(committed.errors) !== stableJson(current.errors)) {
+    metadataChanges.push("errors");
+  }
+  if (stableJson(committed.outputModes) !== stableJson(current.outputModes)) {
+    metadataChanges.push("outputModes");
+  }
+  if ("$schema" in committed && "$schema" in current && committed.$schema !== current.$schema) {
+    metadataChanges.push("$schema");
+  }
+  const committedMap = new Map(committed.actions.map((a) => [a.id, a]));
+  const currentMap = new Map(current.actions.map((a) => [a.id, a]));
+  const added = [];
+  const removed = [];
+  const modified = [];
+  for (const [id] of currentMap) {
+    if (!committedMap.has(id)) {
+      added.push({ id });
+    }
+  }
+  for (const [id] of committedMap) {
+    if (!currentMap.has(id)) {
+      removed.push({ id });
+    }
+  }
+  for (const [id, committedEntry] of committedMap) {
+    const currentEntry = currentMap.get(id);
+    if (!currentEntry) {
+      continue;
+    }
+    const changes = compareEntries(committedEntry, currentEntry);
+    if (changes.length > 0) {
+      modified.push({ id, changes });
+    }
+  }
+  return {
+    hasChanges: added.length > 0 || removed.length > 0 || modified.length > 0 || metadataChanges.length > 0,
+    added,
+    removed,
+    modified,
+    metadataChanges
+  };
+}
+
+export { diffSurfaceMaps };

package/dist/shared/@outfitter/schema-qm3b0skz.d.ts

@@ -0,0 +1,26 @@
+import { SurfaceMap } from "./schema-wgnvy5zh";
+interface SurfaceMapDiff {
+	readonly hasChanges: boolean;
+	readonly added: readonly DiffEntry[];
+	readonly removed: readonly DiffEntry[];
+	readonly modified: readonly ModifiedEntry[];
+	readonly metadataChanges: readonly string[];
+}
+interface DiffEntry {
+	readonly id: string;
+}
+interface ModifiedEntry extends DiffEntry {
+	readonly changes: readonly string[];
+}
+/**
+* Compare two surface maps and return a structured diff.
+*
+* Ignores volatile fields like `generatedAt`. Reports added, removed,
+* and modified actions with specific change categories.
+*
+* @param committed - The previously committed surface map
+* @param current - The current runtime surface map
+* @returns Structured diff result
+*/
+declare function diffSurfaceMaps(committed: SurfaceMap, current: SurfaceMap): SurfaceMapDiff;
+export { SurfaceMapDiff, DiffEntry, ModifiedEntry, diffSurfaceMaps };

package/dist/shared/@outfitter/schema-tnrxpckr.js

@@ -0,0 +1,85 @@
+// @bun
+// packages/schema/src/manifest.ts
+import {
+  ACTION_SURFACES,
+  DEFAULT_REGISTRY_SURFACES,
+  exitCodeMap,
+  statusCodeMap,
+  zodToJsonSchema
+} from "@outfitter/contracts";
+function isActionRegistry(source) {
+  return "list" in source && typeof source.list === "function";
+}
+var OUTPUT_MODES = ["human", "json", "jsonl", "tree", "table"];
+function buildErrorTaxonomy() {
+  const taxonomy = {};
+  for (const category of Object.keys(exitCodeMap)) {
+    taxonomy[category] = {
+      exit: exitCodeMap[category],
+      http: statusCodeMap[category]
+    };
+  }
+  return taxonomy;
+}
+function actionToManifestEntry(action) {
+  const surfaces = [
+    ...action.surfaces ?? DEFAULT_REGISTRY_SURFACES
+  ];
+  return {
+    id: action.id,
+    description: action.description,
+    surfaces,
+    input: zodToJsonSchema(action.input),
+    output: action.output ? zodToJsonSchema(action.output) : undefined,
+    cli: action.cli ? {
+      group: action.cli.group,
+      command: action.cli.command,
+      description: action.cli.description,
+      aliases: action.cli.aliases && action.cli.aliases.length > 0 ? action.cli.aliases : undefined,
+      options: action.cli.options && action.cli.options.length > 0 ? action.cli.options.map((o) => ({
+        flags: o.flags,
+        description: o.description,
+        defaultValue: o.defaultValue,
+        required: o.required
+      })) : undefined
+    } : undefined,
+    mcp: action.mcp ? {
+      tool: action.mcp.tool,
+      description: action.mcp.description,
+      deferLoading: action.mcp.deferLoading
+    } : undefined,
+    api: action.api ? {
+      method: action.api.method,
+      path: action.api.path,
+      tags: action.api.tags
+    } : undefined
+  };
+}
+function generateManifest(source, options) {
+  let actions = isActionRegistry(source) ? source.list() : [...source];
+  if (options?.surface) {
+    const surface = options.surface;
+    actions = actions.filter((action) => {
+      const surfaces = action.surfaces ?? DEFAULT_REGISTRY_SURFACES;
+      return surfaces.includes(surface);
+    });
+  }
+  const surfaceSet = new Set;
+  for (const action of actions) {
+    for (const s of action.surfaces ?? DEFAULT_REGISTRY_SURFACES) {
+      if (ACTION_SURFACES.includes(s)) {
+        surfaceSet.add(s);
+      }
+    }
+  }
+  return {
+    version: options?.version ?? "1.0.0",
+    generatedAt: new Date().toISOString(),
+    surfaces: [...surfaceSet].sort(),
+    actions: actions.map(actionToManifestEntry),
+    errors: buildErrorTaxonomy(),
+    outputModes: [...OUTPUT_MODES]
+  };
+}
+
+export { generateManifest };

package/dist/shared/@outfitter/schema-vzq7nzs3.d.ts

@@ -0,0 +1,59 @@
+import { ActionRegistry, ActionSurface, AnyActionSpec, ErrorCategory, JsonSchema } from "@outfitter/contracts";
+interface ActionManifest {
+	readonly version: string;
+	readonly generatedAt: string;
+	readonly surfaces: ActionSurface[];
+	readonly actions: ActionManifestEntry[];
+	readonly errors: Record<ErrorCategory, {
+		exit: number;
+		http: number;
+	}>;
+	readonly outputModes: string[];
+}
+interface ActionManifestEntry {
+	readonly id: string;
+	readonly description?: string | undefined;
+	readonly surfaces: ActionSurface[];
+	readonly input: JsonSchema;
+	readonly output?: JsonSchema | undefined;
+	readonly cli?: ManifestCliSpec | undefined;
+	readonly mcp?: ManifestMcpSpec | undefined;
+	readonly api?: ManifestApiSpec | undefined;
+}
+interface ManifestCliSpec {
+	readonly group?: string | undefined;
+	readonly command?: string | undefined;
+	readonly description?: string | undefined;
+	readonly aliases?: readonly string[] | undefined;
+	readonly options?: readonly ManifestCliOption[] | undefined;
+}
+interface ManifestCliOption {
+	readonly flags: string;
+	readonly description: string;
+	readonly defaultValue?: string | boolean | string[] | undefined;
+	readonly required?: boolean | undefined;
+}
+interface ManifestMcpSpec {
+	readonly tool?: string | undefined;
+	readonly description?: string | undefined;
+	readonly deferLoading?: boolean | undefined;
+}
+interface ManifestApiSpec {
+	readonly method?: string | undefined;
+	readonly path?: string | undefined;
+	readonly tags?: readonly string[] | undefined;
+}
+interface GenerateManifestOptions {
+	readonly surface?: ActionSurface;
+	readonly version?: string;
+}
+type ActionSource = ActionRegistry | readonly AnyActionSpec[];
+/**
+* Generate a manifest from an action registry or action array.
+*
+* @param source - ActionRegistry or array of ActionSpec
+* @param options - Filtering and version options
+* @returns The manifest object
+*/
+declare function generateManifest(source: ActionSource, options?: GenerateManifestOptions): ActionManifest;
+export { ActionManifest, ActionManifestEntry, ManifestCliSpec, ManifestCliOption, ManifestMcpSpec, ManifestApiSpec, GenerateManifestOptions, ActionSource, generateManifest };

package/dist/shared/@outfitter/schema-wgnvy5zh.d.ts

@@ -0,0 +1,44 @@
+import { ActionManifest, ActionSource, GenerateManifestOptions } from "./schema-vzq7nzs3";
+interface SurfaceMap extends ActionManifest {
+	readonly $schema: string;
+	readonly generator: "runtime" | "build";
+}
+interface GenerateSurfaceMapOptions extends GenerateManifestOptions {
+	readonly generator?: "runtime" | "build";
+}
+/**
+* Generate a surface map from an action registry or action array.
+*
+* Wraps `generateManifest()` with envelope metadata (`$schema`, `generator`).
+*
+* @param source - ActionRegistry or array of ActionSpec
+* @param options - Filtering, version, and generator options
+* @returns The surface map object
+*/
+declare function generateSurfaceMap(source: ActionSource, options?: GenerateSurfaceMapOptions): SurfaceMap;
+/**
+* Write a surface map to disk as pretty-printed JSON.
+*
+* Creates parent directories if they don't exist.
+*
+* @param surfaceMap - The surface map to write
+* @param outputPath - Absolute path for the output file
+*/
+declare function writeSurfaceMap(surfaceMap: SurfaceMap, outputPath: string): Promise<void>;
+/**
+* Read a surface map from disk.
+*
+* @param inputPath - Absolute path to the surface map file
+* @returns The parsed surface map
+*/
+declare function readSurfaceMap(inputPath: string): Promise<SurfaceMap>;
+/**
+* Resolve the file path for a named snapshot.
+*
+* @param cwd - Project root directory
+* @param outputDir - Output directory name (e.g., ".outfitter")
+* @param version - Snapshot version label
+* @returns Absolute path to the snapshot file
+*/
+declare function resolveSnapshotPath(cwd: string, outputDir: string, version: string): string;
+export { SurfaceMap, GenerateSurfaceMapOptions, generateSurfaceMap, writeSurfaceMap, readSurfaceMap, resolveSnapshotPath };

package/dist/shared/@outfitter/schema-xqcdyq2s.d.ts

@@ -0,0 +1,21 @@
+import { ActionManifest } from "./schema-vzq7nzs3";
+type DocSurface = "mcp" | "cli";
+interface MarkdownFormatOptions {
+	/** Which surface to document. Default: "mcp" */
+	readonly surface?: DocSurface;
+	/** Document title. Default: surface-specific (e.g., "MCP Tools Reference") */
+	readonly title?: string;
+	/** Include table of contents. Default: true when 2+ entries */
+	readonly toc?: boolean;
+	/** Include generated timestamp. Default: true */
+	readonly timestamp?: boolean;
+}
+/**
+* Format an action manifest as a markdown reference document.
+*
+* @param manifest - The manifest to format
+* @param options - Formatting options
+* @returns Formatted markdown string
+*/
+declare function formatManifestMarkdown(manifest: ActionManifest, options?: MarkdownFormatOptions): string;
+export { MarkdownFormatOptions, formatManifestMarkdown };

package/dist/shared/@outfitter/schema-y9k7tad6.js

@@ -0,0 +1,180 @@
+// @bun
+// packages/schema/src/markdown.ts
+var DEFAULT_TITLES = {
+  mcp: "MCP Tools Reference",
+  cli: "CLI Reference"
+};
+function formatManifestMarkdown(manifest, options) {
+  const surface = options?.surface ?? "mcp";
+  const title = options?.title ?? DEFAULT_TITLES[surface];
+  const showTimestamp = options?.timestamp ?? true;
+  const sections = [];
+  sections.push(renderHeader(title, manifest.version, showTimestamp ? manifest.generatedAt : undefined));
+  const sorted = manifest.actions.filter((action) => action.surfaces.includes(surface)).sort((a, b) => {
+    const nameA = displayName(a, surface);
+    const nameB = displayName(b, surface);
+    return nameA.localeCompare(nameB);
+  });
+  if (sorted.length === 0) {
+    sections.push("_No tools registered._");
+    return sections.join(`
+
+`);
+  }
+  const showToc = options?.toc ?? sorted.length >= 2;
+  if (showToc) {
+    sections.push(renderToc(sorted, surface));
+  }
+  for (const action of sorted) {
+    sections.push(surface === "cli" ? renderCliCommand(action) : renderMcpTool(action));
+  }
+  return `${sections.join(`
+
+---
+
+`)}
+`;
+}
+function renderHeader(title, version, generatedAt) {
+  const lines = [];
+  lines.push(`# ${title}`);
+  const meta = [];
+  meta.push(`schema v${version}`);
+  if (generatedAt) {
+    meta.push(generatedAt);
+  }
+  lines.push("");
+  lines.push(`> Generated from ${meta.join(" | ")}`);
+  return lines.join(`
+`);
+}
+function renderToc(actions, surface) {
+  const lines = [];
+  lines.push("## Table of Contents");
+  lines.push("");
+  for (const action of actions) {
+    const name = displayName(action, surface);
+    lines.push(`- [${name}](#${slugify(name)})`);
+  }
+  return lines.join(`
+`);
+}
+function renderMcpTool(action) {
+  const name = displayName(action, "mcp");
+  const desc = action.mcp?.description ?? action.description;
+  const lines = [];
+  lines.push(`## ${name}`);
+  lines.push("");
+  if (desc) {
+    lines.push(desc);
+  }
+  if (action.mcp?.deferLoading) {
+    lines.push("");
+    lines.push("> Deferred loading: must be explicitly loaded before use.");
+  }
+  lines.push("");
+  lines.push("### Parameters");
+  lines.push("");
+  lines.push(renderSchemaTable(action.input));
+  return lines.join(`
+`);
+}
+function renderCliCommand(action) {
+  const name = displayName(action, "cli");
+  const desc = action.cli?.description ?? action.description;
+  const lines = [];
+  lines.push(`## ${name}`);
+  lines.push("");
+  if (desc) {
+    lines.push(desc);
+  }
+  if (action.cli?.aliases && action.cli.aliases.length > 0) {
+    lines.push("");
+    const aliasStr = action.cli.aliases.map((a) => `\`${a}\``).join(", ");
+    lines.push(`**Aliases:** ${aliasStr}`);
+  }
+  lines.push("");
+  lines.push("### Options");
+  lines.push("");
+  lines.push(renderCliOptionsTable(action.cli));
+  return lines.join(`
+`);
+}
+function renderCliOptionsTable(cli) {
+  const options = cli?.options;
+  if (!options || options.length === 0) {
+    return "_No options._";
+  }
+  const lines = [];
+  lines.push("| Flag | Description | Default |");
+  lines.push("|------|-------------|---------|");
+  for (const opt of options) {
+    const defaultStr = opt.defaultValue !== undefined ? `\`${JSON.stringify(opt.defaultValue)}\`` : "\u2014";
+    lines.push(`| \`${escapeMarkdown(opt.flags)}\` | ${escapeMarkdown(opt.description)} | ${defaultStr} |`);
+  }
+  return lines.join(`
+`);
+}
+function renderSchemaTable(schema) {
+  const properties = schema.properties;
+  if (!properties || Object.keys(properties).length === 0) {
+    return "_No parameters._";
+  }
+  const required = new Set(schema.required ?? []);
+  const lines = [];
+  lines.push("| Property | Type | Required | Description |");
+  lines.push("|----------|------|----------|-------------|");
+  for (const [key, prop] of Object.entries(properties)) {
+    const typeStr = formatType(prop);
+    const isRequired = required.has(key) ? "Yes" : "No";
+    const descParts = [];
+    if (prop.description) {
+      descParts.push(escapeMarkdown(prop.description));
+    }
+    if (prop.default !== undefined) {
+      descParts.push(`(default: \`${JSON.stringify(prop.default)}\`)`);
+    }
+    const desc = descParts.join(" ");
+    lines.push(`| \`${key}\` | ${typeStr} | ${isRequired} | ${desc} |`);
+  }
+  return lines.join(`
+`);
+}
+function formatType(schema) {
+  if (schema.enum) {
+    return schema.enum.map((v) => `\`${JSON.stringify(v)}\``).join(" \\| ");
+  }
+  if (schema.anyOf) {
+    return schema.anyOf.map(formatType).join(" \\| ");
+  }
+  if (schema.oneOf) {
+    return schema.oneOf.map(formatType).join(" \\| ");
+  }
+  if (schema.type === "array") {
+    const items = schema.items;
+    if (items && !Array.isArray(items) && items.type) {
+      return `array of ${items.type}`;
+    }
+    return "array";
+  }
+  return schema.type ?? "unknown";
+}
+function escapeMarkdown(text) {
+  return text.replace(/\|/g, "\\|");
+}
+function slugify(text) {
+  return text.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-");
+}
+function displayName(action, surface) {
+  if (surface === "cli") {
+    const cli = action.cli;
+    if (!cli)
+      return action.id;
+    const group = cli.group;
+    const command = cli.command ?? action.id;
+    return group ? `${group} ${command}` : command;
+  }
+  return action.mcp?.tool ?? action.id;
+}
+
+export { formatManifestMarkdown };

package/dist/surface.d.ts

@@ -0,0 +1,3 @@
+import { GenerateSurfaceMapOptions, SurfaceMap, generateSurfaceMap, readSurfaceMap, resolveSnapshotPath, writeSurfaceMap } from "./shared/@outfitter/schema-wgnvy5zh";
+import "./shared/@outfitter/schema-vzq7nzs3";
+export { writeSurfaceMap, resolveSnapshotPath, readSurfaceMap, generateSurfaceMap, SurfaceMap, GenerateSurfaceMapOptions };

package/dist/surface.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  generateSurfaceMap,
+  readSurfaceMap,
+  resolveSnapshotPath,
+  writeSurfaceMap
+} from "./shared/@outfitter/schema-cq7f2r5z.js";
+import"./shared/@outfitter/schema-tnrxpckr.js";
+export {
+  writeSurfaceMap,
+  resolveSnapshotPath,
+  readSurfaceMap,
+  generateSurfaceMap
+};

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@outfitter/schema",
+  "description": "Schema introspection, surface map generation, and drift detection for Outfitter",
+  "version": "0.2.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./diff": {
+      "import": {
+        "types": "./dist/diff.d.ts",
+        "default": "./dist/diff.js"
+      }
+    },
+    "./manifest": {
+      "import": {
+        "types": "./dist/manifest.d.ts",
+        "default": "./dist/manifest.js"
+      }
+    },
+    "./markdown": {
+      "import": {
+        "types": "./dist/markdown.d.ts",
+        "default": "./dist/markdown.js"
+      }
+    },
+    "./package.json": "./package.json",
+    "./surface": {
+      "import": {
+        "types": "./dist/surface.d.ts",
+        "default": "./dist/surface.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "cd ../.. && bunup --filter @outfitter/schema",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "lint": "biome lint ./src",
+    "lint:fix": "biome lint --write ./src",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@outfitter/contracts": "workspace:*",
+    "@outfitter/types": "workspace:*"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.7",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.3.7"
+  },
+  "keywords": [
+    "outfitter",
+    "schema",
+    "manifest",
+    "surface-map",
+    "introspection",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/outfitter-dev/outfitter.git",
+    "directory": "packages/schema"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}