@craft-ts/dev-tools 0.7.0-beta.15 → 0.7.0-beta.17

package/src/scripts/create/create-project.js

@@ -1,9 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import { execFileSync } from 'node:child_process';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { runArchitectureMigration } from '../architecture/migrate-architecture.js';
-export const CRAFT_TS_STARTER_VERSION = '^0.7.0-beta.13';
+export const CRAFT_TS_STARTER_VERSION = '^0.7.0-beta.15';
 export const EFFECT_V4_VERSION = '^4.0.0-rc.110';
 const DEFAULT_AGENTS = ['codex'];
 const GENERATED_GITIGNORE = `node_modules/
@@ -88,23 +88,105 @@ This project deliberately uses Effect v4 (effect@${EFFECT_V4_VERSION}) and
 Do not silently replace Effect v4 APIs with v3 examples. Confirm a symbol in
 the installed package before using it.
 `;
-const AGENTS_MD = (mode, config) => `# CraftTS project
+function referenceAgentGuidance(config) {
+    if (!config || (!config.references.craftTs && !config.references.effectTs))
+        return '';
+    const root = config.workspace.kind === 'nx' ? '../../.references' : '.references';
+    const entries = [
+        config.references.craftTs ? `- CraftTS source: \`${root}/craft-ts\`` : '',
+        config.references.effectTs ? `- EffectTS source: \`${root}/effect-ts\`` : '',
+    ].filter(Boolean);
+    return `
+## Local source references
+
+The following repositories are cloned for agent context only:
+${entries.join('\n')}
+Use them to inspect implementations, types, tests and examples when the
+installed package or project documentation is not enough. The application must
+always import CraftTS and EffectTS from the npm dependencies declared in
+\`package.json\`; do not add TypeScript, Vite or package \`file:\` aliases to
+these clones.
+`;
+}
+function agentsMd(mode, config) {
+    const frontend = config?.frontendRuntime ?? (mode === 'effect' ? 'effect' : 'plain');
+    const backend = config?.backendRuntime ?? 'none';
+    const i18n = config?.i18n.enabled ?? true;
+    const designSystem = config?.designSystem !== 'none';
+    const typedCss = config?.typedCss ?? true;
+    const effectFrontend = frontend === 'effect';
+    const effectBackend = backend === 'effect';
+    const effect = effectFrontend || effectBackend;
+    const effectSkillPaths = (config?.agents ?? []).map((agent) => agent === 'codex'
+        ? '.agents/skills/craft-ts-effect-v4/SKILL.md'
+        : agent === 'cursor'
+            ? '.cursor/skills/craft-ts-project/SKILL.md'
+            : agent === 'claude-code'
+                ? '.claude/skills/craft-ts-effect-v4/SKILL.md'
+                : '.gemini/skills/craft-ts-effect-v4/SKILL.md');
+    const effectSkillLine = effectSkillPaths.length
+        ? `Read the Effect-specific guidance in ${effectSkillPaths.map((path) => `\`${path}\``).join(', ')}.`
+        : 'Use the Effect v4 guidance in the project documentation when adding Effect code.';
+    const verify = [
+        'npm run lint',
+        'npm run typecheck',
+        'npm run typecheck-spec',
+        ...(i18n ? ['npm run i18n:check', 'npm run i18n:test'] : []),
+        ...(typedCss ? ['npm run style:check'] : []),
+        ...(backend !== 'none' ? ['npm run server:test'] : []),
+        ...(effect ? ['npm run effect-check'] : []),
+        'npm test',
+        'npm run architecture',
+        'npm run typecheck-architecture',
+        'npm run build',
+    ];
+    const effectGuidance = effect
+        ? `
+## Effect boundary
+
+${effectFrontend ? '- Effect v4 is enabled in the browser; use `queryEffect` and the installed Craft Effect bridge.' : '- The browser runtime is plain; keep Effect imports out of browser components.'}
+${effectBackend ? '- Effect v4 is enabled on the backend; keep server Effects in `src/server/`, provide services through `Layer`, and run `npm run effect-check` after changes.' : '- The backend does not use Effect; do not add Effect dependencies or server Effects unless the runtime choice changes.'}
+${effectSkillLine}
+`
+        : `
+## Effect boundary
+
+Effect is not selected in this starter. Keep the application on the plain
+CraftTS runtime and do not add Effect imports or dependencies incidentally.
+`;
+    return `# CraftTS project
 
