@remix-run/cli 0.3.0 → 0.3.2

package/template/.agents/skills/remix/references/animate-elements.md

@@ -2,23 +2,20 @@
 
 ## What This Covers
 
-How to animate insertion, removal, and layout changes of elements. Read this when the task
-involves:
+How to animate insertion, removal, and layout changes of elements. Read this when the task involves:
 
 - Adding entrance, exit, or shared-layout transitions to UI
 - Choosing between spring physics (`spring(...)`) and time-based easing (`tween`)
 - Coordinating CSS transitions with the same easing as JS animations
 - Imperative animation loops via `requestAnimationFrame`
 
-Import animation APIs from `remix/ui/animation`. For the smaller set of animation helpers that
-show up alongside other mixins, see `mixins-styling-events.md`.
+Import animation APIs from `remix/ui/animation`. For the smaller set of animation helpers that show up alongside other mixins, see `mixins-styling-events.md`.
 
 ## Animation Mixins
 
 ### `animateEntrance(config)`
 
-Animates an element when inserted. Config specifies the **starting** style the element animates
-**from**:
+Animates an element when inserted. Config specifies the **starting** style the element animates **from**:
 
 ```tsx
 <div
@@ -32,8 +29,7 @@ Animates an element when inserted. Config specifies the **starting** style the e
 
 ### `animateExit(config)`
 
-Animates an element when removed. Config specifies the **ending** style the element animates
-**to**. The element stays in the DOM until the animation completes:
+Animates an element when removed. Config specifies the **ending** style the element animates **to**. The element stays in the DOM until the animation completes:
 
 ```tsx
 {
@@ -61,8 +57,7 @@ Animates layout changes (position/size) using FLIP-style transforms:
 }
 ```
 
-Options: `duration` (default 200ms), `easing` (default spring snappy), `size` (default true —
-include scale projection for size changes).
+Options: `duration` (default 200ms), `easing` (default spring snappy), `size` (default true — include scale projection for size changes).
 
 ### Combining mixins
 
@@ -91,8 +86,7 @@ include scale projection for size changes).
 
 ## Spring API
 
-Physics-based spring animation. Returns a `SpringIterator` with `duration`, `easing`, and
-`toString()` for CSS.
+Physics-based spring animation. Returns a `SpringIterator` with `duration`, `easing`, and `toString()` for CSS.
 
 ### Presets
 
@@ -159,9 +153,7 @@ for (let t of spring('bouncy')) {
 
 ## Tween API
 
-Generator-based tween for animating values over time with cubic bezier easing. Prefer animation
-mixins or CSS transitions with `spring` for most UI work. Use `tween` for imperative
-`requestAnimationFrame` loops, canvas/WebGL, or non-CSS properties.
+Generator-based tween for animating values over time with cubic bezier easing. Prefer animation mixins or CSS transitions with `spring` for most UI work. Use `tween` for imperative `requestAnimationFrame` loops, canvas/WebGL, or non-CSS properties.
 
 ```tsx
 import { tween, easings } from 'remix/ui/animation'
