create-stitchkit 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",
@@ -16,6 +16,7 @@
   "files": [
     "dist",
     "template/**/*",
+    "examples/**/*",
     "!template/**/.env",
     "!template/**/node_modules/**",
     "!template/**/.next/**",
@@ -26,6 +27,11 @@
     "!template/**/src/generated/**",
     "!template/**/*.log",
     "!template/**/*.tsbuildinfo",
+    "!examples/**/node_modules/**",
+    "!examples/**/.next/**",
+    "!examples/**/dist/**",
+    "!examples/**/*.log",
+    "!examples/**/*.tsbuildinfo",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -39,6 +45,9 @@
     "build": "rm -rf dist && bun build src/cli.ts --outdir dist --target bun --packages external && chmod +x dist/cli.js",
     "prepublishOnly": "bun run check && bun run test && bun run build"
   },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "typescript": "^7.0.2"

package/template/AGENTS.md

@@ -0,0 +1,50 @@
+# Application agent guide
+
+This repository is a generated Stitchkit application. It is not the Stitchkit
+framework source repository.
+
+## Architecture
+
+- `packages/shared` owns named Zod schemas, inferred DTO types, HTTP contracts
+  and realtime event definitions. It has no database, server or browser imports.
+- `packages/db` owns Prisma schema, migrations and the generated client.
+- `packages/backend` implements contracts, composes the registered surface and
+  owns application policy. Routes remain thin transport boundaries.
+- `packages/frontend` owns Next.js pages, typed clients, query/mutation hooks and
+  cache reactions.
+- `packages/config/src/server.ts` is the only server environment boundary.
+  `app.config.json` is the only application identity boundary.
+
+Dependencies point inward: frontend/backend → shared; backend → db/config.
+Shared never imports an application runtime package.
+
+## Required patterns
+
+- Define each runtime DTO as a named Zod schema in `packages/shared/src/schemas`.
+- Reference schemas from a separate contract module; never inline `z.object()`
+  inside `defineContract`.
+- Implement one service method per contract operation and register the service
+  once in `packages/backend/src/surface.ts`.
+- Use Stitchkit's typed browser client and react-query-kit hooks; do not rebuild
+  endpoint URLs, query keys or error envelopes by hand.
+- Use Socket.IO through the shared realtime contract and Stitchkit wrappers.
+  Authentication, authorization and room membership remain application policy.
+- Extend runtime smoke with an explicit typed probe for operations whose handler
+  behavior matters. Generic OpenAPI/MCP discovery checks are already derived.
+
+Do not duplicate DTOs, copy Stitchkit internals, add raw routes for operations a
+contract can express, or create compatibility aliases. Fix framework gaps in
+Stitchkit rather than copying its implementation into this application.
+
+## Workflow
+
+Follow [`docs/ADDING_A_FEATURE.md`](docs/ADDING_A_FEATURE.md) for the complete
+vertical path. Before handing work off, run:
+
+```bash
+bun run check
+bun run test
+bun run build
+bun run runtime:smoke
+```
+

package/template/README.md

@@ -2,6 +2,10 @@
 
 Production-shaped application generated by `create-stitchkit`.
 
+Application identity lives in [`app.config.json`](app.config.json). Change the
+slug, display name, version and localized description there; package names,
+process names, MCP/OpenAPI identity, UI copy and SEO derive from it.
+
 ## Start
 
 Point `DATABASE_URL` in `.env` at an existing PostgreSQL database, then run:
@@ -19,11 +23,16 @@ checked-in migrations and launches:
 - OpenAPI: <http://localhost:3211/openapi.json>
 - MCP: <http://localhost:3211/mcp>
 
-The home page is a compact Stitchkit Starter reference surface. One configured
-GitHub repository exercises the PostgreSQL cache → contract → typed client →
+The home page is a compact, domain-free Stitchkit Starter 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.
+
+When generated with `--example repository`, one configured GitHub repository
+exercises the PostgreSQL cache → contract → typed client →
 mutation invalidation → realtime path without adding a demo product domain.
 Configure it with `GITHUB_REPOSITORY`; `GITHUB_TOKEN` is optional.