-This project was created with \`craft create\` using frontend **${config?.frontendRuntime ?? (mode === 'effect' ? 'effect' : 'plain')}** and backend **${config?.backendRuntime ?? 'none'}** runtimes.
+This project was created with \`craft create\`. Treat this file as the project
+guide for coding agents: it records the selected runtime and feature surfaces.
+
+## Selected configuration
+
+- Frontend runtime: **${frontend}**
+- Backend runtime: **${backend}**
+- Type-safe i18n: **${i18n ? 'enabled' : 'disabled'}**
+- Design system: **${designSystem ? 'enabled' : 'disabled'}**
+- Typed CSS: **${typedCss ? 'enabled' : 'disabled'}**
 
 Read \`.agents/skills/craft-ts-project/SKILL.md\` before changing application
-code. ${config?.i18n.enabled ? 'The type-safe i18n contract lives in `src/i18n/`; run `npm run i18n:check` and `npm run i18n:test` when changing it.' : ''} ${mode === 'effect' || config?.backendRuntime === 'effect' ? 'Effect-specific guidance is in `.agents/skills/craft-ts-effect-v4/SKILL.md`.' : ''}
+code. ${i18n ? 'Translation keys live in `src/i18n/`; run `npm run i18n:check` and `npm run i18n:test` after changes.' : 'This starter has no i18n surface; do not add translation files unless the project configuration changes.'}
+${effectGuidance}
 
-## Runtime boundaries
+## Workflow
 
-Frontend runtime: ${config?.frontendRuntime ?? (mode === 'effect' ? 'effect' : 'plain')}.
-Backend runtime: ${config?.backendRuntime ?? 'none'}. A backend Effect runtime
-never authorizes importing Effect into browser components.
+Use Craft primitives and yield every Craft reader. Keep the browser, server and
+transport boundaries aligned with the selected runtimes. The architecture
+suite is a graph contract: run \`npm run architecture\` after structural
+changes, and do not add a test per feature or a rule for a smell already
+covered by the baseline helpers.
 
-The architecture suite is a graph contract. Run \`npm run architecture\`;
-do not add a test per feature. Add a rule only for a recurring product-level
-dependency smell not already covered by the baseline helpers.
-`;
+## Verification
+
+Run the checks relevant to this generated configuration:
+
+${verify.map((command) => `- \`${command}\``).join('\n')}
+${referenceAgentGuidance(config)}`;
+}
+const AGENTS_MD = agentsMd;
 function json(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -115,15 +197,9 @@ function packageJson(context) {
     const hasI18n = context.config.i18n.enabled;
     const hasTypedCss = context.config.typedCss;
     const hasServer = context.config.backendRuntime !== 'none';
-    const localReferences = context.config.references.mode === 'local';
-    const sourceReferences = context.config.references.mode === 'source';
     const packageVersion = context.packageVersion ?? CRAFT_TS_STARTER_VERSION;
-    const craftPackage = (name) => (localReferences || sourceReferences) && context.config.references.craftTs
-        ? `file:.references/craft-ts/${sourceReferences ? craftReferencePackagePath(name) : localCraftReferencePackagePath(name)}`
-        : packageVersion;
-    const effectPackage = localReferences && context.config.references.effectTs
-        ? 'file:.references/effect-ts/packages/effect'
-        : EFFECT_V4_VERSION;
+    const craftPackage = () => packageVersion;
+    const effectPackage = EFFECT_V4_VERSION;
     return json({
         name: context.projectName,
         private: true,
@@ -170,37 +246,36 @@ function packageJson(context) {
             'typecheck-architecture': 'tsc -p tsconfig.architecture.json --noEmit',
         },
         dependencies: {
-            '@craft-ts/component': craftPackage('component'),
-            '@craft-ts/core': craftPackage('core'),
-            ...(hasI18n ? { '@craft-ts/i18n': craftPackage('i18n') } : {}),
-            ...(hasTypedCss ? { '@craft-ts/style': craftPackage('style') } : {}),
+            '@craft-ts/component': craftPackage(),
+            '@craft-ts/core': craftPackage(),
+            ...(hasI18n ? { '@craft-ts/i18n': craftPackage() } : {}),
+            ...(hasTypedCss ? { '@craft-ts/style': craftPackage() } : {}),
             ...(hasEffect && hasI18n
-                ? { '@craft-ts/i18n-effect': craftPackage('i18n-effect') }
+                ? { '@craft-ts/i18n-effect': craftPackage() }
                 : {}),
             ...(hasEffect
-                ? { '@craft-ts/effect': craftPackage('effect'), effect: effectPackage }
+                ? { '@craft-ts/effect': craftPackage(), effect: effectPackage }
                 : {}),
         },
         devDependencies: {
-            '@craft-ts/dev-tools': craftPackage('dev-tools'),
-            '@craft-ts/mcp': craftPackage('mcp'),
-            '@craft-ts/function-registry-mcp': craftPackage('function-registry-mcp'),
-            '@craft-ts/log-mcp': craftPackage('log-mcp'),
-            '@craft-ts/log-server': craftPackage('log-server'),
-            effect: effectPackage,
+            '@craft-ts/dev-tools': craftPackage(),
+            '@craft-ts/mcp': craftPackage(),
+            '@craft-ts/function-registry-mcp': craftPackage(),
+            '@craft-ts/log-mcp': craftPackage(),
+            '@craft-ts/log-server': craftPackage(),
+            ...(hasEffect ? { effect: effectPackage } : {}),
             ...(hasTypedCss
-                ? { '@craft-ts/style-testing': craftPackage('style-testing') }
+                ? { '@craft-ts/style-testing': craftPackage() }
                 : {}),
             '@playwright/test': '^1.52.0',
             '@types/node': '^22.0.0',
+            'aria-query': '^5.3.2',
             jsdom: '^27.1.0',
             rxjs: '^7.8.0',
             tslib: '^2.3.0',
             ...(hasEffect
                 ? {
-                    '@effect/tsgo': localReferences && context.config.references.effectTs
-                        ? 'file:.references/effect-ts/packages/tsgo'
-                        : '^0.24.3',
+                    '@effect/tsgo': '^0.24.3',
                     '@typescript/native': 'npm:typescript@7.0.2',
                 }
                 : {}),
@@ -215,61 +290,10 @@ function packageJson(context) {
         },
     });
 }
-function craftReferencePackagePath(name) {
-    if (name === 'mcp' ||
-        name === 'function-registry-mcp' ||
-        name === 'log-mcp') {
-        return `packages/${name}`;
-    }
-    if (name === 'log-server')
-        return 'apps/log-server';
-    return `libs/${name}`;
-}
-export function localCraftReferencePackagePath(name) {
-    if (name === 'mcp' ||
-        name === 'function-registry-mcp' ||
-        name === 'log-mcp') {
-        return `packages/${name}`;
-    }
-    if (name === 'log-server')
-        return 'apps/log-server';
-    return `dist/libs/${name}`;
-}
-function sourceReferenceRoot(context) {
-    return context.config.workspace.kind === 'nx'
-        ? '../../.references/craft-ts'
-        : './.references/craft-ts';
-}
-function sourceReferenceAliases(context) {
-    const root = sourceReferenceRoot(context);
-    const aliases = {
-        '@craft-ts/core': `${root}/libs/core/src/index.ts`,
-        '@craft-ts/component': `${root}/libs/component/src/index.ts`,
-        '@craft-ts/i18n': `${root}/libs/i18n/src/index.ts`,
-        '@craft-ts/style': `${root}/libs/style/src/index.ts`,
-        '@craft-ts/style/vite': `${root}/libs/style/src/plugin/vite.ts`,
-        '@craft-ts/style-testing': `${root}/libs/style-testing/src/index.ts`,
-        '@craft-ts/dev-tools': `${root}/libs/dev-tools/src/index.ts`,
-    };
-    if (context.config.frontendRuntime === 'effect' ||
-        context.config.backendRuntime === 'effect') {
-        aliases['@craft-ts/effect'] = `${root}/libs/effect/src/index.ts`;
-    }
-    if (context.config.i18n.enabled &&
-        (context.config.frontendRuntime === 'effect' ||
-            context.config.backendRuntime === 'effect')) {
-        aliases['@craft-ts/i18n-effect'] = `${root}/libs/i18n-effect/src/index.ts`;
-    }
-    return aliases;
-}
 function tsconfig(context) {
     const hasEffect = context.config.frontendRuntime === 'effect' ||
         context.config.backendRuntime === 'effect';
     const hasServer = context.config.backendRuntime !== 'none';
-    const sourceAliases = context.config.references.mode === 'source' &&
-        context.config.references.craftTs
-        ? Object.fromEntries(Object.entries(sourceReferenceAliases(context)).map(([name, path]) => [name, [path]]))
-        : undefined;
     return json({
         compilerOptions: {
             target: 'ES2022',
@@ -282,7 +306,6 @@ function tsconfig(context) {
             erasableSyntaxOnly: false,
             skipLibCheck: true,
             types: ['node'],
-            ...(sourceAliases ? { paths: sourceAliases } : {}),
         },
         references: [
             { path: './tsconfig.app.json' },
@@ -308,39 +331,49 @@ const tsconfigSpec = `{
 }\n`;
 const tsconfigEffect = `{
   "extends": "./tsconfig.json",
-  "compilerOptions": { "noEmit": true },
+  "compilerOptions": {
+    "noEmit": true,
+    "plugins": [{
+      "name": "@effect/language-service",
+      "diagnostics": true,
+      "diagnosticsName": true,
+      "overrides": [{
+        "include": ["src/**/*.ts"],
+        "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"],
+        "options": {
+          "diagnosticSeverity": {
+            "floatingEffect": "error",
+            "missingEffectContext": "error",
+            "missingEffectError": "error",
+            "missingLayerContext": "error",
+            "missingReturnYieldStar": "error",
+            "missingStarInYieldEffectGen": "error",
+            "outdatedApi": "error",
+            "unsafeEffectTypeAssertion": "error",
+            "asyncFunction": "warning",
+            "newPromise": "warning",
+            "nodeBuiltinImport": "warning",
+            "preferSchemaOverJson": "warning"
+          }
+        }
+      }]
+    }]
+  },
   "include": ["src/**/*.ts"],
   "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
 }\n`;
 function viteConfig(context) {
     const typedCss = context.config.typedCss;
     const hasServer = context.config.backendRuntime !== 'none';
-    const sourceReferences = context.config.references.mode === 'source' &&
-        context.config.references.craftTs;
-    const sourceRoot = sourceReferenceRoot(context);
-    const styleImport = sourceReferences
-        ? `import { craftStyle } from '${sourceRoot}/libs/style/src/plugin/vite.ts';`
-        : "import { craftStyle } from '@craft-ts/style/vite';";
-    const sourceAliasEntries = Object.entries(sourceReferenceAliases(context))
-        .map(([name, path]) => `    ${JSON.stringify(name)}: resolvePath(import.meta.dirname, ${JSON.stringify(path)})`)
-        .join(',\n');
-    const styleAliasEntries = sourceReferences
-        ? sourceAliasEntries
-        : `    '@craft-ts/style': resolvePath(import.meta.dirname, 'node_modules/@craft-ts/style/src/index.js')`;
-    const sourceAliasConfig = sourceReferences
-        ? `resolve: {
-    alias: {
-${sourceAliasEntries}
-    },
-  },`
-        : '';
+    const styleImport = "import { craftStyle } from '@craft-ts/style/vite';";
+    const styleAliasEntries = `    '@craft-ts/style': resolvePath(import.meta.dirname, 'node_modules/@craft-ts/style/src/index.js')`;
     const stylePlugin = typedCss
         ? `    craftStyle({ dumpPath: '.craft/style-graph.json', alias: {
 ${styleAliasEntries}
     } }),`
         : '';
     return `import { readFileSync } from 'node:fs';
-import { resolve as resolvePath } from 'node:path';
+${typedCss ? "import { resolve as resolvePath } from 'node:path';\n" : ''}
 import { defineConfig, type ViteDevServer } from 'vite';
 ${typedCss ? styleImport : ''}
 
@@ -378,9 +411,17 @@ ${hasServer
   return {
     name: 'craft-starter-server-functions',
     async configureServer(server: ViteDevServer) {
-      const module = await server.ssrLoadModule('/src/server/server.ts') as typeof import('./src/server/server');
+      const module = await server.ssrLoadModule('/src/server/node-http.ts') as typeof import('./src/server/node-http');
       server.middlewares.use('/__server-functions', (request, response) => {
-        void module.handleRequest(request, response);
+        void module.handleRequest(request, response).catch((error: unknown) => {
+          if (response.headersSent) {
+            response.destroy();
+            return;
+          }
+          response.statusCode = 500;
+          response.end('Internal Server Error');
+          console.error(error);
+        });
       });
     },
   };
@@ -401,7 +442,6 @@ ${hasServer ? '    serverFunctionsPlugin(),' : ''}
     port: starterPort,
     forwardConsole: true,
   },
-${sourceAliasConfig}
   build: { target: 'es2022' },
 });
 `;
@@ -553,6 +593,12 @@ ${effect ? '' : "      'craft-ts/no-effect-import-in-frontend': 'error',"}
   },
   {
     files: ['src/**/*.spec.ts', 'src/**/*.test.ts'],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.spec.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
     rules: {
       'craft-ts/no-async-await': 'off',
       'craft-ts/no-throw': 'off',
@@ -564,6 +610,7 @@ ${effect ? '' : "      'craft-ts/no-effect-import-in-frontend': 'error',"}
 ${backendEffect
     ? `  {
     files: ['src/server/**/*.ts', 'src/**/*.fn-serveur.ts', 'src/**/*.mw-serveur.ts'],
+    ignores: ['src/**/*.spec.ts', 'src/**/*.test.ts'],
     plugins: { 'craft-ts': craftRules },
     languageOptions: {
       parserOptions: {
@@ -632,7 +679,8 @@ const styles = `:root {
 body { margin: 0; min-width: 320px; }
 a { color: #2457d6; }
 main { max-width: 860px; margin: 0 auto; padding: 3rem 1.25rem; }
-nav { display: flex; gap: 1rem; padding: 1rem 1.25rem; background: white; border-bottom: 1px solid #e3e7ef; }
+nav { display: flex; align-items: center; gap: 1rem; padding: 1rem 1.25rem; background: white; border-bottom: 1px solid #e3e7ef; }
+.starter-experimental-badge { display: inline-flex; align-items: center; margin-left: auto; padding: .25rem .55rem; border: 1px solid #f0c36d; border-radius: 999px; color: #7a4b00; background: #fff8e6; font-size: .75rem; font-weight: 600; line-height: 1.2; white-space: nowrap; }
 button:focus-visible, a:focus-visible { outline: 3px solid #7aa2ff; outline-offset: 3px; }
 .heading { font-size: var(--craft-font-size-heading); line-height: var(--craft-line-height-heading); font-weight: 700; }
 body, .body { font-size: var(--craft-font-size-body); line-height: var(--craft-line-height-body); }
@@ -1032,6 +1080,7 @@ function appTs(context) {
   div,
   main,
   nav,
+  span,
 } from '@craft-ts/component';
 import { CraftRouterLink } from '@craft-ts/core';
 ${uiImport}
@@ -1046,6 +1095,7 @@ export const App = craftComponent(
         a('home', {}, 'Home').pipe(CraftRouterLink({ to: '' })),
         a('services', {}, 'Services').pipe(CraftRouterLink({ to: 'services' })),
         a('about', {}, 'About').pipe(CraftRouterLink({ to: 'about' })),
+        span({ class: 'starter-experimental-badge' }, 'Experimental · feedback welcome'),
       ]),
       main(CraftRouterOutlet()),
     ${themeClose},
@@ -1065,7 +1115,15 @@ function routesTs(context) {
       }),
 `
         : '';
-    return `import { loadCraftComponent } from '@craft-ts/component';
+    const backendEffectErrorHandler = context.config.frontendRuntime === 'plain' &&
+        context.config.backendRuntime === 'effect'
+        ? `    StarterRepositoryError: craftExceptionHandler(function* ({ globalError }) {
+      return globalError();
+    }),
+`
+        : '';
+    return `/* eslint-disable require-yield -- Route exception outcomes are synchronous by design. */
+import { loadCraftComponent } from '@craft-ts/component';
 import {
   assertExhaustiveRouteExceptions,
   craftExceptionHandler,
@@ -1085,6 +1143,7 @@ export const { appRoutes } = craftRoutes('app', [
     ),
   }, {
 ${httpErrorHandler}
+${backendEffectErrorHandler}
 ${welcomeErrorHandler}  }),
   craftRoute('about', {
     ...loadCraftComponent(({ withRetry }) =>
@@ -1200,23 +1259,30 @@ function serverFiles(context) {
         return {};
     const effect = context.config.backendRuntime === 'effect';
     const fnServer = effect
-        ? `import { serverFunction } from '@craft-ts/core';
+        ? `import { serverFunction, type ServerFunctionSuccess } from '@craft-ts/core';
 import { Effect, Schema } from 'effect';
 import { StarterRepository } from './server/repository';
+import { starterMiddleware } from './starter.mw-serveur';
 
 const inputSchema = Schema.toStandardSchemaV1(Schema.Struct({ filter: Schema.String }));
 const outputSchema = Schema.toStandardSchemaV1(Schema.Struct({ title: Schema.String, body: Schema.String }));
 
-export type StarterResponse = { readonly title: string; readonly body: string };
-
 export const getStarterMessage = serverFunction(
   'starter.welcome', inputSchema, { exposure: 'client', output: outputSchema },
-).handler(({ input }) => Effect.gen(function* () {
+).use(starterMiddleware).handler(({ input }) => Effect.gen(function* () {
   const repository = yield* StarterRepository;
   return yield* repository.welcome(input.filter);
-})).exposeErrors({});
+})).exposeErrors({
+  StarterRepositoryError: (errorPayload) => ({
+    code: 'STARTER_REPOSITORY_FAILURE',
+    status: 503,
+    payload: { filter: errorPayload.filter, message: errorPayload.message },
+  }),
+});
+
+export type StarterResponse = ServerFunctionSuccess<typeof getStarterMessage>;
 `
-        : `import { flatMapContext, mapContext, portableServerFunction } from '@craft-ts/core';
+        : `import { flatMapContext, mapContext, portableServerFunction, type SchemaOutput, type ServerFunctionContractOutput, type ServerFunctionSuccess } from '@craft-ts/core';
 import type { StandardSchemaV1 } from '@craft-ts/core';
 import { StarterRepository } from './server/repository';
 
@@ -1224,141 +1290,278 @@ type Input = { readonly filter: string };
 const inputSchema: StandardSchemaV1<Input, Input> = { '~standard': { version: 1, vendor: 'craft-starter', types: undefined,
   validate(value: unknown) { return typeof value === 'object' && value !== null && typeof (value as Input).filter === 'string'
     ? { value: value as Input } : { issues: [{ message: 'filter must be a string' }] }; } } };
-export type StarterResponse = { readonly title: string; readonly body: string };
+const outputSchema: StandardSchemaV1<{ readonly title: string; readonly body: string }, { readonly title: string; readonly body: string }> = { '~standard': { version: 1, vendor: 'craft-starter', types: undefined,
+  validate(value: unknown) { return typeof value === 'object' && value !== null && typeof (value as { title?: unknown }).title === 'string' && typeof (value as { body?: unknown }).body === 'string'
+    ? { value: value as { readonly title: string; readonly body: string } } : { issues: [{ message: 'welcome response must contain title and body' }] }; } } };
 
-export const getStarterMessage = portableServerFunction('starter.welcome', inputSchema, { exposure: 'client' })
+export const getStarterMessage = portableServerFunction('starter.welcome', inputSchema, { exposure: 'client', output: outputSchema })
   .pipe(
     mapContext(({ input }) => ({ normalizedFilter: input.filter.trim() })),
     flatMapContext(() => StarterRepository.welcome()),
   )
-  .handler(async ({ context }) => context.value)
+  .handler(async ({ context }) => context.value as SchemaOutput<typeof outputSchema>)
   .exposeErrors({});
+
+export type StarterResponse = ServerFunctionContractOutput<typeof getStarterMessage['contract']>;
 `;
     const repository = effect
-        ? `import { Context, Effect, Layer } from 'effect';
+        ? `import { Context, Data, Effect, Layer } from 'effect';
 
 export type StarterRepositoryShape = {
-  readonly welcome: (filter: string) => Effect.Effect<{ readonly title: string; readonly body: string }>;
+  readonly welcome: (filter: string) => Effect.Effect<
+    { readonly title: string; readonly body: string },
+    StarterRepositoryError
+  >;
 };
 export class StarterRepository extends Context.Service<StarterRepository, StarterRepositoryShape>()('starter/StarterRepository') {}
+export class StarterRepositoryError extends Data.TaggedError('StarterRepositoryError')<{
+  readonly filter: string;
+  readonly message: string;
+}> {}
+
 export const StarterRepositoryLive = Layer.succeed(StarterRepository, {
-  welcome: (filter) => Effect.succeed({ title: 'Hello from the server', body: 'Effect server function: ' + filter }),
+  welcome: (filter) => Effect.tryPromise({
+    try: () => filter === 'error'
+      ? Promise.reject(new Error('The starter repository failed.'))
+      : Promise.resolve({ title: 'Hello from the server', body: 'Effect server function: ' + filter }),
+    catch: (cause) => new StarterRepositoryError({
+      filter,
+      message: cause instanceof Error ? cause.message : String(cause),
+    }),
+  }),
 });
 `
         : `export const StarterRepository = {
   welcome: async () => ({ value: { title: 'Hello from the server', body: 'Promise server function works.' } }),
 };
 `;
-    let server = '';
-    if (effect) {
-        server = `import { createServer } from '@craft-ts/core';
+    const application = effect
+        ? `import { createServer, type Server } from '@craft-ts/core';
 import { executeEffect } from '@craft-ts/effect';
+${context.config.i18n.enabled ? "import { Layer } from 'effect';\n" : ''}
 import { getStarterMessage } from '../starter.fn-serveur';
 import { StarterRepositoryLive } from './repository';
-import type { IncomingMessage, ServerResponse } from 'node:http';
+${context.config.i18n.enabled ? "import { serverI18nLayer } from './i18n';\n" : ''}
+
+export const runtimeLayer = ${context.config.i18n.enabled ? 'Layer.mergeAll(StarterRepositoryLive, serverI18nLayer)' : 'StarterRepositoryLive'};
+
+export function createApplication(layer = runtimeLayer): Server {
+  return createServer({
+    functions: [getStarterMessage],
+    execute: executeEffect(layer).run,
+    runtimeOptions: {
+      maxBodyBytes: 1_000_000,
+      maxOutputBytes: 1_000_000,
+      timeoutMs: 10_000,
+    },
+  });
+}
 
-export const application = createServer({ functions: [getStarterMessage], execute: executeEffect(StarterRepositoryLive).run });
-export const runtime = StarterRepositoryLive;
-export async function handleRequest(request: IncomingMessage, response: ServerResponse) {
-  const chunks: Buffer[] = [];
-  for await (const chunk of request) chunks.push(Buffer.from(chunk));
-  const host = typeof request.headers.host === 'string' ? request.headers.host : '127.0.0.1';
-  const webResponse = await application.handle(new Request('http://' + host + '/__server-functions', {
-    method: request.method,
-    headers: Object.entries(request.headers).flatMap(([name, value]) => value === undefined ? [] : [[name, Array.isArray(value) ? value.join(', ') : value]]),
-    body: request.method === 'GET' || request.method === 'HEAD' ? undefined : Buffer.concat(chunks),
-  }));
-  response.statusCode = webResponse.status;
-  webResponse.headers.forEach((value, name) => response.setHeader(name, value));
-  response.end(Buffer.from(await webResponse.arrayBuffer()));
+export const application = createApplication();
+`
+        : `import { createServer, type Server } from '@craft-ts/core';
+import { getStarterMessage } from '../starter.fn-serveur';
+
+export function createApplication(): Server {
+  return createServer({
+    functions: [getStarterMessage],
+    runtimeOptions: {
+      maxBodyBytes: 1_000_000,
+      maxOutputBytes: 1_000_000,
+      timeoutMs: 10_000,
+    },
+  });
 }
+
+export const application = createApplication();
 `;
-    }
-    if (!effect) {
-        server = `import { createServer } from '@craft-ts/core';
-import { getStarterMessage } from '../starter.fn-serveur';
+    const nodeHttp = `/* eslint-disable craft-ts/no-async-await -- The Node adapter is an async platform boundary. */
+import { application } from './application';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 
-export const application = createServer({ functions: [getStarterMessage] });
-export async function handleRequest(request: IncomingMessage, response: ServerResponse) {
-  const chunks: Buffer[] = [];
-  for await (const chunk of request) chunks.push(Buffer.from(chunk));
-  const host = typeof request.headers.host === 'string' ? request.headers.host : '127.0.0.1';
-  const webResponse = await application.handle(new Request('http://' + host + '/__server-functions', {
-    method: request.method,
-    headers: Object.entries(request.headers).flatMap(([name, value]) => value === undefined ? [] : [[name, Array.isArray(value) ? value.join(', ') : value]]),
-    body: request.method === 'GET' || request.method === 'HEAD' ? undefined : Buffer.concat(chunks),
-  }));
+export async function handleRequest(request: IncomingMessage, response: ServerResponse): Promise<void> {
+  const abortController = new AbortController();
+  const abort = () => abortController.abort();
+  const close = () => {
+    if (!request.complete) abort();
+  };
+  request.once('aborted', abort);
+  request.once('close', close);
+  try {
+    const webResponse = await application.handle(toWebRequest(request, abortController.signal));
+    await writeWebResponse(webResponse, response, request.method === 'HEAD');
+  } finally {
+    request.off('aborted', abort);
+    request.off('close', close);
+  }
+}
+
+function toWebRequest(request: IncomingMessage, signal: AbortSignal): Request {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (value !== undefined) headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+  }
+  const method = request.method ?? 'GET';
+  const hasBody = method !== 'GET' && method !== 'HEAD';
+  return new Request(
+    'http://' + (request.headers.host ?? '127.0.0.1') + (request.url ?? '/'),
+    {
+      method,
+      headers,
+      signal,
+      ...(hasBody ? { body: request as unknown as BodyInit, duplex: 'half' } : {}),
+    } as RequestInit,
+  );
+}
+
+async function writeWebResponse(
+  webResponse: Response,
+  response: ServerResponse,
+  head: boolean,
+): Promise<void> {
   response.statusCode = webResponse.status;
   webResponse.headers.forEach((value, name) => response.setHeader(name, value));
+  if (head || webResponse.body === null) {
+    response.end();
+    return;
+  }
   response.end(Buffer.from(await webResponse.arrayBuffer()));
 }
 `;
-    }
-    const client = `import { createServerFunctionClient, craftUnique } from '@craft-ts/core';
+    const client = `import { createServerFunctionClient, craftUnique, type ServerFunctionClient } from '@craft-ts/core';
 import type { getStarterMessage as ServerGetStarterMessage, StarterResponse } from './starter.fn-serveur';
 
 export type { StarterResponse };
-export const getStarterMessage = createServerFunctionClient<typeof ServerGetStarterMessage>(craftUnique('starter.welcome'));
+const starterMessageTransport = createServerFunctionClient<typeof ServerGetStarterMessage>(craftUnique('starter.welcome'));
+export const getStarterMessage = starterMessageTransport as ServerFunctionClient<typeof ServerGetStarterMessage, StarterResponse>;
+`;
+    const compatibilityServer = `export { application, createApplication } from './application';
+${effect ? 'export { runtimeLayer } from \'./application\';\n' : ''}export { handleRequest } from './node-http';
 `;
     return {
         'src/server/repository.ts': repository,
-        'src/server/server.ts': server,
+        'src/server/application.ts': application,
+        'src/server/node-http.ts': nodeHttp,
+        'src/server/server.ts': compatibilityServer,
         'src/starter.fn-serveur.ts': fnServer,
         'src/starter.fn-client.ts': client,
         ...(effect && context.config.i18n.enabled
             ? {
-                'src/server/i18n.ts': "import { provideI18nRuntime } from '@craft-ts/i18n-effect';\nimport { i18n } from '../i18n/runtime';\nexport const serverI18nLayer = provideI18nRuntime(i18n);\nexport { translateEffect } from '../i18n/effect';\n",
+                'src/server/i18n.ts': "import { provideI18nRuntime } from '@craft-ts/i18n-effect';\nimport { i18n } from '../i18n/runtime';\n\nexport const serverI18nLayer = provideI18nRuntime(i18n);\n",
             }
             : {}),
         ...(effect
             ? {
-                'src/starter.mw-serveur.ts': "import { Effect } from 'effect';\nimport { effectServerMiddleware } from '@craft-ts/effect';\nexport const starterMiddleware = effectServerMiddleware('starter.middleware', () => Effect.succeed({ value: undefined }));\n",
+                'src/starter.mw-serveur.ts': "import { Effect } from 'effect';\nimport { effectServerMiddleware } from '@craft-ts/effect';\n\nexport const starterMiddleware = effectServerMiddleware('starter.middleware', () =>\n  Effect.gen(function* () {\n    yield* Effect.log('starter middleware executed');\n    return { value: undefined };\n  }),\n);\n",
             }
             : {}),
         'vitest.server.config.ts': `import { defineConfig } from 'vitest/config';
 export default defineConfig({ test: { name: 'craft-starter-server', globals: true, environment: 'node', include: ['src/server/**/*.spec.ts'] } });
 `,
-        'src/server/server.spec.ts': `import { describe, expect, it } from 'vitest';
-import { application } from './server';
+        'src/server/server.spec.ts': serverSpec(context),
+    };
+}
+function serverSpec(context) {
+    const effectFailure = context.config.backendRuntime === 'effect'
+        ? `
+  it('exposes the typed Effect repository failure', async () => {
+    const response = await application.handle(new Request('http://127.0.0.1/__server-functions', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id: 'starter.welcome', input: { filter: 'error' } }),
+    }));
+    expect(response.status).toBe(503);
+    await expect(response.json()).resolves.toMatchObject({
+      error: { _tag: 'StarterRepositoryError', code: 'STARTER_REPOSITORY_FAILURE', filter: 'error' },
+    });
+  });
+`
+        : '';
+    return `import { createServer as createNodeServer } from 'node:http';
+import { describe, expect, it } from 'vitest';
+import { createServer, serverFunction, type StandardSchemaV1 } from '@craft-ts/core';
+import { application, handleRequest } from './server';
+
+const invalidInputSchema: StandardSchemaV1<unknown, unknown> = {
+  '~standard': { version: 1, vendor: 'craft-starter-test', types: undefined,
+    validate(value: unknown) { return { value }; } },
+};
+const invalidOutputSchema: StandardSchemaV1<{ readonly required: string }, { readonly required: string }> = {
+  '~standard': { version: 1, vendor: 'craft-starter-test', types: undefined,
+    validate(value: unknown) {
+      return typeof value === 'object' && value !== null && typeof (value as { required?: unknown }).required === 'string'
+        ? { value: value as { readonly required: string } }
+        : { issues: [{ message: 'required must be a string' }] };
+    } },
+};
+const invalidOutput = serverFunction(
+  'starter.invalid-output',
+  invalidInputSchema,
+  { exposure: 'server', output: invalidOutputSchema },
+).handler(() => ({ required: 123 })).exposeErrors({});
 
 describe('server function registry', () => {
-  it('registers the starter function', () => expect(application).toBeDefined());
+  it('invokes the starter function through the registry', async () => {
+    await expect(application.invoke('starter.welcome', { filter: 'Ada' })).resolves.toMatchObject({
+      title: 'Hello from the server',
+    });
+  });
+
+  it('rejects invalid input', async () => {
+    await expect(application.invoke('starter.welcome', { filter: 123 })).rejects.toThrow(
+      'CRAFT_SERVER_FUNCTION_INPUT_INVALID',
+    );
+  });
+
+  it('rejects invalid output', async () => {
+    const server = createServer({ functions: [invalidOutput] });
+    await expect(server.invoke('starter.invalid-output', undefined)).rejects.toThrow(
+      'CRAFT_SERVER_FUNCTION_OUTPUT_INVALID',
+    );
+  });
+${effectFailure}
+
+  it('serves a real HTTP request through the Node adapter', async () => {
+    const nodeServer = createNodeServer((request, response) => {
+      void handleRequest(request, response).catch((error: unknown) => {
+        if (!response.headersSent) response.statusCode = 500;
+        response.end('Internal Server Error');
+        throw error;
+      });
+    });
+    await new Promise<void>((resolve) => nodeServer.listen(0, '127.0.0.1', resolve));
+    const address = nodeServer.address();
+    if (!address || typeof address === 'string') throw new Error('Server did not start.');
+    try {
+      const response = await fetch('http://127.0.0.1:' + address.port + '/__server-functions', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ id: 'starter.welcome', input: { filter: 'Ada' } }),
+      });
+      expect(response.status).toBe(200);
+      await expect(response.json()).resolves.toMatchObject({ title: 'Hello from the server' });
+    } finally {
+      await new Promise<void>((resolve, reject) => nodeServer.close((error) => error ? reject(error) : resolve()));
+    }
+  });
+
+  it('rejects unsupported method and content type', async () => {
+    await expect(application.handle(new Request('http://127.0.0.1/__server-functions'))).resolves.toHaveProperty('status', 405);
+    await expect(application.handle(new Request('http://127.0.0.1/__server-functions', {
+      method: 'POST',
+      headers: { 'content-type': 'text/plain' },
+      body: '{}',
+    }))).resolves.toHaveProperty('status', 415);
+  });
 });
-`,
-    };
+`;
 }
-export const EFFECT_REFERENCE_PATHS = [
-    'apps/demo-effect',
-    'apps/quickstart-effect',
-    'apps/demo-with-server-function',
-    'apps/docs/learn-effect',
-    'apps/docs/tsconfig.learn-effect.json',
-    'apps/docs/tests/snippets/learn-effect',
-    'apps/docs/guide/advanced/effect.md',
-    'apps/docs/guide/i18n/effect.md',
-    'apps/docs/guide/reactivity/craft-effect.md',
-    'apps/docs/guide/testing/architecture/craft-effect-imperative-sync.md',
-    'apps/docs/guide/testing/architecture/craft-effect-network.md',
-    'apps/docs/resources/effect-adoption.md',
-    'apps/docs/resources/effect-compatibility.md',
-    'apps/docs/public/assets/effect-logo-black.png',
-    'apps/docs/public/assets/effect-craft-ts-hover.png',
-    'apps/docs/public/assets/effect-craft-mark-hover.png',
-    'libs/effect',
-    'libs/i18n-effect',
-    'packages/mcp/skills/craft-ts-effect-v4',
-    'tools/effect-diagnostics',
-    'tools/compile-learn-effect-examples.mjs',
-    'tools/run-effect-tsgo.mjs',
-    'tools/effect-typecost',
-];
 function referenceFiles(context) {
     if (!context.config.references.craftTs && !context.config.references.effectTs)
         return {};
     const manifest = {
         schemaVersion: 1,
-        mode: context.config.references.mode,
+        mode: 'context',
         effectEnabled: context.config.frontendRuntime === 'effect' ||
             context.config.backendRuntime === 'effect',
     };
@@ -1376,14 +1579,19 @@ function referenceFiles(context) {
             resolvedSha: '',
             path: '.references/effect-ts',
         };
-    const resolver = "export function resolveReferencePath(root, name) { const manifest = resolveReferenceManifest(root); return manifest[name] ? resolve(root, manifest[name].path) : undefined; }\nexport function resolveReferenceManifest(root) { return JSON.parse(readFileSync(join(root, '.references/manifest.json'), 'utf8')); }\nimport { readFileSync } from 'node:fs'; import { join, resolve } from 'node:path';\n";
-    const updater = `import { execFileSync } from 'node:child_process'; import { readFileSync, rmSync, writeFileSync } from 'node:fs'; import { join, resolve } from 'node:path';
-const root = resolve(import.meta.dirname, '..'); const manifestPath = join(root, '.references/manifest.json'); const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-const effectReferencePaths = ${JSON.stringify(EFFECT_REFERENCE_PATHS)};
-function pruneEffectReference(referenceRoot) { for (const relativePath of effectReferencePaths) rmSync(join(referenceRoot, relativePath), { recursive: true, force: true }); }
-const craftProjects = ['craft-ts-core', 'craft-ts-component', 'dev-tools', 'mcp', 'craft-ts-i18n', 'craft-ts-i18n-effect', 'craft-ts-style', 'craft-ts-style-testing', ...(manifest.effectEnabled ? ['craft-ts-effect'] : [])].join(',');
-function buildReference(name, path) { if (name === 'craftTs' && manifest.mode === 'local') { execFileSync('npx', ['--no-install', 'nx', 'run-many', '--target=build', '--projects', craftProjects, '--skipSync', '--outputStyle=stream'], { cwd: path, stdio: 'inherit' }); for (const workspace of ['@craft-ts/log-server', '@craft-ts/log-mcp', '@craft-ts/function-registry-mcp']) execFileSync('npm', ['run', 'build', '--workspace', workspace], { cwd: path, stdio: 'inherit' }); } else if (name === 'effectTs' && (manifest.mode === 'local' || manifest.mode === 'source')) execFileSync('npm', ['run', 'build'], { cwd: path, stdio: 'inherit' }); }
-for (const [name, entry] of Object.entries(manifest).filter(([key, value]) => !['schemaVersion', 'mode', 'effectEnabled'].includes(key) && value && value.path)) { const path = resolve(root, entry.path); if (execFileSync('git', ['status', '--short'], { cwd: path, encoding: 'utf8' }).trim()) throw new Error('Modified reference: ' + path); execFileSync('git', ['fetch', '--depth', '1', 'origin', entry.requestedRef], { cwd: path, stdio: 'inherit' }); execFileSync('git', ['checkout', '--detach', 'FETCH_HEAD'], { cwd: path, stdio: 'inherit' }); if (manifest.mode === 'local' || (manifest.mode === 'source' && name === 'effectTs')) { execFileSync('npm', ['install', '--no-audit', '--no-fund'], { cwd: path, stdio: 'inherit' }); buildReference(name, path); } if (name === 'craftTs' && manifest.effectEnabled === false) pruneEffectReference(path); entry.resolvedSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: path, encoding: 'utf8' }).trim(); }
+    const resolver = "import { readFileSync } from 'node:fs'; import { join, resolve } from 'node:path';\nexport function resolveReferenceManifest(root) { return JSON.parse(readFileSync(join(root, '.references/manifest.json'), 'utf8')); }\nexport function resolveReferencePath(root, name) { const manifest = resolveReferenceManifest(root); return manifest[name] ? resolve(root, manifest[name].path) : undefined; }\n";
+    const updater = `import { execFileSync } from 'node:child_process'; import { existsSync, readFileSync, writeFileSync } from 'node:fs'; import { join, resolve } from 'node:path';
+const root = resolve(import.meta.dirname, '..');
+const manifestPath = join(root, '.references/manifest.json');
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+for (const [name, entry] of Object.entries(manifest).filter(([key, value]) => !['schemaVersion', 'mode', 'effectEnabled'].includes(key) && value && value.path)) {
+  const path = resolve(root, entry.path);
+  if (!existsSync(join(path, '.git'))) throw new Error('Missing reference clone: ' + path);
+  if (execFileSync('git', ['status', '--short'], { cwd: path, encoding: 'utf8' }).trim()) throw new Error('Modified reference: ' + path);
+  execFileSync('git', ['fetch', '--depth', '1', 'origin', entry.requestedRef], { cwd: path, stdio: 'inherit' });
+  execFileSync('git', ['checkout', '--detach', 'FETCH_HEAD'], { cwd: path, stdio: 'inherit' });
+  entry.resolvedSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: path, encoding: 'utf8' }).trim();
+}
 writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\\n');
 `;
     return {
@@ -1422,22 +1630,6 @@ function cloneReferenceIfRequested(root, config) {
             mkdirSync(dirname(target), { recursive: true });
             execFileSync('git', ['clone', '--depth', '1', '--branch', ref, url, target], { cwd: root, stdio: 'inherit' });
         }
-        if (relativePath === '.references/craft-ts' &&
-            config.frontendRuntime !== 'effect' &&
-            config.backendRuntime !== 'effect') {
-            pruneEffectReference(target);
-        }
-        if (config.references.mode === 'local' ||
-            (config.references.mode === 'source' &&
-                relativePath === '.references/effect-ts')) {
-            execFileSync('npm', ['install', '--no-audit', '--no-fund'], {
-                cwd: target,
-                stdio: 'inherit',
-            });
-            for (const [command, args] of getReferenceBuildSteps(relativePath, config)) {
-                execFileSync(command, [...args], { cwd: target, stdio: 'inherit' });
-            }
-        }
     }
     const manifestPath = join(root, '.references', 'manifest.json');
     if (existsSync(manifestPath)) {
@@ -1454,51 +1646,6 @@ function cloneReferenceIfRequested(root, config) {
         writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
     }
 }
-/**
- * CraftTS has no root `build` script: its published packages are Nx targets,
- * while the MCP and log workspaces keep their own package build scripts.
- */
-export function getReferenceBuildSteps(relativePath, config) {
-    if (relativePath === '.references/effect-ts') {
-        return [['npm', ['run', 'build']]];
-    }
-    if (relativePath !== '.references/craft-ts')
-        return [];
-    const hasEffect = config.frontendRuntime === 'effect' || config.backendRuntime === 'effect';
-    const projects = [
-        'craft-ts-core',
-        'craft-ts-component',
-        'dev-tools',
-        'mcp',
-        ...(config.i18n.enabled ? ['craft-ts-i18n'] : []),
-        ...(config.i18n.enabled && hasEffect ? ['craft-ts-i18n-effect'] : []),
-        ...(config.typedCss
-            ? ['craft-ts-style', 'craft-ts-style-testing']
-            : []),
-        ...(hasEffect ? ['craft-ts-effect'] : []),
-    ];
-    return [
-        [
-            'npx',
-            [
-                '--no-install',
-                'nx',
-                'run-many',
-                '--target=build',
-                '--projects',
-                projects.join(','),
-                '--skipSync',
-                '--outputStyle=stream',
-            ],
-        ],
-        ['npm', ['run', 'build', '--workspace', '@craft-ts/log-server']],
-        ['npm', ['run', 'build', '--workspace', '@craft-ts/log-mcp']],
-        [
-            'npm',
-            ['run', 'build', '--workspace', '@craft-ts/function-registry-mcp'],
-        ],
-    ];
-}
 function ensureGitignore(root) {
     const gitignorePath = join(root, '.gitignore');
     if (!existsSync(gitignorePath)) {
@@ -1531,11 +1678,6 @@ function initialiseGitRepository(root) {
     }
     execFileSync('git', ['init', '--quiet'], { cwd: root, stdio: 'ignore' });
 }
-export function pruneEffectReference(root) {
-    for (const relativePath of EFFECT_REFERENCE_PATHS) {
-        rmSync(join(root, relativePath), { recursive: true, force: true });
-    }
-}
 function aboutPageTs(context) {
     const designSystem = context.config.designSystem !== 'none';
     const surfaceImport = designSystem
@@ -1593,7 +1735,8 @@ const { StarterService } = craftService({ name: 'StarterService', providedIn: 'g
   return { label: 'resolved through Craft DI' };
 });
 `;
-    return `import { craftComponent, div, heading, p } from '@craft-ts/component';
+    const lintComment = context.config.frontendRuntime === 'effect' ? '' : '/* eslint-disable require-yield -- Synchronous DI factory is intentional in this starter. */\n';
+    return `${lintComment}import { craftComponent, div, heading, p } from '@craft-ts/component';
 ${uiImport}${i18n}${effectI18n}${service}
 export const ServicesPage = craftComponent(
   'ServicesPage',
@@ -1624,9 +1767,9 @@ function plainHomePageTs(context) {
     const summary = context.config.i18n.enabled
         ? "p('i18n: ' + i18n.t('order.summary', { amount: 1234.5, count: 2, date: Date.UTC(2026, 0, 15) })),"
         : "p('A framework-independent starter with a typed API boundary.'),";
-    const loadExpression = context.config.backendRuntime === 'none'
-        ? 'return yield* loadWelcome();'
-        : 'return loadWelcome();';
+    const loadLoader = context.config.backendRuntime === 'none'
+        ? 'function* () { return yield* loadWelcome(); }'
+        : '() => loadWelcome()';
     return `import {
   craftComponent,
   div,
@@ -1646,9 +1789,7 @@ export const HomePage = craftComponent(
       'welcomeQuery',
       {
         params: () => true,
-        loader: function* () {
-          ${loadExpression}
-        },
+        loader: ${loadLoader},
       },
       ({ resource }) => ({
         hasWelcome: craftComputed('hasWelcome', () => resource.hasValue()),
@@ -1664,12 +1805,10 @@ export const HomePage = craftComponent(
       ifNode(welcomeQuery.hasWelcome, () =>
         div([
           p(function* () {
-            const welcome = yield* welcomeQuery.value();
-            return 'API title: ' + (welcome?.title ?? '');
+            return 'API title: ' + String((yield* welcomeQuery.value())?.title);
           }),
           p(function* () {
-            const welcome = yield* welcomeQuery.value();
-            return 'API body: ' + (welcome?.body ?? '');
+            return 'API body: ' + String((yield* welcomeQuery.value())?.body);
           }),
         ]),
       ),
@@ -2051,7 +2190,7 @@ function readme(context) {
             : []),
         ...(references
             ? [
-                `- local CraftTS/EffectTS references under \`${referencePath}/\`; run \`npm run update:references\` to refresh them.`,
+                `- cloned CraftTS/EffectTS source references for coding agents under \`${referencePath}/\`; run \`npm run update:references\` to refresh them.`,
             ]
             : []),
         '',
@@ -2105,7 +2244,8 @@ function readme(context) {
                 '## References',
                 '',
                 `The \`${referencePath}/manifest.json\` file records the requested refs and resolved SHAs.`,
-                'The `context` mode keeps npm dependencies portable; `local` is reserved for build artifacts.',
+                'The cloned repositories are read-only context for coding agents; the application always uses the npm dependencies declared in package.json.',
+                'Do not add file: dependencies or TypeScript/Vite aliases to the clones.',
                 'Run `npm run update:references` after reviewing local changes in a clone.',
             ]
             : []),
@@ -2131,10 +2271,9 @@ function agentFiles(mode, agent, config) {
     const baseSkill = config?.i18n.enabled === false
         ? BASE_AGENT_SKILL.replace(/4\. Keep translations[\s\S]*?5\. Keep visual/, '5. Keep visual')
         : BASE_AGENT_SKILL;
-    const skill = `${baseSkill}${effectEnabled ? `\n${EFFECT_AGENT_SKILL}` : ''}`;
+    const skill = `${baseSkill}${effectEnabled ? `\n${EFFECT_AGENT_SKILL}` : ''}${referenceAgentGuidance(config)}`;
     if (agent === 'codex') {
         return {
-            'AGENTS.md': AGENTS_MD(mode, config),
             '.agents/skills/craft-ts-project/SKILL.md': skill,
             ...(effectEnabled
                 ? { '.agents/skills/craft-ts-effect-v4/SKILL.md': EFFECT_AGENT_SKILL }
@@ -2179,6 +2318,7 @@ function templates(context) {
         : []);
     const files = {
         'package.json': packageJson(context),
+        'AGENTS.md': AGENTS_MD(context.mode, context.config),
         '.gitignore': GENERATED_GITIGNORE,
         'tsconfig.json': tsconfig(context),
         'tsconfig.app.json': tsconfigApp,
@@ -2214,7 +2354,7 @@ function templates(context) {
             }
             : {}),
         ...localeFiles,
-        ...(hasEffect && hasI18n
+        ...(effect && hasI18n
             ? {
                 'src/i18n/effect.ts': effectI18nTs,
                 ...(effect ? { 'src/i18n/effect-layer.ts': effectLayerTs } : {}),
@@ -2382,17 +2522,14 @@ export function normalizeCreateOptions(options) {
         throw new Error(`Unknown references selection "${references}".`);
     }
     if (options.referenceMode !== undefined &&
-        !['context', 'local', 'source'].includes(options.referenceMode)) {
-        throw new Error(`Unknown reference mode "${options.referenceMode}".`);
+        options.referenceMode !== 'context') {
+        throw new Error(`Reference mode "${options.referenceMode}" is no longer supported; cloned references are context only and npm packages remain the runtime dependencies.`);
     }
     const craftTs = options.cloneCraftTs ?? (references === 'craft-ts' || references === 'all');
     const effectTs = options.cloneEffectTs ?? references === 'all';
     if (effectTs && frontendRuntime !== 'effect' && backendRuntime !== 'effect') {
         throw new Error('EffectTS references require an Effect frontend or backend runtime.');
     }
-    if (options.referenceMode === 'local' && !craftTs && !effectTs) {
-        throw new Error('--reference-mode=local requires at least one cloned reference.');
-    }
     const directory = resolve(rootDir, options.directory);
     const workspaceKind = options.workspace ??
         (existsSync(join(rootDir, 'nx.json')) ? 'nx' : 'standalone');
@@ -2413,7 +2550,7 @@ export function normalizeCreateOptions(options) {
         references: {
             craftTs,
             effectTs,
-            mode: options.referenceMode ?? 'context',
+            mode: 'context',
             craftTsRef: options.craftTsRef ?? 'main',
             effectTsRef: options.effectTsRef ?? 'main',
         },