feat(prototypes): deepen prototype framework

Author: jeanduplessis

apps/prototypes/AGENTS.md

@@ -12,20 +12,30 @@ Run prototype checks explicitly:
 pnpm --filter @kilocode/prototypes dev
 pnpm --filter @kilocode/prototypes build
 pnpm --filter @kilocode/prototypes typecheck
+pnpm --filter @kilocode/prototypes test
+pnpm --filter @kilocode/prototypes validate:routes
+pnpm --filter @kilocode/prototypes validate
 ```
 
 Do not wire this app into root `build`, root `validate`, or default CI unless a future task explicitly changes that policy.
 
+## Prototype host contract
+
+Root layout metadata, viewport, font variable composition, and production web theme ownership belong to the prototype-host module. The layout still imports `@web/app/globals.css` as the concrete theme stylesheet, matching the host contract.
+
+The Next config sets output tracing and Turbopack roots to the monorepo root because this opt-in package imports production web source. Keep those assumptions package-local and do not add the app to root validation by default.
+
 ## Import boundaries
 
 - `@/*` resolves to `apps/prototypes/src/*` for prototype-local code.
 - `@web/*` resolves to `apps/web/src/*` for production web theme, primitives, and product UI.
 
-Prefer prototype-local code for catalog/discovery and review-shell utilities. Keep domain-specific prototype data and preview components colocated with the route that owns them.
+Prefer prototype-local code for catalog/discovery and review-shell utilities. Prototype routes import production web UI primitives and shared visual modules through prototype-local seams such as `@/components/ui/*`, `@/components/shared/*`, or `@/components/KiloCrabIcon`; only those bridge files should import `@web/components/*` directly. Keep domain-specific prototype data and preview components colocated with the route that owns them.
 
 ## Folder conventions
 
 - Add prototype routes as `src/app/<prototype-slug>/page.tsx`.
+- Run `pnpm --filter @kilocode/prototypes validate:routes` to check route folder shape and metadata before review. Run `pnpm --filter @kilocode/prototypes validate` for the full opt-in prototype framework gate.
 - Add optional route metadata beside the page when catalog copy/tags are needed.
 - Keep fixtures, client wrappers, and preview components inside the route folder unless another prototype proves the abstraction reusable.
 - Shared prototype-kit primitives belong in `src/` outside app route folders.

apps/prototypes/README.md

@@ -12,18 +12,28 @@ Run commands explicitly; the root `build`, `validate`, and default CI flows do n
 pnpm --filter @kilocode/prototypes dev
 pnpm --filter @kilocode/prototypes build
 pnpm --filter @kilocode/prototypes typecheck
+pnpm --filter @kilocode/prototypes test
+pnpm --filter @kilocode/prototypes validate:routes
+pnpm --filter @kilocode/prototypes validate
 ```
 
+## Prototype host contract
+
+The root layout uses a prototype-host module for metadata, viewport, font variable composition, and the production web theme contract. The theme source is the production web globals stylesheet (`@web/app/globals.css`) so prototypes stay visually faithful to production UI without redefining tokens.
+
+The Next config sets output tracing and Turbopack roots to the monorepo root because the app intentionally imports production web source. Keep that setup local to this opt-in package; do not enroll prototypes in root build, root validate, or default CI unless a future task explicitly changes the policy.
+
 ## Import aliases
 
 - `@/*` points to prototype-local source in `apps/prototypes/src/*`.
 - `@web/*` points to production web source in `apps/web/src/*`.
 
-Use `@/*` for prototype host code, discovery, catalog, and shared prototype-kit utilities. Use `@web/*` only when importing production web theme, primitives, or existing product UI needed to keep a prototype faithful.
+Use `@/*` for prototype host code, discovery, catalog, shared prototype-kit utilities, and production web component bridges. Prototype routes should import UI primitives and shared visual modules through prototype-local seams such as `@/components/ui/*`, `@/components/shared/*`, or `@/components/KiloCrabIcon`; the bridge files own direct `@web/components/*` imports. Use direct `@web/*` imports only for non-component production web contracts such as the shared theme stylesheet.
 
 ## Folder conventions
 
 - Prototype routes live under `src/app/<prototype-slug>/`.
+- Run `pnpm --filter @kilocode/prototypes validate:routes` to check route folder shape and metadata before review. Run `pnpm --filter @kilocode/prototypes validate` for the full opt-in prototype framework gate.
 - Keep prototype-specific fixtures, role logic, preview components, and metadata colocated with that route.
 - Shared prototype-host utilities live under `src/` outside route folders.
 - Do not introduce a central manifest until multiple durable prototypes prove the need.

apps/prototypes/package.json

@@ -5,7 +5,11 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "typecheck": "tsgo --noEmit"
+    "typecheck": "tsgo --noEmit",
+    "test": "tsx --test src/lib/*.test.ts src/components/prototype-kit/*.test.ts",
+    "check:import-seams": "node scripts/check-import-seams.mjs",
+    "validate:routes": "tsx scripts/validate-routes.ts",
+    "validate": "pnpm run check:import-seams && pnpm run validate:routes && pnpm run test && pnpm run typecheck"
   },
   "dependencies": {
     "@radix-ui/react-dialog": "^1.1.15",

apps/prototypes/scripts/check-import-seams.mjs

@@ -0,0 +1,60 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+
+const root = new URL('../', import.meta.url).pathname;
+const srcDir = join(root, 'src');
+const allowedDirectWebComponentImporters = new Set([
+  'src/components/KiloCrabIcon.tsx',
+  'src/components/shared/Banner.tsx',
+]);
+
+const allowedDirectWebComponentPrefixes = ['src/components/ui/'];
+const sourceExtensions = new Set(['.ts', '.tsx', '.js', '.jsx']);
+const webComponentImportPattern = /from\s+['"]@web\/components\//g;
+
+async function collectSourceFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async entry => {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) return collectSourceFiles(path);
+      if (!sourceExtensions.has(extname(entry.name))) return [];
+      return [path];
+    })
+  );
+
+  return files.flat();
+}
+
+function isAllowedDirectImporter(relativePath) {
+  return (
+    allowedDirectWebComponentImporters.has(relativePath) ||
+    allowedDirectWebComponentPrefixes.some(prefix => relativePath.startsWith(prefix))
+  );
+}
+
+const violations = [];
+
+for (const file of await collectSourceFiles(srcDir)) {
+  const relativePath = relative(root, file);
+  if (isAllowedDirectImporter(relativePath)) continue;
+
+  const source = await readFile(file, 'utf8');
+  if (!webComponentImportPattern.test(source)) continue;
+
+  violations.push(relativePath);
+  webComponentImportPattern.lastIndex = 0;
+}
+
+if (violations.length > 0) {
+  console.error(
+    'Prototype Routes must import production web components through prototype-local seams.'
+  );
+  console.error(
+    'Move these imports behind src/components/ui/*, src/components/shared/*, or another approved bridge:'
+  );
+  for (const violation of violations) console.error(`- ${violation}`);
+  process.exit(1);
+}
+
+console.log('Prototype production web component imports use approved local seams.');

apps/prototypes/scripts/validate-routes.ts

@@ -0,0 +1,26 @@
+import { readdirSync } from 'fs';
+import { join } from 'path';
+import { validatePrototypeRoute } from '../src/lib/prototype-route-authoring';
+
+const appDir = join(process.cwd(), 'src/app');
+const routeSlugs = readdirSync(appDir, { withFileTypes: true })
+  .filter(entry => entry.isDirectory())
+  .map(entry => entry.name);
+
+const results = routeSlugs.map(slug => validatePrototypeRoute({ appDir, slug }));
+const invalidResults = results.filter(result => !result.valid);
+
+for (const result of results) {
+  if (result.issues.length === 0) continue;
+
+  console.log(`Prototype route ${result.slug}:`);
+  for (const issue of result.issues) {
+    console.log(`- ${issue.severity.toUpperCase()} ${issue.code}: ${issue.message}`);
+  }
+}
+
+if (invalidResults.length > 0) {
+  process.exit(1);
+}
+
+console.log(`Validated ${results.length} prototype route${results.length === 1 ? '' : 's'}.`);

apps/prototypes/src/app/kiloclaw-org-billing/components.tsx

@@ -34,29 +34,29 @@ import {
   Users,
 } from 'lucide-react';
 import { cn } from '@/lib/utils';
-import { Button } from '@web/components/ui/button';
-import { Badge } from '@web/components/ui/badge';
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@web/components/ui/card';
-import {
-  Table,
-  TableBody,
-  TableCell,
-  TableHead,
-  TableHeader,
-  TableRow,
-} from '@web/components/ui/table';
-import { Banner } from '@web/components/shared/Banner';
-import { Tabs, TabsContent, TabsList, TabsTrigger } from '@web/components/ui/tabs';
-import { Switch } from '@web/components/ui/switch';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import {
   Dialog,
   DialogContent,
   DialogDescription,
   DialogFooter,
   DialogHeader,
   DialogTitle,
-} from '@web/components/ui/dialog';
-import KiloCrabIcon from '@web/components/KiloCrabIcon';
+} from '@/components/ui/dialog';
+import { Switch } from '@/components/ui/switch';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import KiloCrabIcon from '@/components/KiloCrabIcon';
+import { Banner } from '@/components/shared/Banner';
 import {
   type AdminBillingStatus,
   type AssociatedUser,