create-stitchkit 0.2.0 → 0.3.1

package/template/_env.example

@@ -6,4 +6,4 @@ NEXT_PUBLIC_API_URL=http://127.0.0.1:3211
 INTERNAL_API_URL=http://127.0.0.1:3211
 NEXT_PUBLIC_WEB_URL=http://127.0.0.1:3210
 LOG_FORMAT=pretty
-CORS_ORIGIN=*
+CORS_ORIGIN=http://127.0.0.1:3210

package/template/bun.lock

@@ -15,8 +15,10 @@
         "@modelcontextprotocol/client": "^2.0.0",
         "@playwright/test": "^1.55.0",
         "@types/bun": "^1.3.14",
+        "@types/node": "^26.2.0",
         "oxc-parser": "^0.143.0",
         "socket.io-client": "^4.8.3",
+        "stitchkit": "catalog:",
         "typescript": "^7.0.2",
         "zod": "^4.4.3",
       },
@@ -74,7 +76,6 @@
       "version": "0.1.0",
       "dependencies": {
         "@app/config": "workspace:*",
-        "@app/db": "workspace:*",
         "@app/shared": "workspace:*",
         "@radix-ui/react-alert-dialog": "^1.1.23",
         "@radix-ui/react-avatar": "^1.2.6",
@@ -127,7 +128,6 @@
       "name": "@app/shared",
       "version": "0.1.0",
       "dependencies": {
-        "@app/db": "workspace:*",
         "stitchkit": "catalog:",
         "zod": "^4.4.3",
       },
@@ -138,7 +138,7 @@
     },
   },
   "catalog": {
-    "stitchkit": "^0.45.0",
+    "stitchkit": "^0.49.2",
   },
   "packages": {
     "@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.46", "", { "dependencies": { "@ai-sdk/provider": "4.0.7", "@ai-sdk/provider-utils": "5.0.25", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-LIAO6kAG8fpXQb9L0iwPk1FIbXftvqnyC56v5NEAzeWTeL8fUsy/Hx86VPBTWEDFdwbVprjWifJOAqS6AOj3mA=="],
@@ -1117,7 +1117,7 @@
 
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
-    "stitchkit": ["stitchkit@0.45.0", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-IYeet50iZK3J5/bPJApLfASxX1vb5KwliHvHLOwQsLx1QqIELmgeVBl3p5IbFd4sXKW0OIBPDZdtfN+xUsjT0A=="],
+    "stitchkit": ["stitchkit@0.49.2", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-QP0I//fs/khC+bTqYungjpZskAseQAB/Lm8UOx3mZDx+rmYtdsBhlAn0I0hBYE/du9jag5rE032s9HrZgT2VXg=="],
 
     "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
 

package/template/docs/ADDING_A_FEATURE.md

@@ -1,8 +1,9 @@
 # Adding a vertical feature
 
 This guide uses a small `status` resource to show the canonical path. The blank
-scaffold starts with no application surface. In `--example repository` mode,
-keep the repository slice and add the same files beside it.
+scaffold starts with only its HTTP readiness endpoint and no application or tool
+surface. In `--example repository` mode, keep the repository slice and add the
+same files beside it.
 
 ## 1. Define the wire data
 

package/template/e2e/starter.spec.ts

@@ -1,6 +1,11 @@
 import { appIdentity } from '@app/config/identity';
+import { systemContract } from '@app/shared';
 import AxeBuilder from '@axe-core/playwright';
 import { expect, test } from '@playwright/test';
+import { createClient, createHttpClient } from 'stitchkit';
+import { loadToolingEnv } from '../scripts/tooling-env';
+
+const toolingEnv = loadToolingEnv();
 
 test('renders the hydrated starter application and catalogue', async ({ page }) => {
   await page.goto('/en');
@@ -12,10 +17,19 @@ test('renders the hydrated starter application and catalogue', async ({ page })
   await expect(page.getByRole('heading', { level: 1 })).toContainText('UI components');
 });
 
-test('publishes complete page metadata and a reachable Open Graph card', async ({
-  page,
-  request,
-}) => {
+test('calls the live backend through the typed contract client', async () => {
+  const client = createClient(
+    systemContract,
+    createHttpClient({
+      baseUrl: `${toolingEnv.NEXT_PUBLIC_API_URL}/api`,
+      credentials: 'omit',
+    }),
+  );
+
+  await expect(client.status()).resolves.toEqual({ status: 'ok' });
+});
+
+test('publishes complete page metadata', async ({ page }) => {
   await page.goto('/en/ui/themes');
   await expect(page).toHaveTitle(`Theme system · ${appIdentity.name}`);
   await expect(page.locator('link[rel="canonical"]')).toHaveAttribute(
@@ -28,15 +42,9 @@ test('publishes complete page metadata and a reachable Open Graph card', async (
   );
 
   const imageUrl = await page.locator('meta[property="og:image"]').getAttribute('content');
-  expect(imageUrl).not.toBeNull();
-  if (!imageUrl) throw new Error('Open Graph image URL is missing');
-  const imageResponse = await request.get(imageUrl);
-  expect(imageResponse.status()).toBe(200);
-  expect(imageResponse.headers()['content-type']).toContain('image/png');
-
-  const sitemapResponse = await request.get('/sitemap.xml');
-  expect(sitemapResponse.status()).toBe(200);
-  expect(await sitemapResponse.text()).toContain('/ru/ui/themes');
+  expect(imageUrl).toBe(
+    new URL('/api/og/en/themes', toolingEnv.NEXT_PUBLIC_WEB_URL).toString(),
+  );
 });
 
 test('switches catalogue sections and component tabs', async ({ page }) => {

package/template/ecosystem.dev.config.cjs

@@ -5,18 +5,6 @@ const identity = require('./app.config.json');
 config({ path: path.join(__dirname, '.env'), quiet: true });
 
 const frontendArgs = ['dev', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'];
-if (process.env.DEV_HTTPS_CERT && process.env.DEV_HTTPS_KEY) {
-  frontendArgs.push(
-    '--experimental-https',
-    '--experimental-https-key',
-    process.env.DEV_HTTPS_KEY,
-    '--experimental-https-cert',
-    process.env.DEV_HTTPS_CERT,
-  );
-  if (process.env.DEV_HTTPS_CA) {
-    frontendArgs.push('--experimental-https-ca', process.env.DEV_HTTPS_CA);
-  }
-}
 
 module.exports = {
   apps: [

package/template/package.json

@@ -7,12 +7,11 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.45.0"
+    "stitchkit": "^0.49.2"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",
-    "dev:lan": "bun scripts/dev-lan.ts",
-    "check": "bun run db:generate && bun run check:authored && bun run --filter '*' check",
+    "check": "bun run db:generate && bun run check:authored && bun x tsc -p tsconfig.json --noEmit && bun run --filter '*' check",
     "check:authored": "bun scripts/check-authored.ts",
     "test": "bun run --filter '*' test",
     "build": "bun run db:generate && bun --filter @app/backend build && bun --filter @app/frontend build",
@@ -27,6 +26,7 @@
     "cli": "bun packages/backend/src/cli.ts",
     "tools": "bun packages/backend/src/tools.ts",
     "runtime:smoke": "bun scripts/runtime-smoke.ts",
+    "surface:snapshot": "bun scripts/surface-snapshot.ts",
     "e2e": "playwright test",
     "lint": "biome check --error-on-warnings .",
     "lint:fix": "biome check --write .",
@@ -44,8 +44,10 @@
     "@modelcontextprotocol/client": "^2.0.0",
     "@playwright/test": "^1.55.0",
     "@types/bun": "^1.3.14",
+    "@types/node": "^26.2.0",
     "oxc-parser": "^0.143.0",
     "socket.io-client": "^4.8.3",
+    "stitchkit": "catalog:",
     "typescript": "^7.0.2",
     "zod": "^4.4.3"
   },

package/template/packages/backend/src/cli.ts

@@ -9,5 +9,5 @@ const { services, socket } = await createSurface();
 try {
   await createCli({ name: appIdentity.slug, version: appIdentity.version, services });
 } finally {
-  await socket.io.close();
+  await socket.close();
 }

package/template/packages/backend/src/index.ts

@@ -6,7 +6,6 @@ import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools';
 import { prisma } from './lib/db';
 import { createSurface } from './surface';
 import { onError } from './transport/errors';
-import { createLanOnboardingRoutes } from './transport/lan-onboarding';
 
 async function main(): Promise<void> {
   const { services, socket } = await createSurface();
@@ -27,12 +26,10 @@ async function main(): Promise<void> {
     cors: { origin: env.CORS_ORIGIN },
     hooks: { onError },
     logging: { format: env.LOG_FORMAT },
-    websocket: socket.websocket,
+    socket,
     rawRoutes: [
-      socket.route,
       openApiRoute('/openapi.json', openApi),
       createMcpHttpRoute({ path: '/mcp', handler: mcp }),
-      ...createLanOnboardingRoutes(),
       {
         method: 'GET',
         path: '/health',
@@ -40,30 +37,36 @@ async function main(): Promise<void> {
       },
     ],
     wrapFetch: (fetch) => wrapInRequestContext(fetch),
-    bun:
-      env.DEV_HTTPS_CERT && env.DEV_HTTPS_KEY
-        ? {
-            tls: {
-              cert: Bun.file(env.DEV_HTTPS_CERT),
-              key: Bun.file(env.DEV_HTTPS_KEY),
-              ...(env.DEV_HTTPS_CA && { ca: Bun.file(env.DEV_HTTPS_CA) }),
-            },
-          }
-        : undefined,
   });
 
-  async function shutdown(): Promise<void> {
-    server.stop();
-    await mcp.close();
-    await socket.io.close();
-    await prisma.$disconnect();
+  const shutdownController = new AbortController();
+  let shutdownPromise: Promise<void> | undefined;
+
+  function shutdown(): Promise<void> {
+    if (shutdownPromise) {
+      shutdownController.abort();
+      return shutdownPromise;
+    }
+
+    shutdownPromise = (async () => {
+      await server.shutdown({
+        gracePeriodMs: 30_000,
+        signal: shutdownController.signal,
+      });
+      await mcp.close();
+      await prisma.$disconnect();
+    })();
+    return shutdownPromise;
   }
 
-  process.once('SIGTERM', shutdown);
-  process.once('SIGINT', shutdown);
-  console.log(
-    `API listening on ${env.DEV_HTTPS_CERT ? 'https' : 'http'}://127.0.0.1:${env.API_PORT}`,
-  );
+  const onSignal = () =>
+    void shutdown().catch((error: unknown) => {
+      console.error('Shutdown failed', error);
+    });
+
+  process.on('SIGTERM', onSignal);
+  process.on('SIGINT', onSignal);
+  console.log(`API listening on http://127.0.0.1:${env.API_PORT}`);
 }
 
 main().catch((error: unknown) => {

package/template/packages/backend/src/surface-manifest.test.ts

@@ -1,19 +1,35 @@
 import { describe, expect, test } from 'bun:test';
-import { defineContract } from 'stitchkit/contract';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createContractFactory } from 'stitchkit/contract';
 import { generateOpenApiDocument, implement } from 'stitchkit/server';
 import { z } from 'zod';
-import { assertSurfaceConformance, buildSurfaceManifest } from './surface-manifest';
+import { discoverCliCommands, discoverMcpTools } from '../../../scripts/surface-conformance';
+import {
+  assertManifestMatchesSnapshot,
+  assertSurfaceConformance,
+  buildSurfaceManifest,
+} from './surface-manifest';
+
+const NoteParamsSchema = z.object({ id: z.string() });
+const NoteSchema = z.object({ id: z.string() });
+// Same address and presence flags as NoteSchema — a different TYPE, for the
+// snapshot-digest test. Named here, never inline in a contract (the template's
+// own schema-separate-from-contract policy).
+const RetypedNoteSchema = z.object({ id: z.number() });
+const { defineContract } = createContractFactory<'public'>();
 
 const service = implement(
   defineContract(
-    { prefix: 'notes' },
+    { prefix: 'notes', scope: 'public' },
     {
       read: {
         method: 'GET',
         path: '/:id',
         desc: 'Read a note',
-        params: z.object({ id: z.string() }),
-        output: z.object({ id: z.string() }),
+        params: NoteParamsSchema,
+        output: NoteSchema,
+        expose: ['HTTP', 'MCP', 'AGENT', 'CLI'],
       },
     },
   ),
@@ -31,32 +47,191 @@ describe('surface conformance', () => {
       {
         service: 'notes',
         action: 'read',
+        scope: 'public',
+        hasInput: false,
+        hasOutput: true,
+        inputShape: null,
+        outputShape: expect.stringMatching(/^[0-9a-f]{16}$/),
         http: [{ method: 'GET', path: '/api/notes/{id}' }],
-        tools: { AGENT: 'read_note', MCP: 'read_note' },
+        tools: { AGENT: 'read_note', CLI: 'read_note', MCP: 'read_note' },
       },
     ]);
     expect(() =>
-      assertSurfaceConformance({ manifest, openApi, mcpToolNames: ['read_note'] }),
+      assertSurfaceConformance({
+        manifest,
+        openApi,
+        mcpToolNames: ['read_note'],
+        agentToolNames: ['read_note'],
+        cliToolNames: ['read_note'],
+      }),
     ).not.toThrow();
   });
 
   test('fails with transport-specific expected and actual diagnostics', () => {
     const manifest = buildSurfaceManifest([service]);
     expect(() =>
-      assertSurfaceConformance({ manifest, openApi: { paths: {} }, mcpToolNames: [] }),
+      assertSurfaceConformance({
+        manifest,
+        openApi: { paths: {} },
+        mcpToolNames: [],
+        agentToolNames: [],
+        cliToolNames: [],
+      }),
     ).toThrow('HTTP/OpenAPI surface mismatch');
     expect(() =>
       assertSurfaceConformance({
         manifest: manifest.map((operation) => ({ ...operation, http: [] })),
         openApi: { paths: {} },
         mcpToolNames: ['unexpected'],
+        agentToolNames: ['read_note'],
+        cliToolNames: ['read_note'],
       }),
     ).toThrow('MCP discovery surface mismatch');
   });
 
+  test('missing Stitchkit metadata is an ERROR unless the standard-document mode is declared', () => {
+    const manifest = buildSurfaceManifest([service]);
+    const standardDocument = {
+      paths: {
+        '/api/notes/{id}': {
+          get: { responses: { 200: { description: 'Success' } } },
+        },
+      },
+    };
+    const names = {
+      mcpToolNames: ['read_note'],
+      agentToolNames: ['read_note'],
+      cliToolNames: ['read_note'],
+    };
+    // A silent skip was the hole: no x-stitchkit-* keys meant no comparison at
+    // all. The default mode now refuses; opting out is an explicit decision.
+    expect(() =>
+      assertSurfaceConformance({ manifest, openApi: standardDocument, ...names }),
+    ).toThrow(/no x-stitchkit-\* contract metadata/);
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi: standardDocument,
+        ...names,
+        metadata: 'ignore',
+      }),
+    ).not.toThrow();
+  });
+
+  test('a missing AGENT tool and a missing CLI command each fail conformance', () => {
+    const manifest = buildSurfaceManifest([service]);
+    const openApi = generateOpenApiDocument({
+      info: { title: 'Test', version: '1.0.0' },
+      groups: [{ pathPrefix: '/api', services: [service] }],
+    });
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi,
+        mcpToolNames: ['read_note'],
+        agentToolNames: [],
+        cliToolNames: ['read_note'],
+      }),
+    ).toThrow('AGENT mount surface mismatch');
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi,
+        mcpToolNames: ['read_note'],
+        agentToolNames: ['read_note'],
+        cliToolNames: [],
+      }),
+    ).toThrow('CLI manifest surface mismatch');
+  });
+
+  test('the committed snapshot catches an expose edit that moves BOTH in-process sides together', () => {
+    // The probe that defeated the old check: removing AGENT/CLI from `expose`
+    // changes the manifest AND the in-process tool lists in lockstep. The
+    // snapshot is the anchor that does not move with the source.
+    const snapshot = buildSurfaceManifest([service]);
+    const narrowed = implement(
+      defineContract(
+        { prefix: 'notes', scope: 'public' },
+        {
+          read: {
+            method: 'GET',
+            path: '/:id',
+            desc: 'Read a note',
+            params: NoteParamsSchema,
+            output: NoteSchema,
+            expose: ['HTTP', 'MCP'],
+          },
+        },
+      ),
+      { read: ({ params }) => ({ id: params.id }) },
+    );
+    expect(() =>
+      assertManifestMatchesSnapshot(buildSurfaceManifest([narrowed]), snapshot),
+    ).toThrow(/diverged from the committed snapshot/);
+    expect(() =>
+      assertManifestMatchesSnapshot(buildSurfaceManifest([service]), snapshot),
+    ).not.toThrow();
+  });
+
+  test('a schema TYPE change at the same method and path flips the shape digest', () => {
+    const snapshot = buildSurfaceManifest([service]);
+    const retyped = implement(
+      defineContract(
+        { prefix: 'notes', scope: 'public' },
+        {
+          read: {
+            method: 'GET',
+            path: '/:id',
+            desc: 'Read a note',
+            params: NoteParamsSchema,
+            // Same address, same presence flags — different output TYPE.
+            output: RetypedNoteSchema,
+            expose: ['HTTP', 'MCP', 'AGENT', 'CLI'],
+          },
+        },
+      ),
+      { read: ({ params }) => ({ id: Number(params.id) }) },
+    );
+    expect(() =>
+      assertManifestMatchesSnapshot(buildSurfaceManifest([retyped]), snapshot),
+    ).toThrow(/diverged from the committed snapshot/);
+  });
+
   test('fails first on duplicate contract identity', () => {
     expect(() => buildSurfaceManifest([service, service])).toThrow(
       'Duplicate operation identity notes.read',
     );
   });
+
+  test('a broken /mcp endpoint rejects discovery — even when zero tools are expected', async () => {
+    const broken = Bun.serve({
+      port: 0,
+      fetch: () => new Response('not the MCP endpoint', { status: 404 }),
+    });
+    try {
+      await expect(discoverMcpTools(`http://127.0.0.1:${broken.port}`, [])).rejects.toThrow();
+    } finally {
+      broken.stop(true);
+    }
+  });
+
+  test('the CLI surface observed from the SPAWNED process matches the committed snapshot', async () => {
+    // External observation against the external anchor — neither side is the
+    // in-process `services` object, so they cannot move together.
+    const root = join(import.meta.dir, '../../..');
+    const commands = await discoverCliCommands(root);
+    const snapshot = SurfaceSnapshotCliSchema.parse(
+      JSON.parse(
+        await readFile(join(root, 'packages/backend/src/surface.snapshot.json'), 'utf8'),
+      ),
+    );
+    const expected = snapshot
+      .flatMap((operation) => (operation.tools.CLI ? [operation.tools.CLI] : []))
+      .sort();
+    expect([...commands].sort()).toEqual(expected);
+  });
 });
+
+const SurfaceSnapshotCliSchema = z.array(
+  z.object({ tools: z.object({ CLI: z.string().optional() }) }),
+);

package/template/packages/backend/src/surface-manifest.ts

@@ -1,14 +1,29 @@
+import { createHash } from 'node:crypto';
 import type { HttpMethod } from 'stitchkit/contract';
 import type { OpenApiDocument, ServiceDef } from 'stitchkit/server';
 import { listToolNames } from 'stitchkit/tools';
+import { z } from 'zod';
 
 export interface SurfaceManifestOperation {
   service: string;
   action: string;
+  scope: string;
+  hasInput: boolean;
+  hasOutput: boolean;
+  /** Digest of the input JSON Schema — a TYPE change flips it, not just presence. */
+  inputShape: string | null;
+  /** Digest of the output JSON Schema. */
+  outputShape: string | null;
   http: Array<{ method: HttpMethod; path: string }>;
   tools: Partial<Record<'MCP' | 'AGENT' | 'CLI', string>>;
 }
 
+function schemaShape(schema: z.ZodType | undefined, io: 'input' | 'output'): string | null {
+  if (!schema) return null;
+  const document = z.toJSONSchema(schema, { io, unrepresentable: 'any' });
+  return createHash('sha256').update(JSON.stringify(document)).digest('hex').slice(0, 16);
+}
+
 function joinPath(...parts: Array<string | undefined>): string {
   const joined = parts
     .filter((part): part is string => Boolean(part))
@@ -58,6 +73,11 @@ export function buildSurfaceManifest(
       operations.set(key, {
         service: service.name,
         action: method.key,
+        scope: method.scope ?? service.scope,
+        hasInput: Boolean(method.inputSchema),
+        hasOutput: Boolean(method.outputSchema),
+        inputShape: schemaShape(method.inputSchema, 'input'),
+        outputShape: schemaShape(method.outputSchema, 'output'),
         http:
           !method.expose || method.expose.includes('HTTP')
             ? [
@@ -89,29 +109,112 @@ export function buildSurfaceManifest(
   );
 }
 
+/**
+ * Compare the LIVE manifest against the committed snapshot — the external
+ * anchor that a source-level change (an `expose` edit, a schema type change, a
+ * scope change) cannot move along with itself. Regenerate deliberately with
+ * `bun run surface:snapshot` and review the diff.
+ */
+export function assertManifestMatchesSnapshot(
+  manifest: readonly SurfaceManifestOperation[],
+  snapshot: readonly SurfaceManifestOperation[],
+): void {
+  const actual = JSON.stringify(manifest, null, 2);
+  const expected = JSON.stringify(snapshot, null, 2);
+  if (actual !== expected) {
+    throw new Error(
+      `Declared surface diverged from the committed snapshot — if the change is intended, regenerate it with "bun run surface:snapshot" and review the diff.\nsnapshot: ${expected}\nactual: ${actual}`,
+    );
+  }
+}
+
 export function assertSurfaceConformance({
   manifest,
   openApi,
   mcpToolNames,
+  agentToolNames,
+  cliToolNames,
+  metadata = 'require',
 }: {
   manifest: readonly SurfaceManifestOperation[];
   openApi: Pick<OpenApiDocument, 'paths'>;
   mcpToolNames: readonly string[];
+  agentToolNames: readonly string[];
+  cliToolNames: readonly string[];
+  /**
+   * `'require'` (default) — the OpenAPI document must carry `x-stitchkit-*`
+   * metadata and it is compared; `'ignore'` — an explicitly declared mode for
+   * standard documents. A silent skip is not an option.
+   */
+  metadata?: 'require' | 'ignore';
 }): void {
+  const openApiOperations = Object.entries(openApi.paths).flatMap(([path, item]) =>
+    Object.entries(item)
+      .filter(([method]) => ['get', 'post', 'put', 'patch', 'delete', 'head'].includes(method))
+      .map(([method, operation]) => ({ method: method.toUpperCase(), path, operation })),
+  );
   assertSameSet(
     'HTTP/OpenAPI',
     manifest.flatMap((operation) =>
       operation.http.map((entry) => `${entry.method}:${entry.path}`),
     ),
-    Object.entries(openApi.paths).flatMap(([path, item]) =>
-      Object.keys(item)
-        .filter((method) => ['get', 'post', 'put', 'patch', 'delete', 'head'].includes(method))
-        .map((method) => `${method.toUpperCase()}:${path}`),
-    ),
+    openApiOperations.map(({ method, path }) => `${method}:${path}`),
   );
+  const carriesContractMetadata = openApiOperations.some(({ operation }) =>
+    OpenApiOperationMetadataPresenceSchema.parse(operation),
+  );
+  if (metadata === 'require' && openApiOperations.length > 0 && !carriesContractMetadata) {
+    throw new Error(
+      'OpenAPI document carries no x-stitchkit-* contract metadata — pass metadata: "ignore" only for a deliberately standard document',
+    );
+  }
+  if (metadata === 'require' && carriesContractMetadata) {
+    assertSameSet(
+      'HTTP/OpenAPI contract metadata',
+      manifest.flatMap((operation) =>
+        operation.http.map(
+          (entry) =>
+            `${entry.method}:${entry.path}:${operation.scope}:${operation.hasInput}:${operation.hasOutput}`,
+        ),
+      ),
+      openApiOperations.map(({ method, path, operation }) => {
+        const metadata = OpenApiOperationMetadataSchema.parse(operation);
+        return `${method}:${path}:${metadata['x-stitchkit-scope']}:${metadata['x-stitchkit-has-input']}:${metadata['x-stitchkit-has-output']}`;
+      }),
+    );
+  }
   assertSameSet(
     'MCP discovery',
     manifest.flatMap((operation) => (operation.tools.MCP ? [operation.tools.MCP] : [])),
     mcpToolNames,
   );
+  assertSameSet(
+    'AGENT mount',
+    manifest.flatMap((operation) => (operation.tools.AGENT ? [operation.tools.AGENT] : [])),
+    agentToolNames,
+  );
+  assertSameSet(
+    'CLI manifest',
+    manifest.flatMap((operation) => (operation.tools.CLI ? [operation.tools.CLI] : [])),
+    cliToolNames,
+  );
 }
+
+const OpenApiOperationMetadataSchema = z.object({
+  'x-stitchkit-scope': z.string(),
+  'x-stitchkit-has-input': z.boolean(),
+  'x-stitchkit-has-output': z.boolean(),
+});
+
+const OpenApiOperationMetadataPresenceSchema = z
+  .object({
+    'x-stitchkit-scope': z.unknown().optional(),
+    'x-stitchkit-has-input': z.unknown().optional(),
+    'x-stitchkit-has-output': z.unknown().optional(),
+  })
+  .transform(
+    (metadata) =>
+      metadata['x-stitchkit-scope'] !== undefined ||
+      metadata['x-stitchkit-has-input'] !== undefined ||
+      metadata['x-stitchkit-has-output'] !== undefined,
+  );