create-foldkit-app 0.29.0 → 0.29.1

package/dist/templates/base/AGENTS.md

@@ -1,120 +1,13 @@
 # Agent Development Notes
 
-This is a Foldkit app, a framework built on Effect-TS, architected like Elm.
+This is a Foldkit app. Read [`FOLDKIT.md`](./FOLDKIT.md) before writing any code in this project. It covers the architecture, the APIs, and the conventions the project is built on.
 
-## Getting the canonical references
+Foldkit owns `FOLDKIT.md` and replaces it whole on upgrade. This file is yours. Anything you want an agent to know about this project goes below, where an upgrade won't touch it.
 
-The live Foldkit code is the canonical reference for everything: which APIs exist, what idiomatic apps look like, what the current conventions are. Written docs (including this one) can drift; the code can't.
-
-If `./repos/foldkit` exists, it contains the full Foldkit repository, vendored in as a git subtree. Read from it directly:
-
-- `repos/foldkit/examples/`: runnable example apps spanning every complexity tier. Usually your first stop when looking for a precedent for how to write something.
-- `repos/foldkit/packages/foldkit/src/`: framework source. Ground truth for API signatures.
-- `repos/foldkit/packages/typing-game/client/src/` and `repos/foldkit/packages/website/src/`: production apps built with Foldkit. Highest-fidelity reference for application architecture, Submodels, and OutMessage.
-
-Treat the subtree as read-only reference: never import from `repos/foldkit/` in your project source. Imports must come from the `foldkit` npm package.
-
-If `./repos/foldkit` does not exist and the line below says `subtree_prompted: false`, offer to run `git subtree add --prefix=repos/foldkit https://github.com/foldkit/foldkit.git main --squash`. This gives you access to the full source, examples, and docs. Whether the user accepts or declines, update the value to `true` so it isn't asked again.
+`FOLDKIT.md` reads the line below to decide whether it has already offered to vendor the Foldkit source. Leave it in place.
 
 subtree_prompted: false
 