@@ -183,8 +175,7 @@ function tick(timestamp: number) {
 requestAnimationFrame(tick)
 ```
 
-Built-in easings: `easings.linear`, `easings.ease`, `easings.easeIn`, `easings.easeOut`,
-`easings.easeInOut`.
+Built-in easings: `easings.linear`, `easings.ease`, `easings.easeIn`, `easings.easeOut`, `easings.easeInOut`.
 
 ## Practical Guidance
 

package/template/.agents/skills/remix/references/assets-and-browser-modules.md

@@ -4,25 +4,18 @@
 
 How to serve browser scripts and styles from source. Read this when the task involves:
 
-- Configuring `createAssetServer` (`basePath`, `fileMap`, `allow`, `deny`, fingerprinting,
-  compiler options)
-- Choosing between `staticFiles()` for already-built files and `createAssetServer()` for source
-  assets that need import rewriting, preloads, or fingerprinted URLs
+- Configuring `createAssetServer` (`basePath`, `fileMap`, `allow`, `deny`, fingerprinting, compiler options)
+- Choosing between `staticFiles()` for already-built files and `createAssetServer()` for source assets that need import rewriting, preloads, or fingerprinted URLs
 - Generating script URLs or `<link rel="modulepreload">` tags for a client entry
 - Keeping server-only files out of the browser via `deny` rules
 
-For routing the URL namespace itself, see `routing-and-controllers.md`. For client entry
-hydration, see `hydration-frames-navigation.md`.
+For routing the URL namespace itself, see `routing-and-controllers.md`. For client entry hydration, see `hydration-frames-navigation.md`.
 
 ## When To Reach For It
 
-Use `remix/assets` when the app serves browser JavaScript, TypeScript, or CSS from source files.
-This is the right tool for client entrypoints, browser-only helpers, styles under `app/assets/`,
-and monorepo code that should be compiled and served under a public URL namespace.
+Use `remix/assets` when the app serves browser JavaScript, TypeScript, or CSS from source files. This is the right tool for client entrypoints, browser-only helpers, styles under `app/assets/`, and monorepo code that should be compiled and served under a public URL namespace.
 
-Use `staticFiles()` for files that already exist on disk exactly as they should be served. Use
-`createAssetServer()` for source scripts or styles that need rewriting, dependency scanning,
-preloads, sourcemaps, or fingerprinted URLs.
+Use `staticFiles()` for files that already exist on disk exactly as they should be served. Use `createAssetServer()` for source scripts or styles that need rewriting, dependency scanning, preloads, sourcemaps, or fingerprinted URLs.
 
 ## Default Pattern
 
@@ -66,22 +59,16 @@ export default createController(routes, {
 ## Rules
 
 - Treat `allow` and `deny` as the security boundary for browser-reachable source files.
-- Add a `deny` list for server-only modules such as `*.server.*`, private config, or other files
-  that should never be exposed.
+- Add a `deny` list for server-only modules such as `*.server.*`, private config, or other files that should never be exposed.
 - Set `rootDir` explicitly in monorepos so relative paths resolve from the intended project root.
 - `basePath` is the public URL namespace handled by the asset server.
-- `fileMap` keys are URL patterns relative to `basePath`, and values are root-relative file path
-  patterns. They use `route-pattern` syntax on both sides.
-- Keep the same wildcard params on both sides of a `fileMap` entry so import rewriting can map
-  source files back to public URLs.
-- CSS files are compiled and served alongside scripts. Local CSS `@import` rules are rewritten and
-  fingerprinted with the same asset server routing rules.
+- `fileMap` keys are URL patterns relative to `basePath`, and values are root-relative file path patterns. They use `route-pattern` syntax on both sides.
+- Keep the same wildcard params on both sides of a `fileMap` entry so import rewriting can map source files back to public URLs.
+- CSS files are compiled and served alongside scripts. Local CSS `@import` rules are rewritten and fingerprinted with the same asset server routing rules.
 
 ## Rendering HTML
 
-Use `getHref()` when you need the public URL for one module, and `getPreloads()` when you want
-`<link rel="modulepreload">` tags or `Link` headers for one or more entrypoints and their
-dependencies.
+Use `getHref()` when you need the public URL for one module, and `getPreloads()` when you want `<link rel="modulepreload">` tags or `Link` headers for one or more entrypoints and their dependencies.
 
 ```typescript
 let entryHref = await assetServer.getHref('app/assets/entry.ts')
@@ -90,10 +77,7 @@ let preloads = await assetServer.getPreloads(['app/assets/entry.ts'])
 
 Use this when rendering documents or layouts that boot browser behavior with a known client entry.
 
-When resolving hydrated client entries during server rendering, pass the source entry ID from
-`clientEntry(import.meta.url, ...)` to `getHref()` inside `resolveClientEntry`. Keep export-name
-resolution in that render helper, and avoid hard-coding public asset URLs in source-owned component
-modules.
+When resolving hydrated client entries during server rendering, pass the source entry ID from `clientEntry(import.meta.url, ...)` to `getHref()` inside `resolveClientEntry`. Keep export-name resolution in that render helper, and avoid hard-coding public asset URLs in source-owned component modules.
 
 ## Development vs Deployment
 
@@ -116,15 +100,12 @@ Fingerprinting assumes files on disk are stable and requires `watch: false`.
 - `minify` for production minification of scripts and styles
 - `sourceMaps` for `'external'` or `'inline'` source maps for scripts and styles
 - `sourceMapSourcePaths` for `'url'` or `'absolute'` source map paths
-- `target` as an object for shared browser targets and script-only ECMAScript output, such as
-  `{ es: '2020', chrome: '109', safari: '16.4' }`
+- `target` as an object for shared browser targets and script-only ECMAScript output, such as `{ es: '2020', chrome: '109', safari: '16.4' }`
 - `scripts.define` to replace globals such as `process.env.NODE_ENV`
 - `scripts.external` to leave specific script imports untouched
 
-Do not nest shared compiler options under `scripts`. Use top-level `minify`, `sourceMaps`,
-`sourceMapSourcePaths`, and `target` so they apply to styles as well as scripts.
+Do not nest shared compiler options under `scripts`. Use top-level `minify`, `sourceMaps`, `sourceMapSourcePaths`, and `target` so they apply to styles as well as scripts.
 
 ## Lifecycle
 
-If the asset server is long-lived and watching the file system, call `await assetServer.close()`
-when shutting down dev servers or disposing tests.
+If the asset server is long-lived and watching the file system, call `await assetServer.close()` when shutting down dev servers or disposing tests.

package/template/.agents/skills/remix/references/auth-and-sessions.md

@@ -2,8 +2,7 @@
 
 ## What This Covers
 
-How to remember things about a browser between requests and how to identify a user. Read this when
-the task involves:
+How to remember things about a browser between requests and how to identify a user. Read this when the task involves:
 
 - Storing per-browser state across requests (login, cart, "I have submitted this form")
 - Adding a credentials login flow or an OAuth provider
@@ -11,23 +10,15 @@ the task involves:
 - Reading or writing `Session`, `Auth`, or other identity-related context values
 - Logging in, logging out, or rotating session IDs
 
-For raw cookies that are not session-backed (theme, locale, dismissed-banner), see
-`createCookie` in this file plus the broader `Package Map` in `SKILL.md`.
+For raw cookies that are not session-backed (theme, locale, dismissed-banner), see `createCookie` in this file plus the broader `Package Map` in `SKILL.md`.
 
 ## Sessions vs Plain Cookies
 
-Reach for `remix/session` when state is sensitive, must be tamper-resistant, or represents the
-identity of a request: who is logged in, which form a browser already submitted, what items are in
-a cart. Sessions sign or encrypt their backing cookie with a server-held secret and give you a
-typed `Session` object you can `get`, `set`, `flash`, `unset`, and `regenerateId`.
+Reach for `remix/session` when state is sensitive, must be tamper-resistant, or represents the identity of a request: who is logged in, which form a browser already submitted, what items are in a cart. Sessions sign or encrypt their backing cookie with a server-held secret and give you a typed `Session` object you can `get`, `set`, `flash`, `unset`, and `regenerateId`.
 
-Reach for `remix/cookie` directly when the browser is allowed to carry the value and the server
-does not need session semantics. This often means preferences (theme, locale, dismissed banner),
-but a signed cookie can also be fine for small low-risk values where you truly only need one
-cookie-shaped fact and do not need `Session` helpers.
+Reach for `remix/cookie` directly when the browser is allowed to carry the value and the server does not need session semantics. This often means preferences (theme, locale, dismissed banner), but a signed cookie can also be fine for small low-risk values where you truly only need one cookie-shaped fact and do not need `Session` helpers.
 
-If a malicious user editing the value would be a bug, or if the value needs server-managed
-lifecycle, reach for a session.
+If a malicious user editing the value would be a bug, or if the value needs server-managed lifecycle, reach for a session.
 
 ### Quick chooser
 
@@ -60,9 +51,7 @@ export let sessionCookie = createCookie('session', {
 })
 ```
 
-The cookie should always be `httpOnly`, default to `sameSite: 'Lax'`, and be `secure` in
-production. Demo defaults like `'s3cr3t'` are fine in tests but should never reach production —
-fail fast when the secret is missing.
+The cookie should always be `httpOnly`, default to `sameSite: 'Lax'`, and be `secure` in production. Demo defaults like `'s3cr3t'` are fine in tests but should never reach production — fail fast when the secret is missing.
 
 ### Create session storage
 
@@ -117,9 +106,7 @@ async function handler({ get }) {
 
 ### Sessions for non-auth state
 
-Sessions are not just for login. They are the right place to store any tamper-sensitive
-per-browser fact: which form a browser already submitted, how many free actions are left in a
-trial, which feature flags a tester opted into, what items are in a cart.
+Sessions are not just for login. They are the right place to store any tamper-sensitive per-browser fact: which form a browser already submitted, how many free actions are left in a trial, which feature flags a tester opted into, what items are in a cart.
 
 ```typescript
 async function submit({ get }) {
@@ -141,10 +128,7 @@ async function submit({ get }) {
 }
 ```
 
-Notice that there is no manual `Set-Cookie` plumbing in the action — the session middleware handles
-that, and the handler returns an ordinary `Response`. Per-browser state enforced this way is still
-bypassable by clearing cookies; if the guarantee needs to survive that, you also need an account
-(see auth providers below).
+Notice that there is no manual `Set-Cookie` plumbing in the action — the session middleware handles that, and the handler returns an ordinary `Response`. Per-browser state enforced this way is still bypassable by clearing cookies; if the guarantee needs to survive that, you also need an account (see auth providers below).
 
 ## Auth Middleware
 
@@ -296,9 +280,7 @@ let atmosphereProvider = createAtmosphereAuthProvider({
 })
 ```
 
-For Atmosphere-compatible atproto OAuth, create the provider once, call
-`atmosphereProvider.prepare(handleOrDid)` before `startExternalAuth(...)`, then pass the same
-module-scope provider to `finishExternalAuth(...)` and `refreshExternalAuth(...)`.
+For Atmosphere-compatible atproto OAuth, create the provider once, call `atmosphereProvider.prepare(handleOrDid)` before `startExternalAuth(...)`, then pass the same module-scope provider to `finishExternalAuth(...)` and `refreshExternalAuth(...)`.
 
 ### OAuth controller
 
@@ -336,10 +318,7 @@ export default createController(routes.auth.google, {
 
 ### Refresh stored provider tokens
 
-Use `refreshExternalAuth(provider, tokens)` when an app has stored OAuth/OIDC tokens and needs a
-fresh access token from a refresh token. Built-in OIDC providers, X, and Atmosphere support
-refresh-token exchange. If the provider does not rotate the refresh token, the refreshed bundle
-preserves the current one.
+Use `refreshExternalAuth(provider, tokens)` when an app has stored OAuth/OIDC tokens and needs a fresh access token from a refresh token. Built-in OIDC providers, X, and Atmosphere support refresh-token exchange. If the provider does not rotate the refresh token, the refreshed bundle preserves the current one.
 
 ```typescript
 async function refreshGoogleTokens({ get }) {

package/template/.agents/skills/remix/references/component-model.md

@@ -2,25 +2,23 @@
 
 ## What This Covers
 
-How a Remix Component is shaped and how its state, lifecycle, and updates behave. Read this when
-the task involves:
+How a Remix Component is shaped and how its state, lifecycle, and updates behave. Read this when the task involves:
 
 - Writing a component (`handle` plus render function)
 - Managing component-local state, derived values, or post-render DOM work
-- Using `handle.props`, `handle.update()`, `handle.queueTask()`, `handle.signal`, `handle.id`, or
-  `handle.context`
+- Using `handle.props`, `handle.update()`, `handle.queueTask()`, `handle.signal`, `handle.id`, or `handle.context`
 - Listening to global events with cleanup tied to the component lifecycle
 
-For host-element behavior (event handlers, styles, refs, animations), see
-`mixins-styling-events.md`. For browser hydration, frames, and navigation, see
-`hydration-frames-navigation.md`.
+For host-element behavior (event handlers, styles, refs, animations), see `mixins-styling-events.md`. For browser hydration, frames, and navigation, see `hydration-frames-navigation.md`.
 
 ## Phases
 
 A component has two phases:
 
 1. **Setup phase** — runs once when the component is created
-2. **Render phase** — returned function runs on initial render and every update
+2. **Render phase** — returned zero-argument function runs on initial render and every update
+
+The component shape is `function Component(handle: Handle<Props>) { return () => ... }`. Props are available as `handle.props` in setup scope and are updated before every render.
 
 ```tsx
 import { on, type Handle } from 'remix/ui'
@@ -43,9 +41,7 @@ function Counter(handle: Handle<{ initialCount?: number; label: string }>) {
 
 ## Props
 
-Components receive all JSX props through `handle.props`. The object identity is stable for the
-component lifetime, and its values are updated before each render. Put initialization inputs on
-normal JSX props and read them from `handle.props`:
+Components receive all JSX props through `handle.props`. The object identity is stable for the component lifetime, and its values are updated before each render. Put initialization inputs on normal JSX props and read them from `handle.props`:
 
 ```tsx
 function Timer(handle: Handle<{ initialSeconds: number; paused?: boolean }>) {
@@ -57,9 +53,7 @@ function Timer(handle: Handle<{ initialSeconds: number; paused?: boolean }>) {
 // Usage: <Timer initialSeconds={60} paused={false} />
 ```
 
-Because `handle.props` is stable, destructuring `let { props } = handle` is safe when helpers need
-to read current values later. Destructuring individual prop values is only a snapshot; prefer
-`handle.props.name` inside callbacks and render output when values can change.
+Because `handle.props` is stable, destructuring `let { props } = handle` is safe when helpers need to read current values later. Destructuring individual prop values is only a snapshot; prefer `handle.props.name` inside callbacks and render output when values can change.
 
 ## State Rules
 
@@ -84,8 +78,7 @@ function TodoList(handle: Handle) {
 
 ### `handle.update()`
 
-Schedules a rerender. Returns a promise that resolves with an `AbortSignal` after the update
-completes. Await it when you need the updated DOM before follow-up work:
+Schedules a rerender. Returns a promise that resolves with an `AbortSignal` after the update completes. Await it when you need the updated DOM before follow-up work:
 
 ```tsx
 on('click', async () => {
@@ -98,9 +91,7 @@ on('click', async () => {
 
 ### `handle.queueTask(task)`
 
-Schedules a task to run after the next update. The task receives an `AbortSignal` that aborts when
-the component re-renders or is removed. Use for post-render DOM work, reactive data loading, or
-hydration-sensitive setup:
+Schedules a task to run after the next update. The task receives an `AbortSignal` that aborts when the component re-renders or is removed. Use for post-render DOM work, reactive data loading, or hydration-sensitive setup:
 
 ```tsx
 let data = null
@@ -135,8 +126,7 @@ return () => {
 }
 ```
 
-Avoid creating intermediate state just to trigger `queueTask`. Do the work directly in the handler
-or the queued task.
+Avoid creating intermediate state just to trigger `queueTask`. Do the work directly in the handler or the queued task.
 
 ### `handle.signal`
 
@@ -188,8 +178,7 @@ Context for ancestor/descendant communication. See the context section below.
 
 ## Context
 
-Use `handle.context.set()` to provide values and `handle.context.get(Provider)` to consume them.
-`set()` does **not** trigger updates — call `handle.update()` if the tree needs to rerender.
+Use `handle.context.set()` to provide values and `handle.context.get(Provider)` to consume them. `set()` does **not** trigger updates — call `handle.update()` if the tree needs to rerender.
 
 ```tsx
 function ThemeProvider(handle: Handle<{ children?: RemixNode }, { theme: 'light' | 'dark' }>) {
@@ -261,8 +250,7 @@ function ThemedContent(handle: Handle) {
 
 ## Global Events
 
-Use `addEventListeners(target, handle.signal, listeners)` to listen to global targets with
-automatic cleanup when the component disconnects:
+Use `addEventListeners(target, handle.signal, listeners)` to listen to global targets with automatic cleanup when the component disconnects:
 
 ```tsx
 import { addEventListeners, type Handle } from 'remix/ui'

package/template/.agents/skills/remix/references/create-mixins.md

@@ -2,8 +2,7 @@
 
 ## What This Covers
 
-How to author your own reusable host-element behavior with `createMixin`. Read this when the task
-involves:
+How to author your own reusable host-element behavior with `createMixin`. Read this when the task involves:
 
 - Combining multiple low-level events or DOM hooks into one semantic mixin
 - Dispatching custom DOM events from a host node
@@ -14,9 +13,7 @@ For the built-in mixins most code should use, see `mixins-styling-events.md`.
 
 Use `createMixin` from `remix/ui` to author reusable host-element behavior.
 
-Most app code should use built-in core mixins (`on`, `css`, `ref`, `link`, `attrs`) and animation
-mixins from `remix/ui/animation`. Create custom mixins when combining multiple low-level events
-into one semantic event, or when the pattern is reused across components.
+Most app code should use built-in core mixins (`on`, `css`, `ref`, `link`, `attrs`) and animation mixins from `remix/ui/animation`. Create custom mixins when combining multiple low-level events into one semantic event, or when the pattern is reused across components.
 
 ## Core Semantics
 
@@ -24,8 +21,7 @@ into one semantic event, or when the pattern is reused across components.
 2. `insert` is the host-node availability point for imperative setup.
 3. `remove` is teardown for that same lifecycle.
 4. `queueTask` runs post-commit and receives `(node, signal)` for mixins.
-5. Mixin render functions should stay pure; side effects belong in `insert`, `remove`, or queued
-   work.
+5. Mixin render functions should stay pure; side effects belong in `insert`, `remove`, or queued work.
 
 ```tsx
 import { createMixin } from 'remix/ui'
@@ -71,8 +67,7 @@ let withFocus = createMixin<HTMLElement>((handle) => {
 
 ## Custom Event Mixins
 
-Create event mixins when you combine multiple low-level events into one semantic custom event that
-is reused across components.
+Create event mixins when you combine multiple low-level events into one semantic custom event that is reused across components.
 
 1. Namespace custom event names (`myapp:*`) to avoid collisions.
 2. Extend `Event` with the data consumers need.

package/template/.agents/skills/remix/references/data-and-validation.md

@@ -2,16 +2,14 @@
 
 ## What This Covers
 
-How input becomes a value the app trusts, and how that value reaches storage. Read this when the
-task involves:
+How input becomes a value the app trusts, and how that value reaches storage. Read this when the task involves:
 
 - Defining database tables, columns, relations, and migrations
 - Querying or mutating persisted data with `Database`
 - Parsing and validating user input from forms, query strings, or external payloads
 - Choosing between schema-level checks, table validation hooks, and migration-level constraints
 
-For where validation runs in the request lifecycle, see `routing-and-controllers.md`. For session
-or identity-bound writes, see `auth-and-sessions.md`.
+For where validation runs in the request lifecycle, see `routing-and-controllers.md`. For session or identity-bound writes, see `auth-and-sessions.md`.
 
 ## Table Definitions (`remix/data-table`)
 
@@ -65,22 +63,16 @@ export type OrderWithItems = TableRowWith<typeof orders, 'items'>
 | `c.uuid()`                    | UUID / TEXT        |
 | `c.varchar(length)`           | VARCHAR            |
 
-Column modifiers: `.primaryKey()`, `.autoIncrement()`, `.notNull()`, `.unique()`,
-`.references(table, column, fkName?)`, `.onDelete(action)`, `.default(value)`.
+Column modifiers: `.primaryKey()`, `.autoIncrement()`, `.notNull()`, `.unique()`, `.references(table, column, fkName?)`, `.onDelete(action)`, `.default(value)`.
 
 Composite primary keys go on the table option, not the column: `primaryKey: ['order_id', 'book_id']`.
 
 ### Schema vs migrations
 
-Column modifiers describe SQL constraints — the source of truth for them is your **migration**
-files, where they generate the actual DDL. Runtime `table(...)` definitions in `app/data/schema.ts`
-can use the same modifiers, or they can stay minimal (`c.integer()`, `c.text()`, ...) since the
-runtime only needs the column shape and validation hooks. Two valid patterns:
+Column modifiers on runtime `table(...)` definitions in `app/data/schema.ts` describe app-facing column metadata. They do not create or update database tables by themselves. The source of truth for actual DDL and constraints is your hand-written SQL migration files. Two valid patterns:
 
-- **Modifiers in both** — schema and migrations stay in sync visually; useful when you want
-  schema-level docs.
-- **Bare columns in schema, full modifiers in migrations** — schema describes what the app reads
-  and writes; migrations own the DDL and constraints.
+- **Mirror constraints in schema and SQL** — table definitions stay useful as schema-level docs, and migrations still own the actual DDL.
+- **Bare columns in schema, constraints in SQL** — schema describes what the app reads and writes; migrations own the DDL and constraints.
 
 Pick one and apply it consistently across the app.
 
@@ -88,8 +80,7 @@ Pick one and apply it consistently across the app.
 
 Tables can define validation and lifecycle hooks:
 
-- `validate` runs before `create` and `update` writes and should return either `{ value }` or
-  `{ issues }`
+- `validate` runs before `create` and `update` writes and should return either `{ value }` or `{ issues }`
 - `beforeWrite` can normalize or veto `create`/`update` values
 - `afterWrite` observes completed `create`/`update` operations
 - `beforeDelete` and `afterDelete` observe or veto deletes
@@ -135,9 +126,7 @@ let adapter = createSqliteDatabaseAdapter(sqlite)
 export let db = createDatabase(adapter)
 ```
 
-`createSqliteDatabaseAdapter` accepts synchronous SQLite clients with a shared `prepare`/`exec`
-surface, including Node's `node:sqlite`, Bun's `bun:sqlite`, and compatible clients. Use whichever
-client fits the runtime instead of assuming `better-sqlite3` is required.
+`createSqliteDatabaseAdapter` accepts synchronous SQLite clients with a shared `prepare`/`exec` surface, including Node's `node:sqlite`, Bun's `bun:sqlite`, and compatible clients. Use whichever client fits the runtime instead of assuming `better-sqlite3` is required.
 
 ### Database middleware
 
@@ -195,46 +184,51 @@ let featured = await db.findMany(books, {
 
 ## Migrations
 
+Migrations are plain SQL files. Each migration is a directory named `YYYYMMDDHHmmss_<slug>/` containing a hand-written `up.sql` (required) and an optional `down.sql` (omit for irreversible migrations).
+
+```txt
+db/
+  migrations/
+    20260228090000_create_users/
+      up.sql
+      down.sql
+    20260301083000_add_books_search_index/
+      up.sql
+```
+
 ### Writing migrations
 
-```typescript
-import { column as c, createMigration } from 'remix/data-table/migrations'
-import { table } from 'remix/data-table'
-
-export default createMigration({
-  async up({ schema }) {
-    let users = table({
-      name: 'users',
-      columns: {
-        id: c.integer().primaryKey().autoIncrement(),
-        email: c.text().notNull().unique(),
-        name: c.text().notNull(),
-      },
-    })
-    await schema.createTable(users)
-    await schema.createIndex(users, 'email', { name: 'users_email_idx', unique: true })
-  },
+Write standard SQL in `up.sql` and `down.sql`:
 
-  async down({ schema }) {
-    await schema.dropTable('users')
-  },
-})
+```sql
+-- up.sql
+create table users (
+  id integer primary key autoincrement,
+  email text not null unique,
+  name text not null
+);
+
+create index users_email_idx on users (email);
 ```
 
-Migrations can also import table definitions from the app schema to avoid duplication:
+```sql
+-- down.sql
+drop table if exists users;
+```
 
-```typescript
-import { createMigration } from 'remix/data-table/migrations'
-import { users, authAccounts } from '../../app/data/schema.ts'
+Do **not** import app code (e.g. `app/data/schema.ts`) into migration files. Migrations must be stable, immutable artifacts — importing live schema definitions creates drift between what the migration meant when it was written and what it does when replayed later. SQL files guarantee stability because they cannot import anything.
 
-export default createMigration({
-  async up({ schema }) {
-    await schema.createTable(users)
-    await schema.createTable(authAccounts)
-  },
-})
+### Transaction modes
+
+Migrations run inside a transaction by default (when the adapter supports transactional DDL). Override per migration with a directive comment in `up.sql`:
+
+```sql
+-- data-table/transaction: none
+create index concurrently users_email_idx on users (email);
 ```
 
+Modes: `auto` (default — wrap when supported), `required` (wrap; throw if unsupported), `none` (never wrap).
+
 ### Running migrations
 
 ```typescript
@@ -246,15 +240,11 @@ let runner = createMigrationRunner(adapter, migrations)
 await runner.up()
 ```
 
-### Migration file naming
-
-Name migration files with a timestamp prefix: `20260228090000_create_users.ts`. Place them in
-`db/migrations/`.
+The runner checksums each `up.sql` and detects drift if a previously applied migration changes. Use `runner.status()` to inspect applied/pending/drifted state, and `runner.down()` to revert.
 
 ## Input Validation (`remix/data-schema`)
 
-Use `data-schema` to validate user input (forms, query params, API payloads). This is separate from
-table-level `validate` hooks which run at persistence.
+Use `data-schema` to validate user input (forms, query params, API payloads). This is separate from table-level `validate` hooks which run at persistence.
 
 ### Schema builders
 
@@ -295,9 +285,7 @@ let { name, email, password } = s.parse(signupSchema, formData)
 
 There are two ways to get a `FormData` value inside an action.
 
-The recommended way: register `formData()` middleware in the root stack and read with
-`get(FormData)`. The body is parsed once per request, and the typed `FormData` value flows through
-the context system. This also lets `methodOverride()` and CSRF middleware work uniformly.
+The recommended way: register `formData()` middleware in the root stack and read with `get(FormData)`. The body is parsed once per request, and the typed `FormData` value flows through the context system. This also lets `methodOverride()` and CSRF middleware work uniformly.
 
 ```typescript
 import { formData } from 'remix/middleware/form-data'
@@ -310,15 +298,11 @@ let router = createRouter({
 let parsed = s.parseSafe(signupSchema, get(FormData))
 ```
 
-The fallback: `await request.formData()` directly. This works without middleware and is fine for
-small one-off cases, but it bypasses the context system, runs once per call site, and doesn't
-compose with middleware that depends on parsed form fields.
+The fallback: `await request.formData()` directly. This works without middleware and is fine for small one-off cases, but it bypasses the context system, runs once per call site, and doesn't compose with middleware that depends on parsed form fields.
 
 ### Safe parsing
 
-`s.parse` throws on invalid input. `s.parseSafe` returns a tagged result and is usually what an
-action wants, since validation failure is an expected outcome (re-render the form with errors)
-rather than an exception:
+`s.parse` throws on invalid input. `s.parseSafe` returns a tagged result and is usually what an action wants, since validation failure is an expected outcome (re-render the form with errors) rather than an exception:
 
 ```typescript
 let result = s.parseSafe(signupSchema, get(FormData))
@@ -328,13 +312,11 @@ if (!result.success) {
 let { name, email, password } = result.value
 ```
 
-Returning a `Response` for validation failures keeps the route contract honest: the same action
-returns 200 on success, 400 with errors on bad input, no out-of-band exception flow.
+Returning a `Response` for validation failures keeps the route contract honest: the same action returns 200 on success, 400 with errors on bad input, no out-of-band exception flow.
 
 ### Transforming validated output
 
-Use `.transform(...)` when a schema should validate one shape but return another value or output
-type. Transforms run after validation and compose with `.pipe(...)` and `.refine(...)`:
+Use `.transform(...)` when a schema should validate one shape but return another value or output type. Transforms run after validation and compose with `.pipe(...)` and `.refine(...)`:
 
 ```typescript
 import * as coerce from 'remix/data-schema/coerce'
@@ -356,14 +338,9 @@ let { page, q } = s.parse(pageSchema, formData)
 
 Avoid these shapes when reading and validating input:
 
-- **Raw `formData.get('name')` plus an `if (typeof name !== 'string')` guard**, then a thrown
-  custom error. This reinvents what `data-schema` already does, loses the typed result, and
-  pushes error translation into a `try/catch` instead of a return value.
-- **Letting route-local domain errors leak out of the action.** Translate expected outcomes (bad
-  input, missing record, duplicate entry) into the `Response` the route means to return instead of
-  throwing a custom `Error` subclass with a `status` field and catching it later.
-- **Trusting `params`, query strings, or external payloads without a schema.** Anything that
-  crosses a trust boundary should be parsed before it reaches business logic.
+- **Raw `formData.get('name')` plus an `if (typeof name !== 'string')` guard**, then a thrown custom error. This reinvents what `data-schema` already does, loses the typed result, and pushes error translation into a `try/catch` instead of a return value.
+- **Letting route-local domain errors leak out of the action.** Translate expected outcomes (bad input, missing record, duplicate entry) into the `Response` the route means to return instead of throwing a custom `Error` subclass with a `status` field and catching it later.
+- **Trusting `params`, query strings, or external payloads without a schema.** Anything that crosses a trust boundary should be parsed before it reaches business logic.
 
 ### Common patterns