create-stitchkit 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,83 @@ is declared in the template root catalog.
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-08-15
+
+### Changed
+
+- **The template targets Stitchkit 0.49.2 and owns one managed server lifecycle.**
+  Generated backends pass the full Socket.IO handle to `createServer()`, close
+  through `server.shutdown()`, and use a repeated process signal to force the
+  same shutdown chain instead of creating a competing close path.
+
+### Fixed
+
+- **Repository refresh and realtime verification are deterministic.** A successful
+  refresh updates the initiating browser from its typed mutation result, remote
+  browsers still update through the Socket.IO cache bridge, and the release lane
+  exercises the complete backend path against a local GitHub-compatible upstream
+  instead of depending on public API availability.
+
+## [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/_env.example.append

@@ -1,4 +1,6 @@
 GITHUB_REPOSITORY=max-listov/stitchkit
 GITHUB_CACHE_TTL_SECONDS=900
+# Optional. Defaults to the public GitHub API and supports GitHub Enterprise.
+# GITHUB_API_URL=https://api.github.com
 # Optional. Authenticated conditional requests have a higher GitHub rate limit.
 # GITHUB_TOKEN=github_pat_...

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

@@ -1,4 +1,78 @@
-import { expect, test } from '@playwright/test';
+import { expect, type Page, test } from '@playwright/test';
+
+async function gotoWithRealtime(page: Page): Promise<void> {
+  const connected = page
+    .waitForEvent('websocket', {
+      predicate: (socket) => socket.url().includes('/socket.io/'),
+    })
+    .then((socket) =>
+      socket.waitForEvent('framereceived', {
+        predicate: ({ payload }) => typeof payload === 'string' && payload.startsWith('40'),
+      }),
+    );
+  await page.goto('/en');
+  await connected;
+}
+
+async function expectRepositorySummary(page: Page): Promise<void> {
+  const summary = page.getByTestId('repository-summary');
+  await expect(summary).toHaveCount(1);
+  await expect(summary).toBeVisible();
+  await expect(summary.getByText('max-listov/stitchkit', { exact: true })).toBeVisible();
+}
+
+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 expectRepositorySummary(page);
+  expect(clientReads).toBe(0);
+});
+
+test('a server realtime event updates the TanStack cache without a client refetch', async ({
+  context,
+  page,
+}) => {
+  await gotoWithRealtime(page);
+  const summary = page.getByTestId('repository-summary');
+  await expect(summary).toBeVisible();
+  const before = await summary.getAttribute('data-fetched-at');
+  expect(before).not.toBeNull();
+
+  // Sever the observer's HTTP read path completely, then refresh from a second
+  // tab. The observer never invokes the mutation and cannot consume its HTTP
+  // result, so only the Socket.IO event can update its TanStack cache.
+  await page.route('**/api/repository', async (route) => {
+    if (route.request().method() === 'GET') {
+      await route.abort();
+      return;
+    }
+    await route.continue();
+  });
+  const trigger = await context.newPage();
+  await trigger.goto('/en');
+  await trigger.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) => {
@@ -6,7 +80,7 @@ test('renders and refreshes the repository example', async ({ page }) => {
     await route.continue();
   });
   await page.goto('/en');
-  await expect(page.getByText('max-listov/stitchkit')).toBeVisible();
+  await expectRepositorySummary(page);
 
   const refresh = page.getByRole('button', { name: 'Refresh repository data' });
   await expect(refresh).toHaveCSS('height', '32px');

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/domain/repository/github-cache.ts

@@ -155,12 +155,12 @@ export class GitHubRepositoryCache {
 
     try {
       const [repositoryResponse, commitsResponse] = await Promise.all([
-        this.fetcher(new URL(`/repos/${repositoryName}`, 'https://api.github.com'), {
+        this.fetcher(new URL(`/repos/${repositoryName}`, env.GITHUB_API_URL), {
           headers: githubHeaders(),
           signal: AbortSignal.timeout(8_000),
         }),
         this.fetcher(
-          new URL(`/repos/${repositoryName}/commits?per_page=1`, 'https://api.github.com'),
+          new URL(`/repos/${repositoryName}/commits?per_page=1`, env.GITHUB_API_URL),
           { headers: githubHeaders(), signal: AbortSignal.timeout(8_000) },
         ),
       ]);

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/config/src/features.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 
 export const featureServerSchema = {
+  GITHUB_API_URL: z.url().default('https://api.github.com'),
   GITHUB_REPOSITORY: z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/),
   GITHUB_CACHE_TTL_SECONDS: z.coerce.number().int().positive().default(900),
   GITHUB_TOKEN: z.string().min(1).optional(),

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

@@ -30,8 +30,8 @@ export function RepositorySummary() {
   const queryClient = useQueryClient();
   const repository = useRepository();
   const refresh = useRefreshRepository({
-    onSuccess: async () => {
-      await queryClient.invalidateQueries({ queryKey: useRepository.getKey() });
+    onSuccess: (snapshot) => {
+      queryClient.setQueryData(useRepository.getKey(), snapshot);
     },
   });
 
@@ -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,11 @@
-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';
+import { assertPublicWebSurface } from './web-surface-smoke';
 
+const toolingEnv = loadToolingEnv();
 const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
 
 async function json(path: string, init?: RequestInit): Promise<unknown> {
@@ -24,33 +26,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 +72,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 +153,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()) })
@@ -88,4 +167,6 @@ await runSurfaceConformance({
   }
 }
 
-console.log('Runtime HTTP, OpenAPI, Socket.IO and MCP smoke passed');
+await assertPublicWebSurface(toolingEnv.NEXT_PUBLIC_WEB_URL);
+
+console.log('Runtime HTTP, OpenAPI, Socket.IO, MCP and public web smoke passed');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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: