create-foldkit-app 0.6.3 → 0.7.1

package/README.md

@@ -5,14 +5,14 @@ Scaffolding CLI for new Foldkit applications. Creates a ready-to-run project wit
 ## Usage
 
 ```bash
-npx create-foldkit-app --wizard
+npx create-foldkit-app
 # or
-pnpm create foldkit-app --wizard
+pnpm create foldkit-app
 # or
-yarn create foldkit-app --wizard
+yarn create foldkit-app
 ```
 
-The CLI will prompt you for a project name, starter example, and package manager.
+The CLI prompts you for a project name, starter example, and package manager. Pass `--name`, `--example`, and/or `--package-manager` to skip the matching prompts.
 
 ## Examples
 

package/dist/commands/create.js

@@ -1,17 +1,63 @@
-import { Command, FileSystem, Path } from '@effect/platform';
 import chalk from 'chalk';
-import { Console, Effect, Match } from 'effect';
+import { Console, Effect, FileSystem, Match, Option, Path } from 'effect';
+import { Prompt } from 'effect/unstable/cli';
+import { spawnSync } from 'node:child_process';
+import { examples } from '../examples.js';
 import { createProject } from '../utils/files.js';
 import { installDependencies } from '../utils/packages.js';
+import { validateProjectName } from '../validateName.js';
 const isWindows = process.platform === 'win32';
+const promptForName = Prompt.text({
+    message: 'Give your project a name',
+    validate: value => Option.match(validateProjectName(value), {
+        onNone: () => Effect.succeed(value),
+        onSome: message => Effect.fail(message),
+    }),
+});
+const promptForExample = Prompt.autoComplete({
+    message: 'Pick a starting example',
+    choices: examples.map(({ value, title, description }) => ({
+        value,
+        title,
+        description,
+    })),
+});
+const promptForPackageManager = Prompt.select({
+    message: 'Pick a package manager',
+    choices: [
+        { value: 'pnpm', title: 'pnpm' },
+        { value: 'npm', title: 'npm' },
+        { value: 'yarn', title: 'yarn' },
+    ],
+});
+const resolveInput = (input) => Effect.gen(function* () {
+    const name = yield* Option.match(input.name, {
+        onNone: () => promptForName,
+        onSome: Effect.succeed,
+    });
+    const example = yield* Option.match(input.example, {
+        onNone: () => promptForExample,
+        onSome: Effect.succeed,
+    });
+    const packageManager = yield* Option.match(input.packageManager, {
+        onNone: () => promptForPackageManager,
+        onSome: Effect.succeed,
+    });
+    return { name, example, packageManager };
+});
 const validateProject = (name, projectPath, packageManager) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const exists = yield* fs.exists(projectPath);
     if (exists) {
         return yield* Effect.fail(`Directory ${name} already exists!`);
     }
-    const checkCommand = Command.make(isWindows ? 'where' : 'which', packageManager).pipe(Command.stdout('pipe'), Command.stderr('pipe'));
-    return yield* Command.exitCode(checkCommand).pipe(Effect.filterOrFail(exitCode => exitCode === 0, () => `Package manager '${packageManager}' is not available. Please install it first.`));
+    const exitCode = yield* Effect.sync(() => {
+        const result = spawnSync(isWindows ? 'where' : 'which', [packageManager], { stdio: 'pipe', shell: isWindows });
+        return result.status;
+    });
+    if (exitCode !== 0) {
+        return yield* Effect.fail(`Package manager '${packageManager}' is not available. Please install it first.`);
+    }
 });
 const setupProject = (name, projectPath, example) => Effect.gen(function* () {
     yield* Console.log(chalk.blue('🚀 Creating your Foldkit app...'));
@@ -44,24 +90,27 @@ const displaySuccessMessage = (name, packageManager) => Effect.gen(function* ()
     yield* Console.log('');
     yield* Console.log(`  Details: ${chalk.cyan('foldkit.dev/ai/overview')}`);
     yield* Console.log('');
-    yield* Console.log('Foldkit is a one-astronaut nights-and-weekends project.\n' +
-        'If you have praise or criticism, do share.\n' +
-        "Please. It's lonely out here.\n\n" +
-        'Be careful. Make good decisions.');
-    yield* Console.log('');
     yield* Console.log(`Training manual: ${chalk.cyan('foldkit.dev')}`);
     yield* Console.log(`Incident report: ${chalk.cyan('github.com/foldkit/foldkit/issues')}`);
     yield* Console.log('');
-    yield* Console.log(`Transmissions:   ${chalk.cyan('foldkit.dev/newsletter')}`);
-    yield* Console.log(`X:               ${chalk.cyan('x.com/devinjameson')}`);
-    yield* Console.log(`Bluesky:         ${chalk.cyan('bsky.app/profile/devinjameson.bsky.social')}`);
-    yield* Console.log(`Threads:         ${chalk.cyan('threads.com/@devinthedeveloper')}`);
+    yield* Console.log(`Crew channel: ${chalk.cyan('discord.gg/AZRTEs2VX')}`);
+    yield* Console.log('');
+    yield* Console.log('Transmissions:');
+    yield* Console.log(`  Newsletter:  ${chalk.cyan('foldkit.dev/newsletter')}`);
+    yield* Console.log(`  X:           ${chalk.cyan('x.com/devinjameson')}`);
+    yield* Console.log(`  Bluesky:     ${chalk.cyan('bsky.app/profile/devinjameson.bsky.social')}`);
+    yield* Console.log(`  Threads:     ${chalk.cyan('threads.com/@devinthedeveloper')}`);
+    yield* Console.log('');
+    yield* Console.log('Foldkit is a one-astronaut nights-and-weekends project.\n' +
+        'If you have praise or criticism, do share.\n' +
+        "Please. It's lonely out here.");
     yield* Console.log('');
     yield* Console.log('Love you,');
     yield* Console.log('Mission Control');
     yield* Console.log('');
 });
-export const create = ({ name, example, packageManager }) => Effect.gen(function* () {
+export const create = (input) => Effect.gen(function* () {
+    const { name, example, packageManager } = yield* resolveInput(input);
     const path = yield* Path.Path;
     const projectPath = path.resolve(name);
     yield* validateProject(name, projectPath, packageManager);

package/dist/examples.js

@@ -0,0 +1,100 @@
+export const EXAMPLE_VALUES = [
+    'counter',
+    'todo',
+    'stopwatch',
+    'crash-view',
+    'form',
+    'job-application',
+    'weather',
+    'routing',
+    'query-sync',
+    'snake',
+    'auth',
+    'shopping-cart',
+    'pixel-art',
+    'websocket-chat',
+    'kanban',
+    'ui-showcase',
+];
+export const examples = [
+    {
+        value: 'counter',
+        title: 'counter',
+        description: 'Simple increment/decrement with reset',
+    },
+    {
+        value: 'todo',
+        title: 'todo',
+        description: 'CRUD operations with localStorage persistence',
+    },
+    {
+        value: 'stopwatch',
+        title: 'stopwatch',
+        description: 'Timer with start/stop/reset functionality',
+    },
+    {
+        value: 'crash-view',
+        title: 'crash-view',
+        description: 'Custom crash fallback UI with crash.view and crash.report',
+    },
+    {
+        value: 'form',
+        title: 'form',
+        description: 'Form validation with async email checking',
+    },
+    {
+        value: 'job-application',
+        title: 'job-application',
+        description: 'Multi-step form with async validation, file uploads, and per-step error indicators',
+    },
+    {
+        value: 'weather',
+        title: 'weather',
+        description: 'HTTP requests with async state handling',
+    },
+    {
+        value: 'routing',
+        title: 'routing',
+        description: 'URL routing with parser combinators and route parameters',
+    },
+    {
+        value: 'query-sync',
+        title: 'query-sync',
+        description: 'URL-driven filtering, sorting, and search with query parameters',
+    },
+    {
+        value: 'snake',
+        title: 'snake',
+        description: 'Classic game built with subscriptions',
+    },
+    {
+        value: 'auth',
+        title: 'auth',
+        description: 'Authentication with Submodels, OutMessage, and protected routes',
+    },
+    {
+        value: 'shopping-cart',
+        title: 'shopping-cart',
+        description: 'Complex state management with nested models and routing',
+    },
+    {
+        value: 'pixel-art',
+        title: 'pixel-art',
+        description: 'Pixel editor with undo/redo, time-travel history, UI components, and localStorage persistence',
+    },
+    {
+        value: 'websocket-chat',
+        title: 'websocket-chat',
+        description: 'Managed resources with WebSocket integration',
+    },
+    {
+        value: 'kanban',
+        title: 'kanban',
+        description: 'Drag-and-drop board with fractional indexing, keyboard navigation, and screen reader announcements',
+    },
+    {
+        value: 'ui-showcase',
+        title: 'ui-showcase',
+        description: 'Every Foldkit UI component with routing and Submodels',
+    },
+];

package/dist/index.js

@@ -1,62 +1,34 @@
 #!/usr/bin/env node
-import { Command, HelpDoc, Options } from '@effect/cli';
-import { FetchHttpClient } from '@effect/platform';
-import { NodeContext, NodeRuntime } from '@effect/platform-node';
-import { Effect, Match, Option, Schema, String, flow } from 'effect';
+import { NodeRuntime, NodeServices, NodeStdio } from '@effect/platform-node';
+import { Effect, Layer, Option, Schema } from 'effect';
+import { Command, Flag } from 'effect/unstable/cli';
+import { FetchHttpClient } from 'effect/unstable/http';
 import { createRequire } from 'node:module';
 import { create as create_ } from './commands/create.js';
+import { EXAMPLE_VALUES } from './examples.js';
+import { validateProjectName } from './validateName.js';
 /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
 const packageJson = createRequire(import.meta.url)('../package.json');
-const nameSchema = Schema.String.pipe(Schema.filter(name => Match.value(name).pipe(Match.whenOr(String.includes('/'), String.includes('\\'), () => 'Project name cannot contain path separators (/ or \\)'), Match.when(String.includes(' '), () => 'Project name cannot contain spaces'), Match.when(flow(String.match(/[<>:"|?*]/), Option.isSome), () => 'Project name cannot contain special characters: < > : " | ? *'), Match.whenOr(String.startsWith('.'), String.startsWith('-'), () => 'Project name cannot start with . or -'), Match.when(String.isEmpty, () => 'Project name cannot be empty'), Match.orElse(() => true))));
-const name = Options.text('name').pipe(Options.withAlias('n'), Options.withDescription('The name of the project to create'), Options.withSchema(nameSchema));
-const example = Options.choice('example', [
-    'counter',
-    'todo',
-    'stopwatch',
-    'crash-view',
-    'form',
-    'job-application',
-    'weather',
-    'routing',
-    'query-sync',
-    'snake',
-    'auth',
-    'shopping-cart',
-    'pixel-art',
-    'websocket-chat',
-    'kanban',
-    'ui-showcase',
-]).pipe(Options.withAlias('e'), Options.withDescription("The example application to start from. Pick an example that's similar to the application you're building. Or create multiple projects and take pieces of each!\n\n" +
-    'Available examples:\n' +
-    '  counter - Simple increment/decrement with reset\n' +
-    '  todo - CRUD operations with localStorage persistence\n' +
-    '  stopwatch - Timer with start/stop/reset functionality\n' +
-    '  crash-view - Custom crash fallback UI with crash.view and crash.report\n' +
-    '  form - Form validation with async email checking\n' +
-    '  job-application - Multi-step form with async validation, file uploads, and per-step error indicators\n' +
-    '  weather - HTTP requests with async state handling\n' +
-    '  routing - URL routing with parser combinators and route parameters\n' +
-    '  query-sync - URL-driven filtering, sorting, and search with query parameters\n' +
-    '  snake - Classic game built with subscriptions\n' +
-    '  auth - Authentication with Submodels, OutMessage, and protected routes\n' +
-    '  shopping-cart - Complex state management with nested models and routing\n' +
-    '  pixel-art - Pixel editor with undo/redo, time-travel history, UI components, and localStorage persistence\n' +
-    '  websocket-chat - Managed resources with WebSocket integration\n' +
-    '  kanban - Drag-and-drop board with fractional indexing, keyboard navigation, and screen reader announcements\n' +
-    '  ui-showcase - Every Foldkit UI component with routing and Submodels'));
-const packageManager = Options.choice('package-manager', [
+const nameSchema = Schema.String.pipe(Schema.check(Schema.makeFilter(value => Option.match(validateProjectName(value), {
+    onNone: () => true,
+    onSome: message => message,
+}))));
+const name = Flag.string('name').pipe(Flag.withAlias('n'), Flag.withDescription('The name of the project to create'), Flag.withSchema(nameSchema), Flag.optional);
+const example = Flag.choice('example', EXAMPLE_VALUES).pipe(Flag.withAlias('e'), Flag.withDescription("The example application to start from. Run with no flags for an interactive picker that shows each example's description."), Flag.optional);
+const packageManager = Flag.choice('package-manager', [
     'pnpm',
     'npm',
     'yarn',
-]).pipe(Options.withAlias('p'), Options.withDescription('The package manager to use for installing dependencies'));
+]).pipe(Flag.withAlias('p'), Flag.withDescription('The package manager to use for installing dependencies'), Flag.optional);
 const create = Command.make('create', {
     name,
     example,
     packageManager,
-}, create_);
+}, create_).pipe(Command.withDescription('Create a new Foldkit application'));
 const cli = Command.run(create, {
-    name: 'Create Foldkit App',
     version: packageJson.version,
-    summary: HelpDoc.getSpan(HelpDoc.p('Create a new Foldkit application')),
 });
-cli(process.argv).pipe(Effect.provide([FetchHttpClient.layer, NodeContext.layer]), NodeRuntime.runMain);
+cli.pipe(Effect.provide([
+    FetchHttpClient.layer,
+    Layer.mergeAll(NodeServices.layer, NodeStdio.layer),
+]), NodeRuntime.runMain);

package/dist/utils/files.js

@@ -1,5 +1,5 @@
-import { FileSystem, HttpClient, HttpClientRequest, Path, } from '@effect/platform';
-import { Array, Effect, Match, Option, Record, Ref, Schema, String, pipe, } from 'effect';
+import { Array, Effect, FileSystem, Match, Option, Path, Record, Ref, Schema, String, pipe, } from 'effect';
+import { HttpClient, HttpClientRequest, } from 'effect/unstable/http';
 import { fileURLToPath } from 'node:url';
 const GITHUB_API_BASE_URL = 'https://api.github.com/repos/foldkit/foldkit/contents/examples';
 const getBaseFiles = Effect.gen(function* () {
@@ -76,7 +76,7 @@ const fetchExampleFileList = (example) => Effect.gen(function* () {
         const request = HttpClientRequest.get(apiUrl);
         const response = yield* client.execute(request);
         const json = yield* response.json;
-        const entries = yield* Schema.decodeUnknown(Schema.Array(GitHubFileEntry))(json);
+        const entries = yield* Schema.decodeUnknownEffect(Schema.Array(GitHubFileEntry))(json);
         const results = yield* Effect.forEach(entries, entry => Match.value(entry.type).pipe(Match.when('file', () => Effect.succeed([entry])), Match.when('dir', () => fetchFilesRecursively(entry.url)), Match.orElse(() => Effect.succeed([]))));
         return Array.flatten(results);
     });

package/dist/utils/packages.js

@@ -1,12 +1,13 @@
-import { Command, HttpClient, HttpClientRequest } from '@effect/platform';
 import { Array, Effect, Match, Record, Schema, pipe } from 'effect';
+import { HttpClient, HttpClientRequest } from 'effect/unstable/http';
+import { spawn } from 'node:child_process';
 const GITHUB_RAW_BASE_URL = 'https://raw.githubusercontent.com/foldkit/foldkit/main/examples';
 const isWindows = process.platform === 'win32';
 const getInstallArgs = (packageManager, isDev = false) => pipe(Match.value(packageManager), Match.when('npm', () => ['install']), Match.when('yarn', () => ['add']), Match.when('pnpm', () => ['add']), Match.exhaustive, args => (isDev ? [...args, '-D'] : args));
-const StringRecord = Schema.Record({ key: Schema.String, value: Schema.String });
+const StringRecord = Schema.Record(Schema.String, Schema.String);
 const PackageJson = Schema.Struct({
-    dependencies: Schema.optionalWith(StringRecord, { default: () => ({}) }),
-    devDependencies: Schema.optionalWith(StringRecord, { default: () => ({}) }),
+    dependencies: StringRecord.pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
+    devDependencies: StringRecord.pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
 });
 const formatDeps = (deps) => pipe(deps, Record.toEntries, Array.filter(([_, version]) => !version.includes('workspace:')), Array.map(([name, version]) => `${name}@${version}`));
 const fetchExampleDeps = (example) => Effect.gen(function* () {
@@ -14,18 +15,47 @@ const fetchExampleDeps = (example) => Effect.gen(function* () {
     const url = `${GITHUB_RAW_BASE_URL}/${example}/package.json`;
     const response = yield* client.execute(HttpClientRequest.get(url));
     const json = yield* response.json;
-    const packageJson = yield* Schema.decodeUnknown(PackageJson)(json);
+    const packageJson = yield* Schema.decodeUnknownEffect(PackageJson)(json);
     return {
         dependencies: formatDeps(packageJson.dependencies),
         devDependencies: formatDeps(packageJson.devDependencies),
     };
 });
+const runCommand = (command, args, cwd) => Effect.callback((resume) => {
+    const child = spawn(command, [...args], {
+        cwd,
+        shell: isWindows,
+        stdio: 'inherit',
+    });
+    child.on('error', error => resume(Effect.fail(error)));
+    child.on('exit', code => {
+        if (code === 0) {
+            resume(Effect.void);
+        }
+        else {
+            resume(Effect.fail(new Error(`${command} exited with code ${code}`)));
+        }
+    });
+    // NOTE: SIGTERM only — the Effect.callback finalizer is sync so we
+    // can't escalate to SIGKILL. On Windows with shell:true the signal
+    // hits cmd.exe but doesn't propagate to the package manager.
+    return Effect.sync(() => {
+        if (child.exitCode === null && !child.killed) {
+            child.kill();
+        }
+    });
+});
 export const installDependencies = (projectPath, packageManager, example) => Effect.gen(function* () {
     const exampleDeps = yield* fetchExampleDeps(example);
     const installArgs = getInstallArgs(packageManager);
-    const installDeps = Command.make(packageManager, ...installArgs, 'foldkit', ...exampleDeps.dependencies).pipe(Command.runInShell(isWindows), Command.workingDirectory(projectPath), Command.stdout('inherit'), Command.stderr('inherit'));
-    yield* Command.exitCode(installDeps);
+    yield* runCommand(packageManager, [...installArgs, 'foldkit', ...exampleDeps.dependencies], projectPath);
     const installDevArgs = getInstallArgs(packageManager, true);
-    const installDevDeps = Command.make(packageManager, ...installDevArgs, '@foldkit/vite-plugin', '@foldkit/devtools-mcp', 'vitest', 'happy-dom', ...exampleDeps.devDependencies).pipe(Command.runInShell(isWindows), Command.workingDirectory(projectPath), Command.stdout('inherit'), Command.stderr('inherit'));
-    yield* Command.exitCode(installDevDeps);
+    yield* runCommand(packageManager, [
+        ...installDevArgs,
+        '@foldkit/vite-plugin',
+        '@foldkit/devtools-mcp',
+        'vitest',
+        'happy-dom',
+        ...exampleDeps.devDependencies,
+    ], projectPath);
 });

package/dist/validateName.js

@@ -0,0 +1,2 @@
+import { Match, Option, String, flow } from 'effect';
+export const validateProjectName = (name) => Match.value(name).pipe(Match.when(String.isEmpty, () => Option.some('Project name cannot be empty')), Match.whenOr(String.includes('/'), String.includes('\\'), () => Option.some('Project name cannot contain path separators (/ or \\)')), Match.when(String.includes(' '), () => Option.some('Project name cannot contain spaces')), Match.when(flow(String.match(/[<>:"|?*]/), Option.isSome), () => Option.some('Project name cannot contain special characters: < > : " | ? *')), Match.whenOr(String.startsWith('.'), String.startsWith('-'), () => Option.some('Project name cannot start with . or -')), Match.orElse(() => Option.none()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-foldkit-app",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "description": "Create Foldkit applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,15 +12,11 @@
     "templates"
   ],
   "dependencies": {
-    "@effect/cli": "^0.73.2",
-    "@effect/platform": "^0.94.5",
-    "@effect/platform-node": "^0.104.1",
-    "@types/prompts": "^2.4.9",
+    "@effect/platform-node": "4.0.0-beta.59",
     "chalk": "^5.6.2",
-    "effect": "^3.19.19",
-    "prompts": "^2.4.2",
-    "rimraf": "^6.1.2",
-    "typescript": "^6.0.2"
+    "effect": "4.0.0-beta.59",
+    "rimraf": "^6.1.3",
+    "typescript": "^6.0.3"
   },
   "keywords": [
     "create-foldkit-app",

package/templates/base/AGENTS.md

@@ -76,7 +76,7 @@ const fetchWeather = (city: string) =>
     // ...
     return SucceededFetchWeather({ data })
   }).pipe(
-    Effect.catchAll(error =>
+    Effect.catch(error =>
       Effect.succeed(FailedFetchWeather({ error: String(error) })),
     ),
     FetchWeather,
@@ -89,31 +89,38 @@ Command definitions live where they're produced — colocated with the update fu
 
 ### Mount
 
-For per-element DOM work — focusing an input, handing the live `Element` to a third-party library — define a Mount with `Mount.define` and attach it to a view element with `OnMount`. The runtime runs the Effect when the element mounts, dispatches its result Message back through `update`, and runs the paired cleanup on unmount.
+For per-element DOM work that needs the live `Element` handle (anchor positioning, portaling an overlay, attaching observers, handing the element to a third-party library), define a Mount with `Mount.define` and attach it to a view element with `OnMount`. The runtime runs the Effect when the element mounts, dispatches its result Message back through `update`, and runs the paired cleanup on unmount.
 
 ```ts
-const CompletedFocusInput = m('CompletedFocusInput')
+const CompletedPortalToBody = m('CompletedPortalToBody')
 
-const FocusInput = Mount.define('FocusInput', CompletedFocusInput)
+const PortalToBody = Mount.define('PortalToBody', CompletedPortalToBody)
 
-const focusInput = FocusInput(element =>
+const portalToBody = PortalToBody(element =>
   Effect.sync(() => {
-    if (element instanceof HTMLInputElement) {
-      element.focus()
-    }
+    document.body.appendChild(element)
     return {
-      message: CompletedFocusInput(),
-      cleanup: Function.constVoid,
+      message: CompletedPortalToBody(),
+      cleanup: () => element.remove(),
     }
   }),
 )
 
 // In view:
-input([Type('search'), OnMount(focusInput)])
+div([Class('fixed inset-0 bg-black/50'), OnMount(portalToBody)])
 ```
 
 Cleanup is data, paired with setup as a single value. For setup with no cleanup, pass `Function.constVoid`. The `Completed*` Message marks the lifecycle without forcing a meaningful response in update.
 
+Two rules for Mount, both must hold:
+
+1. **The Effect uses the element parameter.** Mount provides the live element handle, and that handle is what makes Mount distinct from Command. If your Effect doesn't read or write the element, pick a different primitive.
+2. **The work is DOM measurement or DOM manipulation on that element.** Read its geometry, mutate its CSS, attach an observer to it, portal it, hand it to a third-party library. Anything else (network, storage, focus-on-transition, scroll lock for the page) belongs in a Command returned from `update`.
+
+Mount Effects re-run during DevTools time-travel renders. The two rules above keep Mount work inherently replay-safe (read-only measurement, idempotent DOM mutation, paired observer attach + cleanup).
+
+Don't reach for Mount just because the work happens to coincide with an element appearing. Check what causes the work. If a Message just dispatched (like `Opened`), the cause is the Message, not the element. Use a Command returned from `update`'s handler instead. Example: focusing a search input when its dialog opens. The cause is `Opened`, not the input's existence; return a `FocusInput` Command from the `Opened` handler.
+
 ### File Organization
 
 Use uppercase section headers (`// MODEL`, `// MESSAGE`, `// INIT`, `// UPDATE`, `// COMMAND`, `// VIEW`) to make files easier to skim. These are for wayfinding — they make it clear where things live and where new code should go. Use domain-specific headers too when it helps (e.g. `// PHYSICS`, `// ROUTING`).
@@ -154,7 +161,7 @@ If the `foldkit_*` tools aren't visible, see `@foldkit/devtools-mcp` on npm for
 - Prefer Effect module functions over native methods when available — e.g. `Array.map`, `Array.filter`, `Option.map`, `String.startsWith` from Effect instead of their native equivalents. This includes Effect's `String` module: use `String.includes`, `String.indexOf` (returns `Option<number>`), `String.slice`, `String.startsWith`, `String.replaceAll`, `String.length`, `String.isNonEmpty`, `String.trim` etc. in `pipe` chains. Exception: native `.map`, `.filter`, `.indexOf()`, `.slice()`, etc. are fine when calling directly on a named variable — use Effect's curried, data-last forms in `pipe` chains where they compose naturally.
 - Never use `for` loops or `let` for iteration. Use `Array.makeBy` for index-based construction, `Array.range` + `Array.findFirst`/`Array.findLast` for searches, and `Array.filterMap`/`Array.flatMap` for transforms.
 - Never cast Schema values with `as Type`. Use callable constructors: `LoginSucceeded({ sessionId })` not `{ _tag: 'LoginSucceeded', sessionId } as Message`.
-- Use `Option` for model fields that may be absent — not empty strings or zero values. `loginError: S.OptionFromSelf(S.String)` not `loginError: S.String` with `''` as the "none" state. Use `Option.match` in views to conditionally render.
+- Use `Option` for model fields that may be absent — not empty strings or zero values. `loginError: S.Option(S.String)` not `loginError: S.String` with `''` as the "none" state. Use `Option.match` in views to conditionally render.
 - Use `Array.take` instead of `.slice(0, n)`.
 - Always use `Array.isEmptyArray(foo)` instead of `foo.length === 0`. Use `Array.isNonEmptyArray(foo)` for non-empty checks. When handling both cases, prefer `Array.match`.
 
@@ -167,12 +174,16 @@ const ClickedSubmit = m('ClickedSubmit')
 const ChangedEmail = m('ChangedEmail', { value: S.String })
 const CompletedNavigateInternal = m('CompletedNavigateInternal')
 
-const Message = S.Union(ClickedSubmit, ChangedEmail, CompletedNavigateInternal)
+const Message = S.Union([
+  ClickedSubmit,
+  ChangedEmail,
+  CompletedNavigateInternal,
+])
 type Message = typeof Message.Type
 ```
 
 1. **Values** — all `m()` declarations, no blank lines between them
-2. **Union + type** — `S.Union(...)` followed by `type Message = typeof Message.Type` on adjacent lines (no blank line between them)
+2. **Union + type** — `S.Union([...])` followed by `type Message = typeof Message.Type` on adjacent lines (no blank line between them)
 
 Use `typeof ClickedSubmit` in type positions to reference a schema value's type.
 
@@ -183,8 +194,8 @@ Use `typeof ClickedSubmit` in type positions to reference a schema value's type.
 - Avoid `let`. Use `const` and prefer immutable patterns.
 - Always use braces for control flow. `if (foo) { return true }` not `if (foo) return true`.
 - Use `is*` for boolean naming e.g. `isPlaying`, `isValid`.
-- Don't add inline or block comments to explain code — if code needs explanation, refactor for clarity or use better names. Exceptions: section headers (see File Organization above) and TSDoc (`/** ... */`) on public exports.
-- Use capitalized string literals for Schema literal types: `S.Literal('Horizontal', 'Vertical')` not `S.Literal('horizontal', 'vertical')`.
+- Don't add inline or block comments to explain code. If code needs explanation, refactor for clarity or use better names. Exceptions: section headers (see File Organization above), TSDoc (`/** ... */`) on public exports, and `// NOTE:` comments. Reserve `// NOTE:` for behavior that would mislead a careful reader into breaking things: a timing dependency that's silent if violated, a workaround for an upstream bug, a browser quirk that costs real debugging time to rediscover. The bar is high. When in doubt, delete it.
+- Use capitalized string literals for Schema literal types: `S.Literals(['Horizontal', 'Vertical'])` not `S.Literals(['horizontal', 'vertical'])`.
 - Capitalize namespace imports: `import * as Command from './command'` not `import * as command from './command'`.
 - Extract magic numbers to named constants. No raw numeric literals in logic.
 - Never use `T[]` syntax. Always use `Array<T>` or `ReadonlyArray<T>`.