create-stitchkit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,66 @@ is declared in the template root catalog.
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-08-10
+
+### ⚠️ Breaking changes
+
+- **Generated projects ship no `.env`.** The single environment source is
+  `.env.example`; `bun run env:ensure` (and every tooling entry point,
+  self-healing before validation) renders `.env` with the application-derived
+  database name. A clone and a post-generation rename now produce the same
+  database, and the second-developer path (`runtime:smoke`, `e2e`) works
+  unaided.
+  `// before: scaffold writes .env with a neutral database name` →
+  `// after:  .env is rendered on first run from .env.example`
+
+- **Starter-owned LAN HTTPS is removed.** Generated applications no longer ship
+  `dev:lan`, certificate generation, onboarding routes or `DEV_HTTPS_*` settings.
+  Applications that need a trusted device-testing origin should own certificate
+  creation and pass TLS files through Stitchkit's documented `bun.tls` boundary.
+
+### Changed
+
+- **Surface conformance is anchored and total.** The declared surface is
+  compared against a committed `surface.snapshot.json` (with schema-shape
+  digests, regenerated deliberately via `bun run surface:snapshot`), the CLI is
+  observed by spawning the real process, missing `x-stitchkit-*` metadata is an
+  error unless a standard-document mode is declared explicitly, and the starter
+  lane sweeps generated trees for neutral-identity leaks against a committed
+  allowlist.
+- **The template targets Stitchkit 0.46.** The error-code map covers
+  `REALTIME_CONTRACT_VIOLATION` and conformance validates the operation
+  metadata 0.46 emits.
+- **Scaffold identity is rendered from one config.** The generated
+  `app.config.json` drives runtime identity and database naming; only the root
+  package manifest is structurally projected, with no global text search or
+  inert lockfile rewrite.
+- **Development is explicit and portable.** `bun run dev` validates PM2 and
+  external PostgreSQL requirements before side effects. The removed LAN HTTPS
+  mode is documented as application-owned framework configuration instead of a
+  starter subsystem.
+
+### Fixed
+
+- **Fresh clones bootstrap in the right order.** The starter materializes its
+  local environment before Prisma/type gates and reports a missing or placeholder
+  `DATABASE_URL` directly.
+- **Every executable source is checked.** Root TypeScript coverage includes
+  scripts and browser E2E; the authored-source guard scans CJS and reports the
+  real offending line.
+- **Runtime and browser gates prove the backend.** Surface conformance compares
+  HTTP/OpenAPI, MCP, Agent and CLI identities and schemas; browser E2E performs
+  a contract call and realtime cache update.
+- **Repository example uses the canonical realtime contract.** Shared Zod event
+  definitions drive backend emission, browser subscriptions and cache bridging
+  without handwritten event maps.
+
+### Removed
+
+- **Starter-owned LAN HTTPS.** `dev:lan`, certificate generation, onboarding
+  transport and `DEV_HTTPS_*` settings are gone; trusted local TLS remains an
+  application-owned adapter choice documented by Stitchkit.
+
 ## [0.2.0] — 2026-08-10
 
 ### ⚠️ Breaking changes

package/dist/cli.js

@@ -60,7 +60,8 @@ function parseOptions(args) {
 // src/scaffold.ts
 import { lstat, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
 import { homedir } from "os";
-import { basename as basename2, dirname, join, parse, relative, resolve, sep } from "path";
+import { basename as basename2, dirname, extname, join, parse, relative, resolve, sep } from "path";
+import { z as z2 } from "zod";
 
 // src/identity.ts
 import { basename } from "path";
@@ -112,12 +113,11 @@ var TEXT_EXTENSIONS = new Set([
   ".yml"
 ]);
 var TEMPLATE_RENAMES = new Map([
-  ["_env", ".env"],
-  ["_env.append", ".env"],
   ["_env.example", ".env.example"],
   ["_env.example.append", ".env.example"],
   ["_gitignore", ".gitignore"]
 ]);
+var RootManifestSchema = z2.looseObject({ name: z2.string().min(1) });
 var IGNORED_DIRECTORIES = new Set([
   ".next",
   "coverage",
@@ -189,8 +189,8 @@ async function collectMaterialisedFiles(templateDirectory, directory, files) {
     const targetName = TEMPLATE_RENAMES.get(entry.name);
     const sourceRelativePath = relative(templateDirectory, sourcePath);
     const outputRelativePath = targetName ? join(dirname(sourceRelativePath), targetName) : sourceRelativePath;
-    const extension = targetName?.includes(".") ? targetName.slice(targetName.indexOf(".")) : "";
-    const fileExtension = extension || sourcePath.slice(sourcePath.lastIndexOf("."));
+    const materialisedName = outputRelativePath.endsWith(".append") ? outputRelativePath.slice(0, -".append".length) : outputRelativePath;
+    const fileExtension = extname(materialisedName);
     const content = TEXT_EXTENSIONS.has(fileExtension) || targetName ? await readFile(sourcePath, "utf8") : await readFile(sourcePath);
     files.push({
       sourcePath: portablePath(sourceRelativePath),
@@ -234,18 +234,9 @@ async function scaffoldProject(templateDirectory, destination, options = {}) {
     await writeFile(join(resolvedDestination, "app.config.json"), `${JSON.stringify(identity, undefined, 2)}
 `);
     const manifestPath = join(resolvedDestination, "package.json");
-    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
-    manifest.name = identity.slug;
-    await writeFile(manifestPath, `${JSON.stringify(manifest, undefined, 2)}
+    const manifest = RootManifestSchema.parse(JSON.parse(await readFile(manifestPath, "utf8")));
+    await writeFile(manifestPath, `${JSON.stringify({ ...manifest, name: identity.slug }, undefined, 2)}
 `);
-    const lockPath = join(resolvedDestination, "bun.lock");
-    const lock = await readFile(lockPath, "utf8");
-    await writeFile(lockPath, lock.replace(/"name"\s*:\s*"stitchkit-starter"/, `"name": "${identity.slug}"`));
-    for (const environmentPath of [".env", ".env.example"]) {
-      const fullPath = join(resolvedDestination, environmentPath);
-      const environment = await readFile(fullPath, "utf8");
-      await writeFile(fullPath, environment.replaceAll("stitchkit_starter", identity.slug.replaceAll("-", "_")));
-    }
   } catch (error) {
     if (!destinationExisted) {
       await rm(resolvedDestination, { recursive: true, force: true });

package/examples/repository/e2e/repository.spec.ts

@@ -1,5 +1,55 @@
 import { expect, test } from '@playwright/test';
 
+test('prefetched data hydrates without a loading flash or a client refetch', async ({
+  page,
+  request,
+}) => {
+  // The SSR document itself carries the prefetched repository data — the
+  // dehydration envelope is not empty.
+  const document = await request.get('/en');
+  expect(await document.text()).toContain('max-listov/stitchkit');
+
+  // Block the browser-side read entirely: the page must still render the data
+  // from the hydration envelope — never refetching, never flashing a loader.
+  let clientReads = 0;
+  await page.route('**/api/repository', async (route) => {
+    if (route.request().method() === 'GET') {
+      clientReads += 1;
+      await route.abort();
+      return;
+    }
+    await route.continue();
+  });
+  await page.goto('/en');
+  await expect(page.getByText('max-listov/stitchkit')).toBeVisible();
+  expect(clientReads).toBe(0);
+});
+
+test('a server realtime event updates the TanStack cache without a client refetch', async ({
+  page,
+}) => {
+  await page.goto('/en');
+  const summary = page.getByTestId('repository-summary');
+  await expect(summary).toBeVisible();
+  const before = await summary.getAttribute('data-fetched-at');
+  expect(before).not.toBeNull();
+
+  // Sever the refetch path completely: the refresh mutation invalidates the
+  // query, but its refetch is aborted here — so the ONLY way the summary can
+  // carry a new snapshot is the Socket.IO event through the cache bridge.
+  await page.route('**/api/repository', async (route) => {
+    if (route.request().method() === 'GET') {
+      await route.abort();
+      return;
+    }
+    await route.continue();
+  });
+  await page.getByRole('button', { name: 'Refresh repository data' }).click();
+  await expect(summary).not.toHaveAttribute('data-fetched-at', before ?? '', {
+    timeout: 10_000,
+  });
+});
+
 test('renders and refreshes the repository example', async ({ page }) => {
   await page.route('**/api/repository/refresh', async (route) => {
     await new Promise((resolve) => setTimeout(resolve, 750));

package/examples/repository/packages/backend/src/domain/repository/github-cache.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, test } from 'bun:test';
+import { RepositoryVisibility } from '@app/db';
+import { RepositoryVisibilitySchema } from '@app/shared';
 import {
   GitHubRepositoryCache,
   type RepositorySnapshotStore,
@@ -39,6 +41,12 @@ function commitsResponse(): Response {
 }
 
 describe('GitHubRepositoryCache', () => {
+  test('keeps the shared wire enum aligned with the database enum', () => {
+    expect([...RepositoryVisibilitySchema.options].sort()).toEqual(
+      Object.values(RepositoryVisibility).sort(),
+    );
+  });
+
   test('deduplicates refreshes and persists an exact repository snapshot', async () => {
     const requests: URL[] = [];
     const fetcher = async (url: URL) => {

package/examples/repository/packages/backend/src/surface.snapshot.json

@@ -0,0 +1,58 @@
+[
+  {
+    "service": "repository",
+    "action": "read",
+    "scope": "public",
+    "hasInput": false,
+    "hasOutput": true,
+    "inputShape": null,
+    "outputShape": "49c1f81a53ca82ad",
+    "http": [
+      {
+        "method": "GET",
+        "path": "/api/repository"
+      }
+    ],
+    "tools": {
+      "MCP": "repository_read",
+      "AGENT": "repository_read",
+      "CLI": "repository_read"
+    }
+  },
+  {
+    "service": "repository",
+    "action": "refresh",
+    "scope": "public",
+    "hasInput": false,
+    "hasOutput": true,
+    "inputShape": null,
+    "outputShape": "49c1f81a53ca82ad",
+    "http": [
+      {
+        "method": "POST",
+        "path": "/api/repository/refresh"
+      }
+    ],
+    "tools": {
+      "MCP": "repository_refresh",
+      "AGENT": "repository_refresh",
+      "CLI": "repository_refresh"
+    }
+  },
+  {
+    "service": "system",
+    "action": "status",
+    "scope": "public",
+    "hasInput": false,
+    "hasOutput": true,
+    "inputShape": null,
+    "outputShape": "58b078ade3ee6167",
+    "http": [
+      {
+        "method": "GET",
+        "path": "/api/system/status"
+      }
+    ],
+    "tools": {}
+  }
+]

package/examples/repository/packages/backend/src/surface.ts

@@ -1,14 +1,16 @@
 import { env } from '@app/config';
-import type { ClientToServerEvents, ServerToClientEvents } from '@app/shared';
-import { createSocketIOServer } from 'stitchkit/server';
+import { repositoryRealtimeContract } from '@app/shared';
+import { bindRealtimeServer, createSocketIOServer } from 'stitchkit/server';
 import { createRepositoryService } from './transport/repository-service';
+import { createSystemService } from './transport/system-service';
 
 export async function createSurface() {
-  const socket = await createSocketIOServer<ServerToClientEvents, ClientToServerEvents>({
+  const socket = await createSocketIOServer({
     cors: { origin: env.CORS_ORIGIN },
   });
+  const realtime = bindRealtimeServer(repositoryRealtimeContract, socket);
   const repositoryService = createRepositoryService((snapshot) =>
-    socket.io.emit('repository:refreshed', snapshot),
+    realtime.emit('repository:refreshed', snapshot),
   );
-  return { socket, services: [repositoryService] };
+  return { socket, services: [createSystemService(), repositoryService] };
 }

package/examples/repository/packages/frontend/src/components/repository-summary.tsx

@@ -52,7 +52,11 @@ export function RepositorySummary() {
     : '—';
 
   return (
-    <div className='mx-auto flex w-full max-w-4xl flex-col gap-4 rounded-xl border border-border bg-card/80 px-4 py-4 text-left backdrop-blur sm:flex-row sm:items-center sm:px-5'>
+    <div
+      className='mx-auto flex w-full max-w-4xl flex-col gap-4 rounded-xl border border-border bg-card/80 px-4 py-4 text-left backdrop-blur sm:flex-row sm:items-center sm:px-5'
+      data-fetched-at={snapshot.cache.fetchedAt}
+      data-testid='repository-summary'
+    >
       <a
         className='group flex min-w-0 flex-1 items-center gap-3'
         href={snapshot.htmlUrl}

package/examples/repository/packages/frontend/src/lib/realtime/repository.ts

@@ -1,14 +1,13 @@
-import type { ClientToServerEvents, ServerToClientEvents } from '@app/shared';
-import { createSocketIOClient } from 'stitchkit';
+import { repositoryRealtimeContract } from '@app/shared';
+import { createRealtimeClient } from 'stitchkit';
 import { createCacheBridge } from 'stitchkit/react';
 import { env } from '@/env';
 import { useRepository } from '@/lib/api/queries';
 import { getQueryClient } from '@/lib/query-client';
 
-export const repositorySocket = createSocketIOClient<
-  ServerToClientEvents,
-  ClientToServerEvents
->({ url: env.NEXT_PUBLIC_API_URL });
+export const repositorySocket = createRealtimeClient(repositoryRealtimeContract, {
+  url: env.NEXT_PUBLIC_API_URL,
+});
 
 export const repositoryBridge = createCacheBridge({
   socket: repositorySocket,

package/examples/repository/packages/shared/src/index.ts

@@ -1,3 +1,5 @@
 export * from './contracts/repository';
-export * from './events/repository';
+export * from './contracts/system';
+export * from './realtime/repository';
 export * from './schemas/repository';
+export * from './schemas/system';

package/examples/repository/packages/shared/src/realtime/repository.ts

@@ -0,0 +1,10 @@
+import { defineRealtimeContract } from 'stitchkit';
+import { z } from 'zod';
+import { RepositorySnapshotSchema } from '../schemas/repository';
+
+export const repositoryRealtimeContract = defineRealtimeContract({
+  serverToClient: {
+    'repository:refreshed': { args: z.tuple([RepositorySnapshotSchema]) },
+  },
+  clientToServer: {},
+});

package/examples/repository/packages/shared/src/schemas/repository.ts

@@ -1,12 +1,14 @@
-import { RepositoryVisibility } from '@app/db/enums';
 import { z } from 'zod';
 
+export const RepositoryVisibilitySchema = z.enum(['PUBLIC', 'PRIVATE', 'INTERNAL']);
+export type RepositoryVisibility = z.infer<typeof RepositoryVisibilitySchema>;
+
 export const RepositorySnapshotSchema = z.object({
   fullName: z.string().min(1),
   description: z.string().nullable(),
   htmlUrl: z.url(),
   language: z.string().nullable(),
-  visibility: z.enum(RepositoryVisibility),
+  visibility: RepositoryVisibilitySchema,
   stars: z.number().int().nonnegative(),
   forks: z.number().int().nonnegative(),
   openIssues: z.number().int().nonnegative(),

package/examples/repository/scripts/runtime-smoke.ts

@@ -1,9 +1,10 @@
-import { RepositorySnapshotSchema } from '@app/shared';
-import { io } from 'socket.io-client';
+import { RepositorySnapshotSchema, repositoryRealtimeContract } from '@app/shared';
+import { createRealtimeClient, defineRealtimeContract } from 'stitchkit';
 import { z } from 'zod';
 import { defineSurfaceProbe, runSurfaceConformance } from './surface-conformance';
-import { toolingEnv } from './tooling-env';
+import { loadToolingEnv } from './tooling-env';
 
+const toolingEnv = loadToolingEnv();
 const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
 
 async function json(path: string, init?: RequestInit): Promise<unknown> {
@@ -24,33 +25,39 @@ await runSurfaceConformance({
       fixture: { path: '/api/repository/refresh' },
       output: RepositorySnapshotSchema,
       run: async ({ path }) => {
-        const socket = io(apiOrigin, { transports: ['websocket'] });
+        const rejected: string[] = [];
+        const socket = createRealtimeClient(repositoryRealtimeContract, {
+          url: apiOrigin,
+          transports: ['websocket'],
+          onRejected: ({ event, direction, phase }) => {
+            rejected.push(`${event}:${direction}:${phase}`);
+          },
+        });
         try {
           await new Promise<void>((resolve, reject) => {
             const timeout = setTimeout(
               () => reject(new Error('Socket.IO connection timed out')),
               5_000,
             );
-            const onConnect = () => {
+            const unsubscribe = socket.onConnectionChange((connected, reason) => {
+              if (!connected) {
+                if (reason) reject(new Error(`Socket.IO disconnected: ${reason}`));
+                return;
+              }
               clearTimeout(timeout);
-              socket.off('connect_error', onConnectError);
+              unsubscribe();
               resolve();
-            };
-            const onConnectError = (error: Error) => {
-              clearTimeout(timeout);
-              socket.off('connect', onConnect);
-              reject(error);
-            };
-            socket.once('connect', onConnect);
-            socket.once('connect_error', onConnectError);
+            });
+            socket.connect();
           });
           const refreshedEvent = new Promise<string>((resolve, reject) => {
             const timeout = setTimeout(
               () => reject(new Error('Socket.IO repository refresh event timed out')),
               5_000,
             );
-            socket.once('repository:refreshed', (snapshot) => {
+            const unsubscribe = socket.on('repository:refreshed', (snapshot) => {
               clearTimeout(timeout);
+              unsubscribe();
               resolve(snapshot.fullName);
             });
           });
@@ -64,9 +71,77 @@ await runSurfaceConformance({
           if (cached.fullName !== refreshed.fullName) {
             throw new Error('Repository cache read differs');
           }
+          if (rejected.length > 0) {
+            throw new Error(`Realtime contract rejected ${rejected.join(', ')}`);
+          }
           return refreshed;
         } finally {
-          socket.close();
+          socket.disconnect();
+        }
+      },
+    }),
+    defineSurfaceProbe({
+      name: 'realtime rejection path fires on a contract mismatch',
+      input: z.object({ path: z.literal('/api/repository/refresh') }),
+      fixture: { path: '/api/repository/refresh' },
+      run: async ({ path }) => {
+        // NEGATIVE probe: a client whose local contract disagrees with the
+        // server must see the real payload REJECTED — this executes the
+        // rejection path instead of merely asserting its absence. Matched by
+        // event/direction/phase, never by message text.
+        const divergentContract = defineRealtimeContract({
+          serverToClient: {
+            'repository:refreshed': { args: z.tuple([z.object({ bogus: z.string() })]) },
+          },
+          clientToServer: {},
+        });
+        const rejections: Array<{ event: string; direction: string; phase: string }> = [];
+        const socket = createRealtimeClient(divergentContract, {
+          url: apiOrigin,
+          transports: ['websocket'],
+          onRejected: ({ event, direction, phase }) => {
+            rejections.push({ event, direction, phase });
+          },
+        });
+        try {
+          await new Promise<void>((resolve, reject) => {
+            const timeout = setTimeout(
+              () => reject(new Error('Socket.IO connection timed out')),
+              5_000,
+            );
+            const unsubscribe = socket.onConnectionChange((connected) => {
+              if (!connected) return;
+              clearTimeout(timeout);
+              unsubscribe();
+              resolve();
+            });
+            socket.connect();
+          });
+          // A handler must be attached for the inbound frame to be validated.
+          const unsubscribe = socket.on('repository:refreshed', () => {
+            throw new Error('a payload outside the local contract reached the handler');
+          });
+          await json(path, { method: 'POST' });
+          const deadline = Date.now() + 5_000;
+          while (rejections.length === 0 && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 50));
+          }
+          unsubscribe();
+          const rejection = rejections[0];
+          if (!rejection) {
+            throw new Error('the contract mismatch was never rejected');
+          }
+          if (
+            rejection.event !== 'repository:refreshed' ||
+            rejection.direction !== 'client-inbound' ||
+            rejection.phase !== 'arguments'
+          ) {
+            throw new Error(
+              `unexpected rejection identity: ${rejection.event}:${rejection.direction}:${rejection.phase}`,
+            );
+          }
+        } finally {
+          socket.disconnect();
         }
       },
     }),
@@ -77,8 +152,11 @@ await runSurfaceConformance({
   const corsResponse = await fetch(`${apiOrigin}/api/repository/`, {
     headers: { Origin: 'http://localhost:58302' },
   });
-  if (corsResponse.headers.get('access-control-allow-origin') !== '*') {
-    throw new Error('Public API does not allow a forwarded browser origin');
+  if (
+    corsResponse.headers.get('access-control-allow-origin') !==
+    new URL(toolingEnv.NEXT_PUBLIC_WEB_URL).origin
+  ) {
+    throw new Error('API CORS origin differs from the configured web origin');
   }
   const openApi = z
     .object({ paths: z.record(z.string(), z.unknown()) })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",

package/template/README.md

@@ -1,4 +1,4 @@
-# Stitchkit Starter
+# Application starter
 
 Production-shaped application generated by `create-stitchkit`.
 
@@ -14,8 +14,8 @@ Point `DATABASE_URL` in `.env` at an existing PostgreSQL database, then run:
 bun run dev
 ```
 
-The command validates the environment, generates the Prisma client, applies the
-checked-in migrations and launches:
+The command validates the environment, generates the Prisma client, applies any
+database migrations you add and launches:
 
 - Web: <http://localhost:3210>
 - UI catalogue: <http://localhost:3210/en/ui>
@@ -23,7 +23,7 @@ checked-in migrations and launches:
 - OpenAPI: <http://localhost:3211/openapi.json>
 - MCP: <http://localhost:3211/mcp>
 
-The home page is a compact, domain-free Stitchkit Starter reference surface.
+The home page is a compact, domain-free application reference surface.
 Add application features as vertical schema → contract → service → client slices.
 The exact workflow is in [`docs/ADDING_A_FEATURE.md`](docs/ADDING_A_FEATURE.md),
 and root [`AGENTS.md`](AGENTS.md) gives coding agents the application boundaries.
@@ -54,14 +54,10 @@ Unsupported browsers and users requesting reduced motion switch immediately.
 bun run check
 bun run test
 bun run build
+bun run runtime:smoke
+bun run e2e
 ```
 
-## Physical-device HTTPS
-
-`bun run dev:lan` is an explicit trusted-LAN mode powered by mkcert. It leaves
-normal development and production unchanged. Setup and device trust steps are
-in [`docs/LAN_HTTPS.md`](docs/LAN_HTTPS.md).
-
 ## Production
 
 Provide a production `.env`, then:

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.46.0",
   },
   "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.46.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-vHFaXHp5Ws4sFSRptqPqwpc7CGEEbmHY+duvvGkNGwuyp51aY4De3bXVh1xiZSGiUN5IS0jhj1P59GG3VjP/Ag=="],
 
     "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