-Repository visibility demonstrates the canonical Prisma enum → shared Zod schema
+Repository visibility then demonstrates the canonical Prisma enum → shared Zod schema
 → HTTP/UI path without duplicating its allowed values.
 
 The `/en/ui` catalogue is isolated under
@@ -47,6 +56,12 @@ bun run test
 bun run build
 ```
 
+## 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:
@@ -65,5 +80,3 @@ application owns its schema and migrations; the environment owns the database
 process and supplies its connection through `DATABASE_URL`.
 
 `bun run dev` and `bun run pm2:dev` use the same direct PM2 development path.
-Rename the neutral `stitchkit-starter` package and process names when adopting
-the template for a product.

package/template/_env

@@ -6,6 +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
-GITHUB_REPOSITORY=max-listov/stitchkit
-GITHUB_CACHE_TTL_SECONDS=900
-# GITHUB_TOKEN=github_pat_...
+CORS_ORIGIN=*

package/template/_env.example

@@ -6,7 +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
-GITHUB_REPOSITORY=max-listov/stitchkit
-GITHUB_CACHE_TTL_SECONDS=900
-# Optional. Authenticated conditional requests have a higher GitHub rate limit.
-# GITHUB_TOKEN=github_pat_...
+CORS_ORIGIN=*

package/template/app.config.json

@@ -0,0 +1,9 @@
+{
+  "slug": "stitchkit-starter",
+  "name": "Stitchkit Starter",
+  "version": "0.1.0",
+  "description": {
+    "en": "Stitchkit Starter is a production application built with Stitchkit.",
+    "ru": "Stitchkit Starter — production-приложение на Stitchkit."
+  }
+}

package/template/bun.lock

@@ -8,6 +8,7 @@
         "dotenv": "^17.4.2",
       },
       "devDependencies": {
+        "@app/config": "workspace:*",
         "@app/shared": "workspace:*",
         "@axe-core/playwright": "^4.11.0",
         "@biomejs/biome": "^2.5.7",
@@ -72,6 +73,7 @@
       "name": "@app/frontend",
       "version": "0.1.0",
       "dependencies": {
+        "@app/config": "workspace:*",
         "@app/db": "workspace:*",
         "@app/shared": "workspace:*",
         "@radix-ui/react-alert-dialog": "^1.1.23",
@@ -136,7 +138,7 @@
     },
   },
   "catalog": {
-    "stitchkit": "^0.44.0",
+    "stitchkit": "^0.45.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=="],
@@ -1115,7 +1117,7 @@
 
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
-    "stitchkit": ["stitchkit@0.44.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-B/MBeBpaoruA3bSxQ25oJ7IZUP08+CZGkpxbXH6PtnEsFoDGev2m3+QEULnQCGQYvvuMkrdoB1z/6k1j+hSdZg=="],
+    "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=="],
 
     "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

@@ -0,0 +1,101 @@
+# 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.
+
+## 1. Define the wire data
+
+Create `packages/shared/src/schemas/status.ts`:
+
+```ts
+import { z } from 'zod'
+
+export const StatusSchema = z.object({ message: z.string().min(1) })
+export const UpdateStatusInputSchema = StatusSchema
+export type Status = z.infer<typeof StatusSchema>
+```
+
+Export it from the shared package. Do not introduce a second handwritten DTO.
+
+## 2. Define the HTTP/tool contract separately
+
+Create `packages/shared/src/contracts/status.ts` and import the named schemas:
+
+```ts
+import { defineContract } from 'stitchkit'
+import { StatusSchema, UpdateStatusInputSchema } from '../schemas/status'
+
+export const statusContract = defineContract(
+  { prefix: 'status', scope: 'public' },
+  {
+    read: { method: 'GET', path: '/', desc: 'Read status', output: StatusSchema },
+    update: {
+      method: 'PUT', path: '/', desc: 'Update status',
+      input: UpdateStatusInputSchema, output: StatusSchema,
+      expose: ['HTTP', 'MCP', 'AGENT', 'CLI'],
+    },
+  },
+)
+```
+
+The contract owns transport identity. Do not add a raw route or duplicate path.
+
+## 3. Implement and register the service
+
+Create `packages/backend/src/transport/status-service.ts` with `implement()`.
+Keep persistence and business rules in a domain/service module; the contract
+handler calls that module once. Add the returned service to the `services` array
+in `packages/backend/src/surface.ts`. That one registration drives HTTP,
+OpenAPI, MCP, agent tools and CLI discovery.
+
+## 4. Add typed browser access
+
+Export `statusContract` from `packages/shared/src/index.ts`. In
+`packages/frontend/src/lib/api/client.ts`, create `statusApi` with the same
+`createClient(statusContract, http)` pattern used by the application's other
+contracts. Create the query key and react-query-kit query/mutation hooks in
+`packages/frontend/src/lib/api/status.ts`. On mutation success, update or
+invalidate that canonical key.
+
+Render the hook from a feature component. Pages compose features; they do not
+call `fetch`, construct `/api/status` or decode error bodies themselves.
+
+## 5. Add realtime only when another client must observe the change
+
+Declare the event in the shared realtime source and use a named Zod schema for
+its tuple. The server emits after the domain change succeeds; the frontend cache
+bridge reacts by updating or invalidating the status query. Keep handshake auth,
+authorization and room membership in the application. Socket.IO delivery,
+reconnection, retained subscriptions and validation belong to Stitchkit.
+
+The starter advances its single `catalog.stitchkit` target only after the
+required framework release exists. Do not copy a framework adapter into the
+application or maintain a parallel event-map API.
+
+## 6. Prove the surface and behavior
+
+Generic smoke already derives expected HTTP operations and MCP tool names from
+the registered services and compares them with live OpenAPI/MCP discovery. Add
+an explicit probe only for handler behavior:
+
+```ts
+defineSurfaceProbe({
+  name: 'status update lifecycle',
+  input: UpdateStatusInputSchema,
+  fixture: { message: 'Ready' },
+  output: StatusSchema,
+  run: (input) => statusClient.update(input),
+})
+```
+
+Add domain tests beside domain code, contract/schema tests in shared, and UI E2E
+only for user-visible behavior. Finish with the commands in root `AGENTS.md`.
+
+## Ownership boundary
+
+Application-owned: domain policy, persistence, auth decisions, rooms, cache
+semantics and presentation. Framework-owned: contract routing, validation,
+normalized errors, transport lifecycle, tool discovery and Socket.IO wrappers.
+When the framework-owned layer is missing a generic capability, fix Stitchkit
+and upgrade this application's one catalog target after that release exists.

package/template/docs/LAN_HTTPS.md

@@ -0,0 +1,28 @@
+# Trusted LAN HTTPS development
+
+Use this optional mode to test microphone, camera, PWA and WebRTC behavior on a
+physical device connected to the same private network:
+
+```bash
+# Install the maintained local-CA tool first:
+brew install mkcert
+
+bun run dev:lan
+# Multiple private interfaces:
+bun run dev:lan --host 192.168.1.20
+```
+
+The launcher uses mkcert, stores leaf certificates under
+`~/.local/share/<app-slug>/lan-https`, and keeps the CA in mkcert's own CAROOT.
+No certificate or machine address is written into the project. When the chosen
+address changes, only the leaf certificate is renewed.
+
+The command prints the HTTPS web/API URLs and a development-only onboarding URL.
+Open that URL on the phone to download the **public** root certificate. On iOS,
+install the profile and enable full trust under Certificate Trust Settings. On
+Android, install it as a CA certificate; native development builds must opt into
+user-installed roots. The private CA key is never served.
+
+`bun run dev` remains plain localhost HTTP. Production never reads the LAN
+certificate variables or mounts the onboarding routes.
+

package/template/e2e/starter.spec.ts

@@ -1,3 +1,4 @@
+import { appIdentity } from '@app/config/identity';
 import AxeBuilder from '@axe-core/playwright';
 import { expect, test } from '@playwright/test';
 
@@ -6,7 +7,6 @@ test('renders the hydrated starter application and catalogue', async ({ page })
   await expect(page.getByRole('heading', { level: 1 })).toContainText(
     'Build the product, not the plumbing',
   );
-  await expect(page.getByText('max-listov/stitchkit')).toBeVisible();
   await page.getByRole('link', { name: /UI system/ }).click();
   await expect(page).toHaveURL(/\/en\/ui\/components$/);
   await expect(page.getByRole('heading', { level: 1 })).toContainText('UI components');
@@ -17,7 +17,7 @@ test('publishes complete page metadata and a reachable Open Graph card', async (
   request,
 }) => {
   await page.goto('/en/ui/themes');
-  await expect(page).toHaveTitle('Theme system · Stitchkit Starter');
+  await expect(page).toHaveTitle(`Theme system · ${appIdentity.name}`);
   await expect(page.locator('link[rel="canonical"]')).toHaveAttribute(
     'href',
     /\/en\/ui\/themes$/,
@@ -39,23 +39,6 @@ test('publishes complete page metadata and a reachable Open Graph card', async (
   expect(await sitemapResponse.text()).toContain('/ru/ui/themes');
 });
 
-test('spins the refresh icon in place while its action is pending', async ({ page }) => {
-  await page.route('**/api/repository/refresh', async (route) => {
-    await new Promise((resolve) => setTimeout(resolve, 750));
-    await route.continue();
-  });
-  await page.goto('/en');
-
-  const refresh = page.getByRole('button', { name: 'Refresh repository data' });
-  await expect(refresh).toHaveCSS('height', '32px');
-  await expect(refresh).toHaveCSS('width', '32px');
-  await expect(refresh.locator('.tabler-icon-refresh')).toHaveCount(1);
-  await refresh.click();
-  await expect(refresh).toHaveAttribute('aria-busy', 'true');
-  await expect(refresh.locator('svg')).toHaveCount(1);
-  await expect(refresh.locator('.tabler-icon-refresh')).toHaveClass(/animate-spin/);
-});
-
 test('switches catalogue sections and component tabs', async ({ page }) => {
   await page.goto('/en/ui');
   await expect(page).toHaveURL(/\/en\/ui\/components$/);
@@ -176,7 +159,11 @@ test('keeps long localized navigation labels inside the mobile drawer', async ({
   expect(overflow.page).toBeLessThanOrEqual(1);
 });
 
-test('provides a server-first synchronized theme system', async ({ context, page }) => {
+test('provides a server-first synchronized theme system', async ({
+  browserName,
+  context,
+  page,
+}) => {
   const consoleProblems: string[] = [];
   page.on('console', (message) => {
     if (message.type() === 'error' || message.type() === 'warning') {
@@ -210,17 +197,25 @@ test('provides a server-first synchronized theme system', async ({ context, page
   const secondPage = await context.newPage();
   await secondPage.goto('/en/ui/themes');
   await expect(secondPage.locator('html')).toHaveClass(/dark/);
+  await expect(secondPage.getByTestId('theme-state-selected')).not.toContainText('hydrating');
+  await page.emulateMedia({ reducedMotion: 'reduce' });
   await page.getByRole('button', { name: 'Light', exact: true }).click();
+  if (browserName === 'webkit') {
+    // Playwright WebKit shares localStorage but does not dispatch cross-page storage events.
+    await secondPage.reload();
+  }
   await expect(secondPage.locator('html')).toHaveClass(/light/);
 
   await page.getByRole('button', { name: 'System', exact: true }).click();
   await expect(page.getByTestId('theme-state-selected')).toContainText('system');
   const themeCookie = (await context.cookies()).find(
-    (cookie) => cookie.name === 'stitchkit-starter-theme',
+    (cookie) => cookie.name === `${appIdentity.slug}-theme`,
   );
   expect(themeCookie?.value).toBe('system');
   await page.reload();
-  await expect(page.getByTestId('theme-state-server-cookie')).toContainText('system');
+  const serverCookieState = page.getByTestId('theme-state-server-cookie');
+  await expect(serverCookieState).toHaveCount(1);
+  await expect(serverCookieState).toContainText('system');
   expect(
     consoleProblems.filter((message) =>
       /hydration|useServerInsertedHTML|inline script/i.test(message),

package/template/ecosystem.config.cjs

@@ -1,12 +1,13 @@
 const path = require('node:path');
 const { config } = require('dotenv');
+const identity = require('./app.config.json');
 
 config({ path: path.join(__dirname, '.env'), quiet: true, override: true });
 
 module.exports = {
   apps: [
     {
-      name: 'stitchkit-starter-backend',
+      name: `${identity.slug}-backend`,
       cwd: path.join(__dirname, 'packages/backend'),
       script: 'dist/index.js',
       interpreter: 'bun',
@@ -15,7 +16,7 @@ module.exports = {
       env: { NODE_ENV: 'production' },
     },
     {
-      name: 'stitchkit-starter-frontend',
+      name: `${identity.slug}-frontend`,
       cwd: path.join(__dirname, 'packages/frontend'),
       script: 'node_modules/.bin/next',
       args: ['start', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'],

package/template/ecosystem.dev.config.cjs

@@ -1,12 +1,27 @@
 const path = require('node:path');
 const { config } = require('dotenv');
+const identity = require('./app.config.json');
 
-config({ path: path.join(__dirname, '.env'), quiet: true, override: true });
+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: [
     {
-      name: 'stitchkit-starter-backend-dev',
+      name: `${identity.slug}-backend-dev`,
       cwd: path.join(__dirname, 'packages/backend'),
       script: 'src/index.ts',
       interpreter: 'bun',
@@ -16,10 +31,10 @@ module.exports = {
       env: { NODE_ENV: 'development' },
     },
     {
-      name: 'stitchkit-starter-frontend-dev',
+      name: `${identity.slug}-frontend-dev`,
       cwd: path.join(__dirname, 'packages/frontend'),
       script: 'node_modules/.bin/next',
-      args: ['dev', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'],
+      args: frontendArgs,
       interpreter: 'bun',
       autorestart: true,
       kill_timeout: 10000,

package/template/package.json

@@ -7,10 +7,11 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.44.0"
+    "stitchkit": "^0.45.0"
   },
   "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:authored": "bun scripts/check-authored.ts",
     "test": "bun run --filter '*' test",
@@ -36,6 +37,7 @@
     "dotenv": "^17.4.2"
   },
   "devDependencies": {
+    "@app/config": "workspace:*",
     "@app/shared": "workspace:*",
     "@axe-core/playwright": "^4.11.0",
     "@biomejs/biome": "^2.5.7",

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

@@ -1,12 +1,13 @@
 #!/usr/bin/env bun
 
+import { appIdentity } from '@app/config/identity';
 import { createCli } from 'stitchkit/cli';
 import { createSurface } from './surface';
 
 const { services, socket } = await createSurface();
 
 try {
-  await createCli({ name: 'stitchkit-starter', version: '0.1.0', services });
+  await createCli({ name: appIdentity.slug, version: appIdentity.version, services });
 } finally {
   await socket.io.close();
 }

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

@@ -1,20 +1,22 @@
 import { env } from '@app/config';
+import { appIdentity } from '@app/config/identity';
 import { wrapInRequestContext } from 'stitchkit/observability';
 import { createServer, generateOpenApiDocument, openApiRoute } from 'stitchkit/server';
 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();
   const mcp = createMcpHandler({
-    serverInfo: { name: 'stitchkit-starter', version: '0.1.0' },
+    serverInfo: { name: appIdentity.slug, version: appIdentity.version },
     auth: () => ({ scope: 'public' }),
     services,
   });
   const openApi = generateOpenApiDocument({
-    info: { title: 'Stitchkit Starter API', version: '0.1.0' },
+    info: { title: `${appIdentity.name} API`, version: appIdentity.version },
     groups: [{ pathPrefix: '/api', services }],
   });
 
@@ -22,7 +24,7 @@ async function main(): Promise<void> {
     groups: [{ pathPrefix: '/api', services }],
     port: env.API_PORT,
     hostname: '0.0.0.0',
-    cors: { origin: '*' },
+    cors: { origin: env.CORS_ORIGIN },
     hooks: { onError },
     logging: { format: env.LOG_FORMAT },
     websocket: socket.websocket,
@@ -30,6 +32,7 @@ async function main(): Promise<void> {
       socket.route,
       openApiRoute('/openapi.json', openApi),
       createMcpHttpRoute({ path: '/mcp', handler: mcp }),
+      ...createLanOnboardingRoutes(),
       {
         method: 'GET',
         path: '/health',
@@ -37,6 +40,16 @@ 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> {
@@ -48,7 +61,9 @@ async function main(): Promise<void> {
 
   process.once('SIGTERM', shutdown);
   process.once('SIGINT', shutdown);
-  console.log(`API listening on http://127.0.0.1:${env.API_PORT}`);
+  console.log(
+    `API listening on ${env.DEV_HTTPS_CERT ? 'https' : 'http'}://127.0.0.1:${env.API_PORT}`,
+  );
 }
 
 main().catch((error: unknown) => {

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

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test';
+import { defineContract } from 'stitchkit/contract';
+import { generateOpenApiDocument, implement } from 'stitchkit/server';
+import { z } from 'zod';
+import { assertSurfaceConformance, buildSurfaceManifest } from './surface-manifest';
+
+const service = implement(
+  defineContract(
+    { prefix: 'notes' },
+    {
+      read: {
+        method: 'GET',
+        path: '/:id',
+        desc: 'Read a note',
+        params: z.object({ id: z.string() }),
+        output: z.object({ id: z.string() }),
+      },
+    },
+  ),
+  { read: ({ params }) => ({ id: params.id }) },
+);
+
+describe('surface conformance', () => {
+  test('derives matching HTTP and MCP discovery identities without calling handlers', () => {
+    const manifest = buildSurfaceManifest([service]);
+    const openApi = generateOpenApiDocument({
+      info: { title: 'Test', version: '1.0.0' },
+      groups: [{ pathPrefix: '/api', services: [service] }],
+    });
+    expect(manifest).toEqual([
+      {
+        service: 'notes',
+        action: 'read',
+        http: [{ method: 'GET', path: '/api/notes/{id}' }],
+        tools: { AGENT: 'read_note', MCP: 'read_note' },
+      },
+    ]);
+    expect(() =>
+      assertSurfaceConformance({ manifest, openApi, mcpToolNames: ['read_note'] }),
+    ).not.toThrow();
+  });
+
+  test('fails with transport-specific expected and actual diagnostics', () => {
+    const manifest = buildSurfaceManifest([service]);
+    expect(() =>
+      assertSurfaceConformance({ manifest, openApi: { paths: {} }, mcpToolNames: [] }),
+    ).toThrow('HTTP/OpenAPI surface mismatch');
+    expect(() =>
+      assertSurfaceConformance({
+        manifest: manifest.map((operation) => ({ ...operation, http: [] })),
+        openApi: { paths: {} },
+        mcpToolNames: ['unexpected'],
+      }),
+    ).toThrow('MCP discovery surface mismatch');
+  });
+
+  test('fails first on duplicate contract identity', () => {
+    expect(() => buildSurfaceManifest([service, service])).toThrow(
+      'Duplicate operation identity notes.read',
+    );
+  });
+});