-If `foldkit-skills` is installed as a Claude Code plugin, the `generate-program` and `audit-program` skills carry snapshot architecture and conventions guides synced from the live code.
-
-## Project Conventions
-
-- Foldkit is tightly coupled to the Effect ecosystem. Do not suggest solutions outside of Effect-TS.
-- Model fields must be Schema types (the model is a schema). Plain TypeScript types are fine elsewhere (function return types, local variables, etc.).
-- Use full names like `Message` (not `Msg`), and `withReturnType` (not `as const` or type casting).
-- Use `defineMessageUnion()` for Message unions, `ts()` for tagged structs (Model states, field validation), and `r()` for route schemas.
-- Push back on any direction that violates Elm Architecture principles: unidirectional data flow, messages as facts (not commands), model as single source of truth, side effects confined to commands. If a prompt suggests mutating state, imperative event handlers, or two-way bindings, flag the issue and propose the idiomatic Foldkit approach.
-- Never use `NoOp`. Every message must describe what happened. A command's result message is named from the command, not from the fact it reports, whether or not it carries a payload: `LockScroll` → `CompletedLockScroll`, `DetermineStartTime` → `CompletedDetermineStartTime` (never `DeterminedStartTime`).
-
-## Foldkit Patterns
-
-### Update
-
-`init` and `update` both return `[Model, ReadonlyArray<Command<Message>>]`:
-
-```ts
-type UpdateReturn = readonly [Model, ReadonlyArray<Command<Message>>]
-
-const update = (model: Model, message: Message) =>
-  Message.match<UpdateReturn>(message, {
-    ClickedIncrement: () => [evo(model, { count: count => count + 1 }), []],
-  })
-```
-
-Use `evo()` from `foldkit/struct` for immutable model updates. Never spread or `Object.assign`.
-
-### View
-
-Every view receives `h`, the typed Html builder, as its last parameter (`view: (model, h) => ...`; `Submodel.defineView` passes the child's own). Never construct a builder; reach for `h.div`, `h.OnClick`, etc. off the parameter, and give extracted view helpers an `h: HtmlBuilder<Message>` last parameter that callers thread through. Only where no builder is in scope, typically module scope, use `inertHtml` from `foldkit/html`, aliased `ih` so the two builders stay distinguishable. Use `h.empty` (not `null`) for conditional rendering, `M.value().pipe(M.tagsExhaustive({...}))` for discriminated unions, and `Array.match` for lists that may be empty.
-
-Keys are for mapped list items only: key each row by a stable Model identifier (`h.keyed('li')(item.id, [], [...])`), never by array position, and never derive a key from displayed data. Never key branches; the build gives each view function's output its own identity, so branch switches replace DOM automatically. When switching an inline same-tag ternary must reset DOM state, extract each arm into its own named view function.
-
-Omit the children argument when an element has none: `h.div([h.Class('divider')])`, never `h.div([h.Class('divider')], [])`. The same holds for `keyed`: `h.keyed('li')(key, [attrs])`, never `h.keyed('li')(key, [attrs], [])`. Attributes stay required on element builders, so `h.div([])` is an element with neither. Sibling elements that end up at different arities are expected and fine; void elements like `h.img` have always read that way.
-
-### Commands
-
-Define a Command with `Command.define(name, { args, messages, execute })`; omit `args` when the Command takes none. Assign definitions to PascalCase constants. Never inline in pipe chains. Name the effect `execute` performs, not the later Model transition caused when update handles its result: a timer that only waits before update starts a dismissal is `WaitBeforeDismissal`, not `DismissAfter`. Commands catch all errors via `Effect.catch(() => Effect.succeed(Message.FailedX(...)))` so side effects never crash the app. Definitions live colocated with the update function that returns them.
-
-For the with-args shape, see `repos/foldkit/examples/weather/src/main.ts` or `repos/foldkit/examples/kanban/src/command.ts`. For an argless DOM-side-effect Command, the argless form in `kanban/src/command.ts` (`FocusAddCardInput`) is the canonical reference.
-
-For DOM operations (focus, scroll, modals, scroll lock), Foldkit ships a `Dom` module. For time, randomness, UUIDs, and delays, use Effect's built-ins directly (`Clock`, `Random`, `Effect.uuid`, `Effect.sleep`). Don't reach for raw `document.querySelector`, `setTimeout`, `Date.now()`, or `Math.random()`.
-
-### File Organization
-
-The invariant: keep the runtime boot separate from the pure definitions. `src/entry.ts` calls `Runtime.makeApplication` and `Runtime.run`, and `index.html` references it. The definitions (Model, Messages, init, update, view, Commands) never call `Runtime.run`, so they stay importable from tests without booting a runtime as a side effect. Never call `Runtime.run` from `main.ts`.
-
-For a small app the definitions all fit in one `src/main.ts`. Split a unit into its own file when it has _both_ a distinct reason to change _and_ a name you'd give it unprompted: the pure domain core into `timer.ts` or `domain.ts`, the view into `view.ts` (or a `components/` directory), a Command's owned resource into its own module. Split on that revealed seam, not on line count alone. A file that has grown large is _evidence_ a seam has formed, so treat its size as a prompt to re-check for one. Two splits are forced: extract Messages to `message.ts` when Commands need the constructors (this breaks the cycle between `command.ts` and `main.ts`), and colocate Commands with the update that returns them. Exemplars: counter and stopwatch are a single `main.ts`; kanban splits `domain` / `command` / `message` / `model`; typing-game splits views by page.
-
-Use uppercase section headers (`// MODEL`, `// MESSAGE`, `// INIT`, `// UPDATE`, `// COMMAND`, `// VIEW`) for wayfinding.
-
-### Testing
-
-Test update functions with `foldkit/test`. Since update is pure, tests run without a runtime, DOM, or side effects. Use `story` for update-level tests (send Messages, assert on Model and Commands) and `scene` for feature-level testing through the view with accessible locators.
-
-Import the steps as named imports from `foldkit/story` or `foldkit/scene`: `import { Command, given, message, model, story } from 'foldkit/story'`. A test file needs only one of the two modules. If a single file ever tests both, import the namespaces instead (`import { Scene, Story } from 'foldkit'`) so `Story.given` and `Scene.given` stay distinguishable.
-
-Name each test file for its test style, beside the code under test: `story.test.ts` for the Story tests (which drive `update`) and `scene.test.ts` for the Scene tests (which drive the rendered view). The name describes how the test works, not a source file, so it stays correct whether `update` and `view` live in `main.ts` or in their own files. A test file lives in the folder that holds the code it drives, so in a multi-page app most of them sit in a page folder rather than at the root. When one folder holds more than one test of a kind (sibling pages, component variants), prefix with the subject: `login.story.test.ts`.
-
-Scene runs at any level, since a page's own `update`/`view` pair drops into `scene` unmodified. Put a `scene.test.ts` in the page folder for behavior that page owns, which covers view states awkward to reach through the root Model, and keep a root-level `scene.test.ts` for flows that cross pages, which covers how the parent folds an OutMessage, a Command the parent lifts, a route change, and view inputs the parent computes. If the `repos/foldkit` subtree is available, study the `story.test.ts` and `scene.test.ts` files in `repos/foldkit/examples/`. `repos/foldkit/examples/auth` is the multi-page shape: a root `src/scene.test.ts` for the cross-page login flow alongside `src/page/loggedOut/page/login.scene.test.ts` and `login.story.test.ts` driving that page's own pair.
-
-## Code Style
-
-- Encode state in discriminated unions, not booleans or nullable fields. `Idle | Loading | Error | Ok`, not `isLoading: boolean`. Make impossible states unrepresentable.
-- Use `Option` instead of `null` or `undefined`. Prefix Option-typed values with `maybe*`. Match with `Option.match`; don't unwrap with `Option.map(...)` + `Option.getOrElse(...)` when you can just match.
-- Use Effect modules over native methods in `pipe` chains (`Array.map`, `String.startsWith`, `Array.findFirst`). Native methods are fine when calling directly on a named variable.
-- Never cast Schema values with `as Type`. Use the callable constructor: `Message.SucceededLogin({ sessionId })`, not `{ _tag: 'SucceededLogin', sessionId } as Message`.
-- Always `Array.isArrayEmpty` / `Array.isArrayNonEmpty` (not `.length === 0` / `.length > 0`). Use `Array.match` when handling both empty and non-empty cases.
-- Never use `for` loops or `let` for iteration. Reach for `Array.map`, `Array.filterMap`, `Array.makeBy`, `Array.reduce`.
-- Never use `T[]`. Always `Array<T>` or `ReadonlyArray<T>`.
-- Use `Message.match` for exhaustive Message matching. Use Effect `Match` for other tagged unions, partial matching, fallbacks, and one handler shared across multiple tags. Never use `switch`.
-- Always use braces for control flow: `if (foo) { return true }`.
-- Don't add inline comments to explain code. Use better names instead. Reserve `// NOTE:` for behavior that would mislead a careful reader.
-
-## Message Layout
-
-Declare the whole Message union with `defineMessageUnion()`, then put `type Message = typeof Message.Type` on the next line:
-
-```ts
-const Message = defineMessageUnion({
-  ClickedSubmit: {},
-  UpdatedEmail: { value: S.String },
-})
-type Message = typeof Message.Type
-```
-
-Keep the `defineMessageUnion()` declaration and `type Message` alias adjacent. Construct values through the namespace (`Message.ClickedSubmit()`) and handle the union with `Message.match`. Never destructure constructors from `Message` or `OutMessage`; the owning namespace stays visible at every call site.
-
-Keep each case's payload object on one line when it fits. Let Prettier wrap payloads that need more space, so the declaration remains easy to scan as one variant per line.
-
-Messages are verb-first past-tense. Common prefixes: `Clicked*`, `Updated*` (input changes and external state updates), `Submitted*`, `Pressed*`, `Selected*`, `Succeeded*` / `Failed*` (paired async results), `Completed*` (every other Command result), `Got*` (child OutMessage in the Submodel pattern).
-
-## Debugging
-
-This project ships with `@foldkit/devtools-mcp` pre-wired. When the dev server is running and the app is open in a browser, `foldkit_*` MCP tools let you inspect Model, Message history, and time-travel. Reach for them before adding `console.log` whenever the question is about state or Message flow.
-
-## Going Deeper
+## Project Notes
 
-For Submodels and OutMessage, Subscriptions, Mount / ManagedResource / CustomElement, field validation, routing, accessibility, and the full convention set, read the live Foldkit code in `repos/foldkit/`. The `examples/` directory and the production apps (`packages/typing-game/`, `packages/website/`) are the highest-fidelity references for any specific pattern. The `foldkit-skills` plugin's `generate-program` and `audit-program` skills carry written snapshot guides if you want a structured walkthrough.
+Domain vocabulary, deployment steps, local conventions that differ from Foldkit's defaults: write them here.

package/dist/templates/base/FOLDKIT.md

@@ -0,0 +1,144 @@
+# Foldkit Conventions
+
+Foldkit owns this file. `create-foldkit-app` writes it and upgrades replace it whole, so anything added here is lost. Project-specific instructions go in `AGENTS.md`.
+
+This is a Foldkit app, a framework built on Effect-TS, architected like Elm.
+
+## Getting the canonical references
+
+The live Foldkit code is the canonical reference for everything: which APIs exist, what idiomatic apps look like, what the current conventions are. Written docs (including this one) can drift; the code can't.
+
+If `./repos/foldkit` exists, it contains the full Foldkit repository, vendored in as a git subtree. Read from it directly:
+
+- `repos/foldkit/examples/`: runnable example apps spanning every complexity tier. Usually your first stop when looking for a precedent for how to write something.
+- `repos/foldkit/packages/foldkit/src/`: framework source. Ground truth for API signatures.
+- `repos/foldkit/packages/typing-game/client/src/` and `repos/foldkit/packages/website/src/`: production apps built with Foldkit. Highest-fidelity reference for application architecture, Submodels, and OutMessage.
+
+Treat the subtree as read-only reference: never import from `repos/foldkit/` in your project source. Imports must come from the `foldkit` npm package.
+
+If `./repos/foldkit` does not exist and `AGENTS.md` says `subtree_prompted: false`, offer to run `git subtree add --prefix=repos/foldkit https://github.com/foldkit/foldkit.git main --squash`. This gives you access to the full source, examples, and docs. Whether the user accepts or declines, set that line in `AGENTS.md` to `true` so it isn't asked again.
+
+If `foldkit-skills` is installed as a Claude Code plugin, the `generate-program` and `audit-program` skills carry snapshot architecture and conventions guides synced from the live code.
+
+## Keeping this file current
+
+Foldkit's APIs and conventions change, and this file changes with them. A stale copy sends agents after APIs the installed packages no longer export.
+
+Replace it whenever the project upgrades its Foldkit packages. If `./repos/foldkit` exists, copy `repos/foldkit/packages/create-foldkit-app/templates/base/FOLDKIT.md` over this file. Otherwise take the [current template on GitHub](https://github.com/foldkit/foldkit/blob/main/packages/create-foldkit-app/templates/base/FOLDKIT.md). There is nothing here to merge or preserve.
+
+## Project Conventions
+
+- Foldkit is tightly coupled to the Effect ecosystem. Do not suggest solutions outside of Effect-TS.
+- Model fields must be Schema types (the model is a schema). Plain TypeScript types are fine elsewhere (function return types, local variables, etc.).
+- Use full names like `Message` (not `Msg`), and `withReturnType` (not `as const` or type casting).
+- Use `defineMessageUnion()` for Message unions, `ts()` for tagged structs (Model states, field validation), and `r()` for route schemas.
+- Push back on any direction that violates Elm Architecture principles: unidirectional data flow, messages as facts (not commands), model as single source of truth, side effects confined to commands. If a prompt suggests mutating state, imperative event handlers, or two-way bindings, flag the issue and propose the idiomatic Foldkit approach.
+- Never use `NoOp`. Every message must describe what happened. A command's result message is named from the command, not from the fact it reports, whether or not it carries a payload: `LockScroll` → `CompletedLockScroll`, `DetermineStartTime` → `CompletedDetermineStartTime` (never `DeterminedStartTime`).
+
+## Foldkit Patterns
+
+### Update
+
+`init` and `update` both return a record with the next Model and optional Commands. Inline the return type when the matcher is its only use:
+
+```ts
+const update = (model: Model, message: Message) =>
+  Message.match<Update.Return<Model, Message>>(message, {
+    ClickedIncrement: () => ({
+      model: evo(model, { count: count => count + 1 }),
+    }),
+  })
+```
+
+Create an `UpdateReturn` alias when another matcher, helper, or exported signature reuses the type. The match generic constrains the whole update, so do not repeat the return annotation on the function.
+
+Update, init, boot, and component helper producers return `{ model }` when they statically create no Commands. When they compute a Commands collection, return it directly without checking whether it is empty. Never write the literal `commands: []`; `foldkit/no-empty-commands-array` enforces this producer convention.
+
+When composing one of those results, bind the whole result to a value named after the operation and access its fields through that value. Use `homeInit`, `dialogClose`, or a trailing underscore such as `init_` when the operation name collides with the function. Do not destructure or rename `model`, `commands`, or `outMessage`. Dot access does not prevent someone from ignoring `outMessage`; it keeps the operation and all of its returned fields visible together. Name a child fold's `write` parameter after the next child Model, such as `nextSettings`.
+
+Pass optional Commands directly to APIs that accept them: `Command.mapMessages(homeInit.commands, toParentMessage)`. Use `result.commands ?? []` only when the next operation requires a concrete array for spreading, concatenating, execution, or an assertion.
+
+`Update.Return<Model, Message>` rejects an OutMessage-producing result where an API would consume only its Model and Commands. `Update.ReturnWithOutMessage<Model, Message, OutMessage>` still accepts a result with no `outMessage`, because omission means the update emitted nothing.
+
+Manual unpacking of a child result usually means the site should use `Update.foldChild` or `Update.foldChildStep`.
+
+Use `Update.combine` when a later Step should receive the Model produced by an earlier Step. It takes two or more Steps. Do not wrap one Step in `Update.combine`; call that operation directly. Name an inline Step parameter `stepModel`; it contains the Model produced by the preceding Step.
+
+When the OutMessage is already known while constructing a new result, include it directly: `{ model, commands, outMessage }`. Use `Update.withOutMessage` when attaching an OutMessage to an existing plain return or when the value has the type `OutMessage | undefined`. Pipe an existing return into the helper: `pipe(dialogClose, Update.withOutMessage(outMessage))`. When constructing the plain return in the same expression, pass it first: `Update.withOutMessage({ model, commands }, outMessage)`.
+
+Add `toParentOutMessage` only when at least one child OutMessage is forwarded from the current Submodel to its parent. Omit it when no variant is forwarded. Local handling through `foldOutMessage` is independent, so a forwarded variant may also update the current parent. Never write `toParentOutMessage: () => undefined`.
+
+Use `evo()` from `foldkit/struct` for immutable model updates. Never spread or `Object.assign`.
+
+### View
+
+Every view receives `h`, the typed Html builder, as its last parameter (`view: (model, h) => ...`; `Submodel.defineView` passes the child's own). Never construct a builder; reach for `h.div`, `h.OnClick`, etc. off the parameter, and give extracted view helpers an `h: HtmlBuilder<Message>` last parameter that callers thread through. Only where no builder is in scope, typically module scope, use `inertHtml` from `foldkit/html`, aliased `ih` so the two builders stay distinguishable. Use `h.empty` (not `null`) for conditional rendering, `M.value().pipe(M.tagsExhaustive({...}))` for discriminated unions, and `Array.match` for lists that may be empty.
+
+Keys are for mapped list items only: key each row by a stable Model identifier (`h.keyed('li')(item.id, [], [...])`), never by array position, and never derive a key from displayed data. Never key branches; the build gives each view function's output its own identity, so branch switches replace DOM automatically. When switching an inline same-tag ternary must reset DOM state, extract each arm into its own named view function.
+
+Omit the children argument when an element has none: `h.div([h.Class('divider')])`, never `h.div([h.Class('divider')], [])`. The same holds for `keyed`: `h.keyed('li')(key, [attrs])`, never `h.keyed('li')(key, [attrs], [])`. Attributes stay required on element builders, so `h.div([])` is an element with neither. Sibling elements that end up at different arities are expected and fine; void elements like `h.img` have always read that way.
+
+### Commands
+
+Define a Command with `Command.define(name, { args, messages, execute })`; omit `args` when the Command takes none. Assign definitions to PascalCase constants. Never inline in pipe chains. Name the effect `execute` performs, not the later Model transition caused when update handles its result: a timer that only waits before update starts a dismissal is `WaitBeforeDismissal`, not `DismissAfter`. Commands catch all errors via `Effect.catch(() => Effect.succeed(Message.FailedX(...)))` so side effects never crash the app. Definitions live colocated with the update function that returns them.
+
+For the with-args shape, see `repos/foldkit/examples/weather/src/main.ts` or `repos/foldkit/examples/kanban/src/command.ts`. For an argless DOM-side-effect Command, the argless form in `kanban/src/command.ts` (`FocusAddCardInput`) is the canonical reference.
+
+For DOM operations (focus, scroll, modals, scroll lock), Foldkit ships a `Dom` module. For time, randomness, UUIDs, and delays, use Effect's built-ins directly (`Clock`, `Random`, `Effect.uuid`, `Effect.sleep`). Don't reach for raw `document.querySelector`, `setTimeout`, `Date.now()`, or `Math.random()`.
+
+### File Organization
+
+The invariant: keep the runtime boot separate from the pure definitions. `src/entry.ts` calls `Runtime.makeApplication` and `Runtime.run`, and `index.html` references it. The definitions (Model, Messages, init, update, view, Commands) never call `Runtime.run`, so they stay importable from tests without booting a runtime as a side effect. Never call `Runtime.run` from `main.ts`.
+
+For a small app the definitions all fit in one `src/main.ts`. Split a unit into its own file when it has _both_ a distinct reason to change _and_ a name you'd give it unprompted: the pure domain core into `timer.ts` or `domain.ts`, the view into `view.ts` (or a `components/` directory), a Command's owned resource into its own module. Split on that revealed seam, not on line count alone. A file that has grown large is _evidence_ a seam has formed, so treat its size as a prompt to re-check for one. Two splits are forced: extract Messages to `message.ts` when Commands need the constructors (this breaks the cycle between `command.ts` and `main.ts`), and colocate Commands with the update that returns them. Exemplars: counter and stopwatch are a single `main.ts`; kanban splits `domain` / `command` / `message` / `model`; typing-game splits views by page.
+
+Use uppercase section headers (`// MODEL`, `// MESSAGE`, `// INIT`, `// UPDATE`, `// COMMAND`, `// VIEW`) for wayfinding.
+
+### Testing
+
+Test update functions with `foldkit/test`. Since update is pure, tests run without a runtime, DOM, or side effects. Use `story` for update-level tests (send Messages, assert on Model and Commands) and `scene` for feature-level testing through the view with accessible locators.
+
+Import the steps as named imports from `foldkit/story` or `foldkit/scene`: `import { Command, given, message, model, story } from 'foldkit/story'`. A test file needs only one of the two modules. If a single file ever tests both, import the namespaces instead (`import { Scene, Story } from 'foldkit'`) so `Story.given` and `Scene.given` stay distinguishable.
+
+Name each test file for its test style, beside the code under test: `story.test.ts` for the Story tests (which drive `update`) and `scene.test.ts` for the Scene tests (which drive the rendered view). The name describes how the test works, not a source file, so it stays correct whether `update` and `view` live in `main.ts` or in their own files. A test file lives in the folder that holds the code it drives, so in a multi-page app most of them sit in a page folder rather than at the root. When one folder holds more than one test of a kind (sibling pages, component variants), prefix with the subject: `login.story.test.ts`.
+
+Scene runs at any level, since a page's own `update`/`view` pair drops into `scene` unmodified. Put a `scene.test.ts` in the page folder for behavior that page owns, which covers view states awkward to reach through the root Model, and keep a root-level `scene.test.ts` for flows that cross pages, which covers how the parent folds an OutMessage, a Command the parent lifts, a route change, and view inputs the parent computes. If the `repos/foldkit` subtree is available, study the `story.test.ts` and `scene.test.ts` files in `repos/foldkit/examples/`. `repos/foldkit/examples/auth` is the multi-page shape: a root `src/scene.test.ts` for the cross-page login flow alongside `src/page/loggedOut/page/login.scene.test.ts` and `login.story.test.ts` driving that page's own pair.
+
+## Code Style
+
+- Encode state in discriminated unions, not booleans or nullable fields. `Idle | Loading | Error | Ok`, not `isLoading: boolean`. Make impossible states unrepresentable.
+- Use `Option` for absence in the Model and domain values instead of `null` or `undefined`. Foldkit return records are the exception: omit `commands` and `outMessage` when absent. A partial `toParentOutMessage` mapper returns `undefined` for each named child variant that stops at the current parent. Prefix Option-typed values with `maybe*`. Match with `Option.match`; don't unwrap with `Option.map(...)` + `Option.getOrElse(...)` when you can just match.
+- Use Effect modules over native methods in `pipe` chains (`Array.map`, `String.startsWith`, `Array.findFirst`). Native methods are fine when calling directly on a named variable.
+- Never cast Schema values with `as Type`. Use the callable constructor: `Message.SucceededLogin({ sessionId })`, not `{ _tag: 'SucceededLogin', sessionId } as Message`.
+- Always `Array.isArrayEmpty` / `Array.isArrayNonEmpty` (not `.length === 0` / `.length > 0`). Use `Array.match` when handling both empty and non-empty cases.
+- Never use `for` loops or `let` for iteration. Reach for `Array.map`, `Array.filterMap`, `Array.makeBy`, `Array.reduce`.
+- Never use `T[]`. Always `Array<T>` or `ReadonlyArray<T>`.
+- Use `Message.match` for exhaustive Message matching. Use Effect `Match` for other tagged unions, partial matching, fallbacks, and one handler shared across multiple tags. Never use `switch`.
+- Always use braces for control flow: `if (foo) { return true }`.
+- Don't add inline comments to explain code. Use better names instead. Reserve `// NOTE:` for behavior that would mislead a careful reader.
+
+## Message Layout
+
+Declare the whole Message union with `defineMessageUnion()`, then put `type Message = typeof Message.Type` on the next line:
+
+```ts
+const Message = defineMessageUnion({
+  ClickedSubmit: {},
+  UpdatedEmail: { value: S.String },
+})
+type Message = typeof Message.Type
+```
+
+Keep the `defineMessageUnion()` declaration and `type Message` alias adjacent. Construct values through the namespace (`Message.ClickedSubmit()`) and handle the union with `Message.match`. Never destructure constructors from `Message` or `OutMessage`; the owning namespace stays visible at every call site.
+
+Keep each case's payload object on one line when it fits. Let Prettier wrap payloads that need more space, so the declaration remains easy to scan as one variant per line.
+
+Messages are verb-first past-tense. Common prefixes: `Clicked*`, `Updated*` (input changes and external state updates), `Submitted*`, `Pressed*`, `Selected*`, `Succeeded*` / `Failed*` (paired async results), `Completed*` (every other Command result), `Got*` (child OutMessage in the Submodel pattern).
+
+## Debugging
+
+This project ships with `@foldkit/devtools-mcp` pre-wired. When the dev server is running and the app is open in a browser, `foldkit_*` MCP tools let you inspect Model, Message history, and time-travel. Reach for them before adding `console.log` whenever the question is about state or Message flow.
+
+## Going Deeper
+
+For Submodels and OutMessage, Subscriptions, Mount / ManagedResource / CustomElement, field validation, routing, accessibility, and the full convention set, read the live Foldkit code in `repos/foldkit/`. The `examples/` directory and the production apps (`packages/typing-game/`, `packages/website/`) are the highest-fidelity references for any specific pattern. The `foldkit-skills` plugin's `generate-program` and `audit-program` skills carry written snapshot guides if you want a structured walkthrough.

package/dist/templates/examples/api-cache/src/main.ts

@@ -90,18 +90,18 @@ export type Message = typeof Message.Type
 
 // UPDATE
 
-type UpdateReturn = readonly [Model, ReadonlyArray<Command.Command<Message>>]
+type UpdateReturn = Update.Return<Model, Message>
 
 const applyPostsTransition = (
   model: Model,
   maybeNextPosts: Option.Option<PostsData>,
 ): UpdateReturn =>
   Option.match(maybeNextPosts, {
-    onNone: () => [model, []],
-    onSome: nextPosts => [
-      evo(model, { posts: () => nextPosts }),
-      [FetchPosts()],
-    ],
+    onNone: () => ({ model }),
+    onSome: nextPosts => ({
+      model: evo(model, { posts: () => nextPosts }),
+      commands: [FetchPosts()],
+    }),
   })
 
 const applyStatsTransition = (
@@ -109,11 +109,11 @@ const applyStatsTransition = (
   maybeNextStats: Option.Option<StatsData>,
 ): UpdateReturn =>
   Option.match(maybeNextStats, {
-    onNone: () => [model, []],
-    onSome: nextStats => [
-      evo(model, { stats: () => nextStats }),
-      [FetchStats()],
-    ],
+    onNone: () => ({ model }),
+    onSome: nextStats => ({
+      model: evo(model, { stats: () => nextStats }),
+      commands: [FetchStats()],
+    }),
   })
 
 const setPostDetail = (postId: string, postDetail: PostDetailData) =>
@@ -168,20 +168,19 @@ export const update = (model: Model, message: Message) =>
       })
 
       return Option.match(HashMap.get(model.postDetailById, postId), {
-        onNone: () => [
-          evo(selectedModel, {
+        onNone: () => ({
+          model: evo(selectedModel, {
             postDetailById: setPostDetail(postId, PostDetailData.Loading()),
           }),
-          [FetchPostDetail({ postId })],
-        ],
-        onSome: () => [selectedModel, []],
+          commands: [FetchPostDetail({ postId })],
+        }),
+        onSome: () => ({ model: selectedModel }),
       })
     },
 
-    ClickedBackToPosts: () => [
-      evo(model, { maybeSelectedPostId: () => Option.none() }),
-      [],
-    ],
+    ClickedBackToPosts: () => ({
+      model: evo(model, { maybeSelectedPostId: () => Option.none() }),
+    }),
 
     ClickedInvalidatePosts: () =>
       applyPostsTransition(model, AsyncData.revalidateOrLoad(model.posts)),
@@ -189,12 +188,12 @@ export const update = (model: Model, message: Message) =>
     ClickedRetryPosts: () =>
       applyPostsTransition(model, AsyncData.revalidateOrLoad(model.posts)),
 
-    ClickedRetryPostDetail: ({ postId }) => [
-      evo(model, {
+    ClickedRetryPostDetail: ({ postId }) => ({
+      model: evo(model, {
         postDetailById: setPostDetail(postId, PostDetailData.Loading()),
       }),
-      [FetchPostDetail({ postId })],
-    ],
+      commands: [FetchPostDetail({ postId })],
+    }),
 
     ClickedRefreshStats: () =>
       applyStatsTransition(model, AsyncData.revalidateOrLoad(model.stats)),
@@ -205,28 +204,25 @@ export const update = (model: Model, message: Message) =>
     TickedRevalidateStats: () =>
       applyStatsTransition(model, AsyncData.revalidate(model.stats)),
 
-    SettledFetchPosts: ({ result }) => [
-      evo(model, { posts: AsyncData.settle(result) }),
-      [],
-    ],
+    SettledFetchPosts: ({ result }) => ({
+      model: evo(model, { posts: AsyncData.settle(result) }),
+    }),
 
-    SettledFetchPostDetail: ({ postId, result }) => [
-      evo(model, {
+    SettledFetchPostDetail: ({ postId, result }) => ({
+      model: evo(model, {
         postDetailById: HashMap.modify(postId, AsyncData.settle(result)),
       }),
-      [],
-    ],
+    }),
 
-    SettledFetchStats: ({ result }) => [
-      evo(model, { stats: AsyncData.settle(result) }),
-      [],
-    ],
+    SettledFetchStats: ({ result }) => ({
+      model: evo(model, { stats: AsyncData.settle(result) }),
+    }),
   })
 
 // INIT
 
-export const init: Runtime.ApplicationInit<Model, Message> = () => [
-  {
+export const init: Runtime.ApplicationInit<Model, Message> = () => ({
+  model: {
     tabs: Tabs.init({ id: TABS_ID }),
     activeTab: 'Posts',
     posts: PostsData.Loading(),
@@ -234,8 +230,8 @@ export const init: Runtime.ApplicationInit<Model, Message> = () => [
     maybeSelectedPostId: Option.none(),
     stats: StatsData.Idle(),
   },
-  [FetchPosts()],
-]
+  commands: [FetchPosts()],
+})
 
 // COMMAND
 

package/dist/templates/examples/auth/src/main.ts

@@ -1,6 +1,6 @@
 import { Effect, Match as M, Option, Schema as S } from 'effect'
 import { KeyValueStore } from 'effect/unstable/persistence'
-import { Command, Runtime } from 'foldkit'
+import { Runtime, type Update } from 'foldkit'
 import { Url } from 'foldkit/url'
 
 import { BrowserKeyValueStore } from '@effect/platform-browser'
@@ -39,7 +39,7 @@ export type Flags = typeof Flags.Type
 
 // INIT
 
-type InitReturn = [Model, ReadonlyArray<Command.Command<Message>>]
+type InitReturn = Update.Return<Model, Message>
 const withInitReturn = M.withReturnType<InitReturn>()
 
 export const init: Runtime.RoutingApplicationInit<Model, Message, Flags> = (
@@ -52,24 +52,25 @@ export const init: Runtime.RoutingApplicationInit<Model, Message, Flags> = (
     onNone: () =>
       M.value(route).pipe(
         withInitReturn,
-        M.tag('Home', 'Login', 'NotFound', route => [
-          LoggedOut.init(route),
-          [],
-        ]),
-        M.orElse(() => [LoggedOut.init(LoginRoute()), [RedirectToLogin()]]),
+        M.tag('Home', 'Login', 'NotFound', route => ({
+          model: LoggedOut.init(route),
+        })),
+        M.orElse(() => ({
+          model: LoggedOut.init(LoginRoute()),
+          commands: [RedirectToLogin()],
+        })),
       ),
 
     onSome: session =>
       M.value(route).pipe(
         withInitReturn,
-        M.tag('Dashboard', 'Settings', 'NotFound', route => [
-          LoggedIn.init(route, session),
-          [],
-        ]),
-        M.orElse(() => [
-          LoggedIn.init(DashboardRoute(), session),
-          [RedirectToDashboard()],
-        ]),
+        M.tag('Dashboard', 'Settings', 'NotFound', route => ({
+          model: LoggedIn.init(route, session),
+        })),
+        M.orElse(() => ({
+          model: LoggedIn.init(DashboardRoute(), session),
+          commands: [RedirectToDashboard()],
+        })),
       ),
   })
 }

package/dist/templates/examples/auth/src/page/loggedIn/update.ts

@@ -1,16 +1,15 @@
-import { Option } from 'effect'
-import { Command } from 'foldkit'
+import { type Update } from 'foldkit'
 
 import { Message, OutMessage } from './message'
 import { Model } from './model'
 
-type UpdateReturn = readonly [
-  Model,
-  ReadonlyArray<Command.Command<Message>>,
-  Option.Option<OutMessage>,
-]
-
 export const update = (model: Model, message: Message) =>
-  Message.match<UpdateReturn>(message, {
-    ClickedLogout: () => [model, [], Option.some(OutMessage.RequestedLogout())],
-  })
+  Message.match<Update.ReturnWithOutMessage<Model, Message, OutMessage>>(
+    message,
+    {
+      ClickedLogout: () => ({
+        model,
+        outMessage: OutMessage.RequestedLogout(),
+      }),
+    },
+  )

package/dist/templates/examples/auth/src/page/loggedOut/page/login.ts

@@ -9,7 +9,7 @@ import {
   String,
   pipe,
 } from 'effect'
-import { Command, Submodel } from 'foldkit'
+import { Command, Submodel, type Update } from 'foldkit'
 import {
   Field,
   Invalid,
@@ -86,12 +86,6 @@ const isFormValid = (model: Model): boolean =>
 
 // UPDATE
 
-type UpdateReturn = readonly [
-  Model,
-  ReadonlyArray<Command.Command<Message>>,
-  Option.Option<OutMessage>,
-]
-
 export const SimulateAuthRequest = Command.define('SimulateAuthRequest', {
   args: { email: S.String, password: S.String },
   messages: [
@@ -122,59 +116,54 @@ export const SimulateAuthRequest = Command.define('SimulateAuthRequest', {
 })
 
 export const update = (model: Model, message: Message) =>
-  Message.match<UpdateReturn>(message, {
-    ChangedEmail: ({ value }) => [
-      evo(model, { email: () => validateEmail(value) }),
-      [],
-      Option.none(),
-    ],
-
-    ChangedPassword: ({ value }) => [
-      evo(model, { password: () => validatePassword(value) }),
-      [],
-      Option.none(),
-    ],
-
-    SubmittedForm: () => {
-      if (model.isSubmitting) {
-        return [model, [], Option.none()]
-      }
+  Message.match<Update.ReturnWithOutMessage<Model, Message, OutMessage>>(
+    message,
+    {
+      ChangedEmail: ({ value }) => ({
+        model: evo(model, { email: () => validateEmail(value) }),
+      }),
 
-      if (!isFormValid(model)) {
-        return [model, [], Option.none()]
-      }
+      ChangedPassword: ({ value }) => ({
+        model: evo(model, { password: () => validatePassword(value) }),
+      }),
 
-      return [
-        evo(model, { isSubmitting: () => true }),
-        [
-          SimulateAuthRequest({
-            email: model.email.value,
-            password: model.password.value,
-          }),
-        ],
-        Option.none(),
-      ]
-    },
+      SubmittedForm: () => {
+        if (model.isSubmitting) {
+          return { model }
+        }
+
+        if (!isFormValid(model)) {
+          return { model }
+        }
+
+        return {
+          model: evo(model, { isSubmitting: () => true }),
+          commands: [
+            SimulateAuthRequest({
+              email: model.email.value,
+              password: model.password.value,
+            }),
+          ],
+        }
+      },
 
-    SucceededSimulateAuthRequest: ({ session }) => [
-      model,
-      [],
-      Option.some(OutMessage.SucceededLogin({ session })),
-    ],
+      SucceededSimulateAuthRequest: ({ session }) => ({
+        model,
+        outMessage: OutMessage.SucceededLogin({ session }),
+      }),
 
-    FailedSimulateAuthRequest: ({ error }) => [
-      evo(model, {
-        password: () =>
-          Invalid({
-            value: model.password.value,
-            errors: [error],
-          }),
-        isSubmitting: () => false,
+      FailedSimulateAuthRequest: ({ error }) => ({
+        model: evo(model, {
+          password: () =>
+            Invalid({
+              value: model.password.value,
+              errors: [error],
+            }),
+          isSubmitting: () => false,
+        }),
       }),
-      [],
-      Option.none(),
-    ],
-  })
+    },
+  )
 
 // VIEW