create-rivet 0.0.0-stage → 0.1.0-alpha.0

package/templates/starter-minimal/.claude/skills/rivet-fix-resumability-error/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: rivet-fix-resumability-error
+description: 'Diagnose and fix Rivet resumability errors - RV2xxx compiler diagnostics, RV1016 handler errors, "is not serializable" / "Cannot resume" build or prerender errors, browser globals during server rendering, state that resets after the first click. Use when a Rivet build, check or page fails with such an error.'
+---
+
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/fix-resumability-error.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Fix a resumability error
+
+A Rivet page is rendered on the server and resumed in the browser: handlers, bindings and client effects run there with the values they capture, which the server serialized into the HTML. Errors come from code that cannot cross that line.
+
+1. Get the exact diagnostic: `npm run check` (`file:line:col - error RVnnnn`), the Vite overlay (`[RVnnnn] file:line:col`), or `check_code(source, filename)`. For the fix: `explain_diagnostic("RVnnnn")`; `check_code` also returns the quick-fixed source when one applies.
+2. Common codes:
+   - RV2001 browser global (`window`, `document`, `localStorage`) read during server rendering → move it into a handler, `clientEffect(() => …)`, `clientEvent(window, "resize", …)` or `clientOnly(() => import("…"))`.
+   - RV2003 captured class instance (`new Intl.NumberFormat`, an SDK client) → capture plain data; create the object inside the handler or `clientEffect`, or build it with `reconstruct(() => new X(…))` from `@rivetjs/runtime/dom` (the browser runs the factory on first read). A data class declared in the component module (plain fields) resumes as is.
+   - RV2102 captured instance of a module class that cannot resume as data (`#private` field, a decorator, a field arrow using `super`, a base that is not a data class of the module, `window` / `document` / `WebSocket` read while constructing) → create it inside the handler, build it with `reconstruct(() => new X(…))`, keep only plain fields, or add `[serialize]()` + `static [revive](data)` (from `@rivetjs/runtime/resume-format`; package classes: `registerClass(Cls, { id, serialize, revive })` in a module imported by the server code and the resume entry). At render, `RV2102: X has [serialize] but no static [revive]` → add the `static [revive]`.
+   - RV1016 handler expression reads state when it binds (`onClick={a() ? f : g}`) → wrap: `onClick={(e) => (a() ? f(e) : g(e))}`.
+   - RV2002 ref callback must assign a local → `ref={(el) => (local = el)}` or `const el = ref()` + `ref={el}`.
+   - RV2006 JSX inside a handler / effect / computed → render JSX in the component, switch it with a signal.
+   - RV2007 `this` in resumable code → `event.currentTarget`.
+   - RV2009 two module references share a browser name (two imports of different modules under one name) → rename one import (`import { fmt as fmtDate } from …`).
+   - RV2101 (warning, type-aware) a captured value's type does not serialize → as RV2003.
+3. Build / prerender error `Cannot resume <file>#<Component>$<hash>: function is not serializable` (dev server: ``capture `<name>` function is not serializable``; dev build: `capture #<i> …`): a captured function Rivet did not compile (created at runtime by a library such as `memoize(fn)`, a `.bind(…)` written inside an object literal (keep `const inc = add.bind(null, 2)` in a local constant and store `inc`; `.bind(ctx)` of a function using `this` stays RV2007), a method, or held by an object built outside a component: at module level such as `const table = { format: formatEuro }`, or by your own hook / helper such as `function useFormat() { return { format: formatEuro }; }`). Wrap it in an inline arrow, or build the object inside the component (module-level and imported functions used by name there resume by reference). A library object holding functions (a chart, editor, socket client from a package): build it with `reconstruct(() => createChart(…))` from `@rivetjs/runtime/dom` — no value in the page, the browser runs the factory on first read (module level: one server instance per process, never read request state in it). A class instance at render (`X instance is not serializable`): your class → `reconstruct(() => new X(…))` or `[serialize]()` + `static [revive](data)`; a package class → `registerClass(X, { id, serialize, revive })` from `@rivetjs/runtime/resume-format`. `NODE_ENV=development vite build` names the value path. Rules: `get_doc("docs:/best-practices/serializable-captures/")`.
+4. State resets on the first change after resume: a child destructures its props (`function C({ value })`) and is re-created → read `props.value`. Copies of `props.children` in a local are not tracked → render `{props.children}` directly.
+5. `.ts` module importing `@rivetjs/runtime/dom` (bundles the DOM runtime into SSR) → move that code into a `.tsx` file.
+6. Re-run `npm run check` and `npm run build` (prerender exercises serialization); both must be clean.

package/templates/starter-minimal/.claude/skills/rivet-form-in-drawer/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denys Severyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/starter-minimal/.claude/skills/rivet-form-in-drawer/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: rivet-form-in-drawer
+description: 'Build a validated form inside a drawer or dialog on a Rivet live page, so a submit updates the list behind it in place, keeps the overlay open on errors and works without JavaScript. Use for "add/edit X in a drawer/modal/dialog" tasks in a Rivet project.'
+---
+
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/form-in-drawer.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Form in a drawer with a live page
+
+Reference implementation: `get_doc("docs:/guides/forms/forms-in-overlays/")` (example `docs:/examples/drawer-form/`). Read it first; the steps below are its shape.
+
+1. Define the form once, shared by page and action (any Standard Schema library):
+
+```ts
+// src/forms/customer.ts
+import { defineForm } from "@rivetjs/forms";
+import { z } from "zod";
+export const customerForm = defineForm({ name: "customer", schema: z.object({ name: z.string().min(1), email: z.string().email() }) });
+```
+
+2. Make the page live and add the action:
+
+```tsx
+import type { LivePageProps } from "@rivetjs/router";
+import { actionResult } from "@rivetjs/router/client";
+import { action, invalid } from "@rivetjs/forms/server";
+
+export const live = true; // data is an accessor, refreshed in place after a submit: signals (open drawer, input, focus) survive
+export const serverLoad = ({ url }: { url: URL }) => ({ customers: [...customers], creating: url.searchParams.has("new") });
+export const serverActions = {
+  customer: action(customerForm, (value) => {
+    if (customers.some((c) => c.email === value.email)) return invalid({ email: "Already a customer" });
+    customers.push({ id: customers.length + 1, ...value });
+  }),
+};
+export default function Customers({ data }: LivePageProps<typeof serverLoad>) {
+  /* … */
+}
+```
+
+3. In the component: `const result = actionResult("customer")`, `const open = signal(data().creating || (result?.status ?? 0) >= 400)` (no-JS entry: `<a href="?new" onClick={(e) => { e.preventDefault(); open.set(true); }}>`), `const form = createForm(customerForm, { result })`. Render the list from `data()` with `<For each={data().customers} by={(c) => c.id}>`; never copy `data()` into a signal.
+4. The overlay: `@rivetjs/ui` (`Drawer` / `Modal`, `isOpen={open}`) or cdk `ModalOverlay isDismissable isOpen={open}` + `Modal` + `Dialog` (div overlay layer, two-way `isOpen`). The form inside:
+
+```tsx
+<form id={formId(form)} method="post" action="?/customer" onSubmit={async (event) => (await onSubmit(customerForm, form, event)) && open.set(false)}>
+  <label for={fieldId(form, "email")}>Email</label>
+  <input
+    id={fieldId(form, "email")}
+    name="email"
+    value={defaultValue(form, "email")}
+    aria-invalid={isInvalid(form, "email")}
+    aria-describedby={describedBy(form, "email")}
+  />
+  <FieldError of={form} name="email" />
+  <button aria-disabled={submitting(form) ? "true" : undefined}>Save</button>
+</form>
+```
+
+`onSubmit` resolves true once the server accepted the form and the page data is fresh: close the drawer then. Errors stay in the open drawer. Imports: `createForm, defaultValue, describedBy, fieldId, formId, isInvalid, onSubmit, submitting` from `@rivetjs/forms`, `FieldError` from `@rivetjs/forms/components`.
+
+5. A layout `serverLoad` re-runs too (counts in headers update).
+6. Check: `check_code` on the page, `npm run check`, then try it with JavaScript disabled (plain POST, 400 re-render with the drawer open).

package/templates/starter-minimal/.claude/skills/rivet-port-react-component/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denys Severyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/starter-minimal/.claude/skills/rivet-port-react-component/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: rivet-port-react-component
+description: "Port a React (or Solid / Next.js) component or page to Rivet idioms - signals instead of useState, clientEffect instead of useEffect, For with a key, live props, class, serializable handlers. Use when the user pastes React code or asks to convert / migrate a component to Rivet."
+---
+
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/port-react-component.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Port a React component to Rivet
+
+Map each construct (full table: `get_doc("docs:/start/coming-from-other-frameworks/")`):
+
+| React                                                   | Rivet                                                                                                                               |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `const [n, setN] = useState(0)`                         | `const n = signal(0)`; read `n()`, write `n.set(1)` / `n.update((v) => v + 1)` (`@rivetjs/reactivity`)                              |
+| `useMemo(() => a * 2, [a])`                             | `computed(() => a() * 2)` (no dependency list)                                                                                      |
+| `useEffect(() => …, [deps])`                            | `clientEffect(() => …)` from `@rivetjs/runtime/dom` (browser only, re-runs when read signals change; return a cleanup)              |
+| `useRef()` for an element                               | `const el = ref<HTMLInputElement>()` + `ref={el}`; read `el()`                                                                      |
+| `useCallback`, `memo`                                   | nothing: components run once                                                                                                        |
+| `useContext`                                            | `createContext` / `useContext` (`@rivetjs/reactivity`) + `<Provider token value>` (`@rivetjs/runtime/dom`)                          |
+| `items.map((i) => <li key={i.id}>…)`                    | `<For each={items} by={(i) => i.id}>{(i) => <li>{i().name}</li>}</For>` (item / index are accessors); `.map` is fine for fixed data |
+| `cond && <p />`                                         | `cond() && <p />` or `<Show when={cond()}>`                                                                                         |
+| `className`, `htmlFor`, `onChange` on text inputs       | `class`, `for`, `onInput` or `model:value={signal}`                                                                                 |
+| `style="…"` strings                                     | `style={{ color: c() }}` or `style:color={c()}`                                                                                     |
+| `function Badge({ count })`                             | `function Badge(props: { count: number })` + `props.count` (props are live; destructuring reads once)                               |
+| `React.lazy`, `<Suspense>`                              | `lazyComponent`, `Async`, `Suspense` (`@rivetjs/runtime/dom`)                                                                       |
+| Next.js `getServerSideProps`, Remix `loader` / `action` | `export const serverLoad` / `serverActions` in the route file                                                                       |
+| `useRouter().push`, `useSearchParams`                   | `navigate()`, `useSearchParams()` from `@rivetjs/router/client`                                                                     |
+| icon components / inline SVG                            | `<Icon icon={Check} />` from `@rivetjs/kit/icon` + `import { Check } from "lucide"`                                                 |
+
+Then fix what resuming requires:
+
+1. Move browser reads (`window`, `document`, `localStorage`, `matchMedia`) out of the component body into handlers or `clientEffect` (RV2001).
+2. Handlers: inline arrows or local consts. Values they capture must serialize: create class instances (`Intl.*`, SDK clients) inside the handler or build them with `reconstruct(() => new X(…))` (`import { reconstruct } from "@rivetjs/runtime/dom"`; RV2003); wrap library callbacks: `onPress={() => track("save")}`.
+3. Render props and item renderers stay functions (`{(item) => …}`).
+4. Third-party React UI → `@rivetjs/ui` / `@rivetjs/cdk` equivalents: `list_components`, `get_component(name)`; React Aria-style names carry over (`onPress`, `isOpen={signal}`).
+5. `check_code` the result, fix every RV code (`explain_diagnostic`), then `npm run check`.

package/templates/starter-minimal/.claude/skills/rivet-ui-design/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denys Severyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/starter-minimal/.claude/skills/rivet-ui-design/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: rivet-ui-design
+description: "Use when designing, building, or polishing Rivet interfaces with @rivetjs/ui or @rivetjs/cdk, including colors, spacing, typography, page structure, app layouts, component composition, responsive behavior, and interactions."
+---
+
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/design-ui.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Design with Rivet UI and CDK
+
+Design a coherent experience around the user's task, then express it with Rivet components. Preserve the app's brand, established patterns, and requested scope. This skill works in consumer projects; MCP is optional.
+
+## Start with the task and existing system
+
+Read project instructions, the relevant screens, installed package versions, global styles, and theme overrides. Identify the main task, content priorities, primary action, data density, and target devices. Ask only about missing information that materially changes the design; otherwise state a reasonable assumption and proceed.
+
+For a new or substantially redesigned screen, establish a compact design contract:
+
+- **Structure:** navigation, page regions, reading order, and what changes on mobile.
+- **Visual system:** semantic color roles, type hierarchy, spacing rhythm, density, and surface treatment.
+- **Composition:** chosen UI/CDK components and why they fit the task.
+- **Behavior:** primary action, focus/keyboard behavior, feedback, and loading/empty/error/success states.
+
+Use that contract to guide the implementation, not as a mandatory separate deliverable or approval gate. For a small edit, preserve the existing contract and change only what is needed.
+
+## Read the relevant design references
+
+| Decision                                                                             | Reference                                                       |
+| ------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| Palette, contrast, spacing, typography, radius, visual hierarchy                     | [Visual foundations](references/visual-foundations.md)          |
+| Information architecture, app shell, page regions, responsive and scrolling behavior | [Structure and app layouts](references/structure-and-layout.md) |
+| Choosing and combining components, forms, lists, overlays, reusable patterns         | [Component composition](references/component-composition.md)    |
+| Action hierarchy, states, feedback, keyboard, focus, motion                          | [Interactions](references/interactions.md)                      |
+| Actual imports, APIs, signals, resumability, styles, MCP and offline lookup          | [Rivet implementation](references/rivet-implementation.md)      |
+
+Load the references needed for the task. Before writing code, consult the implementation reference and verify the selected components against the installed version.
+
+## Implement and assess the whole experience
+
+Use styled `@rivetjs/ui` for its supported patterns. Use headless `@rivetjs/cdk` when the task requires a different visual treatment or a behavior primitive; custom styling still needs every interactive state. Compose semantic HTML for regions that need no component behavior.
+
+Evaluate the screen with realistic content: long titles, many rows, empty data, validation errors, pending actions, and narrow widths. Check hierarchy, alignment, contrast, readable text, keyboard access, focus restoration, and overflow. Inspect light/dark modes if supported and reduced motion when adding movement. Run the project's available checks and build; use MCP `check_code` when connected. Report the design decisions and what was actually verified. If browser inspection is unavailable, say which visual checks remain.

package/templates/starter-minimal/.claude/skills/rivet-ui-design/references/component-composition.md

@@ -0,0 +1,55 @@
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/design-ui/references/component-composition.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Choose and combine components
+
+## Select by purpose
+
+Use styled `@rivetjs/ui` when the existing look/variants fit. Use headless `@rivetjs/cdk` for a bespoke visual treatment or a lower-level behavior. The CDK supplies behavior and state hooks; the application supplies layout and complete visual states. Semantic HTML is appropriate for ordinary content regions. Neither a component count nor visual complexity makes a screen better.
+
+| Need                               | Consider                                          | Selection criterion                                                                             |
+| ---------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Navigate to a location             | Link or semantic anchor                           | Navigation should retain href, new-tab and no-JS behavior                                       |
+| Perform an action                  | Button; Toolbar for related controls              | Keep one dominant action per action group                                                       |
+| Show one object's summary          | Card/Surface with title, content, optional footer | A meaningful object/section boundary, not a decorative wrapper for every item                   |
+| Compare repeated structured data   | Table or DataGrid                                 | Use DataGrid when its editing/selection/interaction features are needed; verify feature support |
+| Switch peer views within a context | Tabs                                              | Related views; use route navigation for independent locations                                   |
+| Reveal optional content in place   | Disclosure/Accordion                              | Content remains in reading order; not for required content hidden by default                    |
+| Choose from a small known set      | RadioGroup, Segment, Select                       | Visibility, number of choices, and space available                                              |
+| Choose from a searchable set       | ComboBox/Autocomplete composition                 | Verify the particular input, collection, filtering and focus wiring                             |
+| Change a binary preference         | Switch or Checkbox                                | Switch for immediate on/off; checkbox for selecting/agreeing in a form                          |
+| Edit with surrounding context      | Drawer or contextual aside                        | Keep the current task visible and preserve draft state                                          |
+| Complete a focused interruption    | Modal/AlertDialog                                 | Modal for a focused task; AlertDialog for consequential confirmation                            |
+| Display supplementary content      | Popover/Tooltip                                   | Tooltip for short help; popover for richer contextual interaction                               |
+| Inform about an outcome            | Inline message/Alert, optionally Toast            | Persistent information belongs inline; transient confirmation may use toast                     |
+
+The table routes decisions, not prop spellings. UI and CDK subpaths differ: e.g. UI `combo-box`/`list-box` versus CDK `combobox`/`listbox`. Use the installed package's exports and examples.
+
+## Preserve component anatomy
+
+Compound roots establish state/context; triggers, labels, content and items consume it. Keep required relationships and place parts under their documented provider/root. Start from a real Rivet example, then adapt content and layout.
+
+- Cards: `Card.Header` groups `Card.Title` and `Card.Description`, `Card.Content` holds content, `Card.Footer` holds related actions. Omit unnecessary parts.
+- Fields: combine an explicit `Label`, the appropriate field/control, optional `Description`, and `FieldError` according to that field's anatomy. Required information should not exist only in placeholder text or tooltips.
+- Selection: keep trigger/value/indicator/popover/collection parts in their supported structure. Give each item a stable identity and searchable text where required.
+- Overlays: preserve backdrop/container/dialog/title/close relationships. Content must remain inside its interaction context; a visually correct panel with missing dialog semantics is incomplete.
+- Custom-styled anchors can use `buttonVariants`/`linkVariants`, but CSS classes do not provide the component's interactive behavior. Use the correct native semantics for the task.
+
+Avoid nested interactive targets: an entire clickable card with nested buttons, a button inside an anchor, or a row whose selection and action both fire. Separate the primary target and secondary controls. Event propagation hacks do not fix ambiguous semantics.
+
+## Compose common regions
+
+**Collection page:** heading + main create action → labeled search/filter controls → result count and collection → pagination. Show bulk actions only when selection exists; `ActionBar` or `Toolbar` may fit. Align filters and table columns to the same content edges. Provide initial-empty and filtered-empty states separately.
+
+**Settings page:** heading/description → grouped `Fieldset` sections → controls/help/errors → save feedback/actions. Group related rows within a section with consistent spacing or separators. Do not wrap every preference in a card. Choose either explicit save or immediate updates for a region and make that behavior visible.
+
+**Detail/edit page:** summary and status → related content sections → contextual actions. Use a drawer for short contextual edits, a page for long/deep edits, and inline editing for small well-bounded values. Destructive actions belong near the affected object with clear labels and proportionate confirmation.
+
+**Dashboard:** lead with metrics that support a decision, then the trend or collection needed to act. `Kpi`, `TrendChip`, and the chart exports may fit. Every chart needs a readable explanation or data alternative; meaningful units, time range and empty states matter more than decorative chart variety.
+
+**Command picker:** compose a labeled search field and a supported action collection, often using `Autocomplete` + `Menu` for commands. Confirm documented filtering, virtual focus and activation behavior for the installed version. A command menu and a value-selecting list box are different tasks. A dialog may provide a focused enclosing surface. Add pending, no-match, error and clear-query behavior; do not invent a `Command` export or manual arrow-key loop when suitable primitives exist.
+
+## Reuse at the pattern boundary
+
+Extract a repeated region when content, behavior and styling form a stable pattern (page header, labeled field row, filter toolbar). Prefer wrappers that expose domain-relevant choices and forward native/component props. Preserve live props with `splitProps`/`mergeProps`; use `Content` for renderable values. Avoid a universal wrapper with dozens of layout flags or a separate wrapper for every instance.
+
+When composing CDK, style its actual `rv-*` classes and documented `data-*`/ARIA states. Supply idle, hover, pressed, focus-visible, selected, disabled, invalid and pending treatments as applicable. Do not remove its behavior-critical inline styles, roles or keyboard handling.

package/templates/starter-minimal/.claude/skills/rivet-ui-design/references/interactions.md

@@ -0,0 +1,49 @@
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/design-ui/references/interactions.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Interactions and complete states
+
+## Action hierarchy
+
+Give the user a clear next action. Within an action group, use one primary treatment, secondary alternatives, and tertiary dismissal. Independent regions may each have a primary action; do not make every toolbar control primary. Use verb/object labels such as "Save changes" or "Archive ticket" rather than ambiguous "OK".
+
+Use links for navigation, buttons for actions, toggles for persistent state. Place actions near the content they affect and keep ordering consistent. Put low-frequency actions in a menu only if discoverability remains adequate. Give icon-only buttons an accessible label; a tooltip is supplemental. Use Lucide through `@rivetjs/kit/icon` rather than invented SVG or Unicode icons.
+
+## Define states with the behavior
+
+| State                       | User-visible behavior                                                                             |
+| --------------------------- | ------------------------------------------------------------------------------------------------- |
+| Idle                        | Clear affordance and current value/selection                                                      |
+| Hover/pressed/focus-visible | Consistent feedback; keyboard focus is distinct from hover                                        |
+| Pending                     | Describe what is happening, keep useful context, prevent accidental duplicate mutation            |
+| Success                     | Show the resulting state; close/clear only after acceptance; use transient confirmation if needed |
+| Validation error            | Explain the affected field and recovery near it; preserve entered values                          |
+| Request error               | Explain the failed operation and offer a meaningful retry; preserve draft/selection               |
+| Initial empty               | Explain what belongs here and the next action to populate it                                      |
+| Filtered empty              | Show that no results match; preserve filters and offer reset/clear                                |
+| Disabled/unavailable        | Communicate why when useful and provide a reachable alternative                                   |
+
+For loading, use a skeleton when the eventual structure is known, a spinner for a bounded wait, and progress for measurable work. Avoid replacing the entire workspace when only one region is refreshing. Maintain dimensions to prevent layout shifts and keep result announcements concise. For async search, ensure an older response cannot replace newer results.
+
+For forms, decide when validation occurs and what happens after submit. Keep labels stable, required status visible and help/error associations connected. On errors, keep the form or overlay open; focus the first invalid control or a useful summary. An explicit-save form preserves drafts until accepted. Immediate-update preferences need pending/success/error feedback and rollback if rejected.
+
+## Choose the right feedback surface
+
+Use inline errors for fields and local operations, an Alert for persistent page/section information, and a Toast for short-lived outcomes. Do not put the only error explanation in a disappearing toast. Use an AlertDialog for high-consequence confirmation when undo is unavailable; offer undo for easily reversible operations when it fits. Make a destructive confirmation name the affected item and action.
+
+## Keyboard, focus and dismissal
+
+Retain the UI/CDK primitive's interaction model. Verify Tab order, arrow-key navigation where expected, Enter/Space activation, Escape dismissal, and visible focus. Do not add global shortcuts that conflict with typing, native browser actions or existing app shortcuts; shortcuts supplement visible controls.
+
+For menus, dialogs, drawers and popovers, check initial focus, focus containment where modal, and restoration to the opening control. Define outside-press and Escape behavior, especially with unsaved work. Make sure a sticky header/footer does not cover the focused element. A clickable div with an `onClick` handler does not supply button semantics or keyboard behavior.
+
+Accessible names should remain meaningful out of context. Status updates that are not focused may need a live announcement; do not announce every render or keystroke. Custom CDK styling must retain selected/focus/invalid indicators, not just idle visuals.
+
+## Motion explains change
+
+Use movement to show an opening surface, selection change, or structural transition. Prefer the kit's existing CSS transitions and reduced-motion support. Match easing/duration across related controls. Small feedback usually needs a short transition (roughly 100–200ms); larger panel transitions may need more time (roughly 200–300ms). These are starting design ranges, not overrides for every component.
+
+Prefer opacity/transform for custom animation where suitable, avoid animating unrelated layout, and keep actions usable while feedback runs. Respect `prefers-reduced-motion`; use a component's `reduceMotion` option when available. Do not add motion merely to fill space or delay navigation for an animation. For custom element animation (entrances, hover / press states, exits, layout moves) use `@rivetjs/motion` (`<Motion.*>`, `Presence`, `animateLayout`): entrances stay CSS from the server and reduced motion is handled; keep drag / flick physics on the cdk's own motion.
+
+## Verify realistic sequences
+
+Try open → edit → submit → pending → error → retry → success; select → filter → no matches → clear; resize → collapse → restore; and queue → detail → back on mobile. Include keyboard-only use and touch-sized controls. Verify behavior on an actual SSR/resumed page, not only a client-rendered story: deferred overlay content, preserved drafts and first interaction are part of the experience.

package/templates/starter-minimal/.claude/skills/rivet-ui-design/references/rivet-implementation.md

@@ -0,0 +1,66 @@
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/design-ui/references/rivet-implementation.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Rivet implementation and documentation lookup
+
+## Use the installed version as the authority
+
+Read project `AGENTS.md`/`CLAUDE.md`, dependencies, JSX/compiler configuration and styling setup. Rivet resembles React JSX but uses fine-grained signals and compiled/resumable output. Do not install React UI libraries or assume React examples run unchanged. Do not upgrade dependencies or replace a working app setup just to apply this skill.
+
+When Rivet MCP is connected, use `get_component(name, package)` with an explicit `ui` or `cdk` package to retrieve imports, signatures, compound parts and examples. `search_docs(query, site)` and `get_doc(path)` provide guides. Useful doc ids include:
+
+- `ui:/start/design-principles/`, `ui:/start/theming/`, `ui:/start/styling/`, `ui:/start/composition/`.
+- `ui:/components/app-layout/`, `ui:/components/typography/`, and the chosen component's page.
+- `docs:/learn/resuming/` for SSR/resume constraints.
+
+Without MCP, inspect the installed package's `package.json` exports and corresponding `.d.ts`/source files in `node_modules/@rivetjs/{ui,cdk}`. Those determine available names, props, parts and event types. If an export points into `dist` or a conditional types entry, follow that target. Use the project's docs links or a supplied docs origin: `/llms.txt` indexes Markdown pages, and `<page>.md` provides a page. A `ui:/…` id is an MCP identifier, not a browser URL; do not invent a production host or fetch localhost unless a docs server is actually running.
+
+In a Rivet source checkout, sources are `libs/ui/src/components/<name>/index.ts`, `libs/ui/package.json`, `libs/cdk/package.json`; guides are `apps/ui-docs/content/start/*.md`, component pages are `apps/ui-docs/content/components/<name>.md` and `apps/cdk-docs/content/components/<name>.md`. Examples live under the corresponding app's `examples/`. These paths are a checkout fallback, not dependencies of this installed skill. If the API remains unavailable, request the relevant docs or state the limitation; do not fabricate exports or behavior.
+
+## Styles and tokens
+
+For an app already using Tailwind v4, keep this import order in its global CSS:
+
+```css
+@import "tailwindcss";
+@import "@rivetjs/ui/styles";
+```
+
+The `ui` starter provides the build setup. The UI style import uses the Rivet theme; other looks (the Classic theme included) are `@rivetjs/ui/theme` presets whose variables follow the import. Keep existing custom theme overrides. Tailwind must scan application source containing the classes; if a class is missing, check source detection and CSS import/build configuration. Raw `--surface` is a CSS token; `bg-surface` is a Tailwind utility generated from the kit's theme mapping. With plain CSS use `var(--surface)`.
+
+Themes respond to `.light`/`.dark` or `[data-theme="light" | "dark"]`. UI components can render in portals: scope theme changes to a root that includes their portal output, or use the documented overlay/theme scoping mechanism. Test a menu/dialog as well as the page when changing a scoped theme. A themed inner wrapper alone may leave its overlay with different tokens.
+
+Use `@rivetjs/ui/theme` for framework-free theme derivation. Verify these exports on the installed version. This example generates a candidate restrained teal theme and checks both modes:
+
+```ts
+import { auditContrast, themeCss, type ThemeParams } from "@rivetjs/ui/theme";
+
+const theme: ThemeParams = {
+  lightness: 0.5,
+  chroma: 0.1,
+  hue: 185,
+  base: 0.004,
+  radius: "medium",
+  formRadius: "large",
+};
+const css = themeCss(theme);
+const failures = ["light", "dark"].flatMap((mode) => auditContrast(theme, mode as "light" | "dark").filter((pair) => !pair.pass));
+// Review failures, adjust paired tokens/overrides, and re-audit before applying css.
+```
+
+`themeVariables(theme, mode)` returns CSS variables for a style object. `RIVET_PRESET`, `CLASSIC_PRESET` and `THEME_PRESETS` (also the look presets `BRUTALIST_PRESET`, `GLASS_PRESET`, `MAUVE_PRESET`, which change radii, border widths, shadows and card backdrop too) are available starting points. To switch a subtree's whole look by one attribute, import `@rivetjs/ui/styles/themes/presets.css` and set `data-ui-preset="<id>"`. `auditContrast` evaluates the kit's listed pairs including hover/soft variants; custom text, controls, transparency and scoped themes still require checks on the actual screen.
+
+## Rivet conventions that affect composition
+
+- Prefer subpaths: `import { Button } from "@rivetjs/ui/button"`, `import { AppLayout } from "@rivetjs/ui/app-layout"`. CDK names can differ from UI names (`@rivetjs/cdk/combobox`, `@rivetjs/cdk/listbox`); verify exports.
+- Prefer `class` and `for`. Component events follow their typed APIs, commonly `onPress`, `onSelectionChange`, `onOpenChange`; native text input uses `onInput` or `model:value`.
+- Create `const open = signal(false)` from `@rivetjs/reactivity`; read `open()`, write `open.set(true)`. Supported two-way props take the signal itself (`isOpen={open}`, `value={value}`, `selectedKeys={keys}`). Reading it passes a one-way value; check which props support two-way state.
+- Preserve live props: read `props.name`, and use `splitProps`/`mergeProps` from `@rivetjs/runtime/props` for forwarding. Destructuring live props can read them once.
+- Dynamic collections use `For` from `@rivetjs/runtime/dom` with a stable `by` key; its item and index arguments are accessors. Component render-prop state values can also be accessors; inspect the example/type before reading them.
+- For renderable props use `Content` from `@rivetjs/runtime/jsx-runtime`. For deferred closed overlays/providers on resumable pages use render-function children `{() => …}` instead of already-created JSX. `AppLayout` named slots also take render functions, not JSX values.
+- Keep handlers as inline arrows or supported local functions with serializable captures. Browser reads (`window`, `document`, storage) belong in handlers or `clientEffect`, not server render. Import browser runtime helpers from `.tsx` modules for resume rewriting.
+- Icons: `import { Icon } from "@rivetjs/kit/icon"` and icon data from `lucide`, then `<Icon icon={Search} />`. Keep decorative icons hidden and icon-only controls named. Do not invent SVG paths or use text glyphs as icons.
+- CDK is headless: documented `rv-*` classes and `data-*` state support custom CSS, while behavior-critical styles remain inline. Use its overlay primitives, not a hand-built/native-dialog replacement with a different focus/dismissal model.
+
+## Validation
+
+Run `check_code` on changed files when MCP is available. Run the consumer project's existing check/typecheck and build commands (starters use `npm run check` and `npm run build`). A compiler check does not prove visual quality or keyboard behavior; inspect the screen and key sequences in a browser. Use targeted interaction tests when behavior is added or changed. Report checks separately from assumptions, especially when API lookup, browser access or SSR verification is unavailable.

package/templates/starter-minimal/.claude/skills/rivet-ui-design/references/structure-and-layout.md

@@ -0,0 +1,51 @@
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/design-ui/references/structure-and-layout.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Structure and app layouts
+
+## Organize around the task
+
+Identify what users repeatedly do, what they need to compare, and what they must know before acting. Order content by that sequence. Separate global navigation, page navigation, local controls, and the main content; a row of tabs should not silently replace route navigation.
+
+Before selecting components, name the regions: app navigation, page heading/actions, filters, main content, contextual detail, feedback. Decide which are essential and which are optional. A simple form does not need an app shell; a multi-area workspace usually benefits from stable navigation.
+
+| User task                                           | Layout direction                                             | Rivet building blocks                                                |
+| --------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- |
+| Move between persistent app areas                   | Sidebar + page heading/content                               | `AppLayout`, `Sidebar`, optional `Navbar`                            |
+| A few top-level areas, public site, lightweight app | Top navigation + normal page flow                            | `Navbar`, semantic `main`/sections                                   |
+| Read/edit one object                                | Bounded content column; related sections and local actions   | `Typography`, `Form`, `Fieldset`, optional `Card`/`Surface`          |
+| Scan, compare, and act on many objects              | Filters/toolbar + collection + pagination; contextual detail | `SearchField`, `Toolbar`, `Table`/`DataGrid`, `Pagination`           |
+| Work through a queue                                | Master list + selected item + optional context panel         | `AppLayout` aside, `Resizable`, collections, conversation primitives |
+| Complete ordered stages                             | Visible progress + focused current step                      | `Stepper` when its navigation/validation model fits                  |
+
+These are selection directions, not interchangeable APIs. Verify component exports/parts using [implementation lookup](rivet-implementation.md).
+
+## Use the app shell's capabilities deliberately
+
+`@rivetjs/ui/app-layout` already composes a sidebar provider, sticky header, optional toolbar, main region, contextual aside and footer. Its `sidebar`, `navbar`, `aside`, `toolbar`, and `footer` slots take render functions `() => …` so their contents run inside the layout's providers. Do not recreate a shell's focus and mobile behavior from styled divs when this component fits.
+
+- Choose `sidebarCollapsible="icon"` only if icons/tooltips remain comprehensible; choose `"offcanvas"` when full labels are essential. Preserve useful navigation labels.
+- Use the aside for information about the current selection, not another global navigation tree. `asideMobile="sheet"` makes that information available on narrow screens; the default `"hidden"` requires another accessible path if the information is necessary.
+- `AppLayout.MenuToggle` is the mobile sidebar trigger; `Sidebar.Trigger` supports sidebar toggling. `AppLayout.AsideTrigger` controls the aside. Include the triggers that correspond to the panels you expose.
+- Use `sidebarResizable`/`asideResizable` when users benefit from varying the region widths. Set usable minimum sizes and verify keyboard resizing. Persist sizes with `resizableAutoSaveId` only when useful.
+- `scrollMode="page"` is ordinary document scrolling with sticky chrome. `"content"` fixes the shell to the viewport and scrolls the main region. Select an intentional scroll owner; test how long lists, composers, toolbars and detail panels behave together.
+
+`AppLayout` renders the main landmark. Avoid nesting another `main` inside it. Its slots and providers also affect resumability; preserve their render-function form.
+
+## Responsive behavior is a task decision
+
+Define what stacks, collapses, hides, or becomes a separate view. Do not merely scale down desktop columns.
+
+- Keep the main task reachable first. Move secondary details behind a visible trigger; keep essential data available.
+- A master/detail workspace can become list → detail navigation on mobile, with a clear back path and preserved list selection/filter/scroll position.
+- Wide tables may keep horizontal scrolling for comparisons. If switching to cards, preserve the labels, key values, sorting/filtering and row actions; do not silently remove functionality.
+- Preserve source order that makes sense for reading and keyboard navigation. CSS reordering should not create a different focus sequence.
+- Define how page actions wrap, whether a composer/save action stays reachable, and whether a sticky element obscures content, focus, or the mobile keyboard.
+- Use content-driven breakpoints. Test at a narrow width around 320–375 CSS px, a middle width where columns begin to collide, and a wide width. Check zoom, long translated labels and touch interaction.
+
+Use `min-w-0`/`min-h-0` on flex/grid children that need to shrink, bounded widths for reading, and overflow only on the region that owns it. Avoid hard-coded screen heights and three nested scrolling containers by default.
+
+## Example decision: support workspace
+
+For triaging tickets while replying, use a compact ticket queue, a dominant conversation, and an optional customer aside. Global navigation remains stable. A page toolbar holds assignment/priority controls; the reply composer owns the main send action. Use neutral surfaces and the customer's accent for selection/action, with text labels for priority.
+
+On narrow screens, show queue and conversation as separate reachable views; customer context can use an aside sheet. Preserve the selected ticket and draft when changing views. Test a long thread, a long customer name, empty queue, failed send, and the keyboard opening over the composer. This is a decision example, not a fixed layout for every app.

package/templates/starter-minimal/.claude/skills/rivet-ui-design/references/visual-foundations.md

@@ -0,0 +1,64 @@
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/design-ui/references/visual-foundations.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Visual foundations
+
+## Color roles before palette
+
+Inspect the app's theme before selecting new colors. Preserve a customer's brand; Rivet's blue/indigo default is a starting theme, not a requirement for every application. Assign a role to each color rather than adding arbitrary shades per component.
+
+| Role                       | Rivet CSS tokens / Tailwind utilities                                               | Decision                                                        |
+| -------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Page                       | `--background`, `--foreground`; `bg-background text-foreground`                     | Quiet canvas and primary reading text                           |
+| Grouped content            | `--surface`, `--surface-foreground`; `bg-surface text-surface-foreground`           | Separate a meaningful section from its surroundings             |
+| Secondary surfaces         | `--surface-secondary`, `--surface-tertiary`                                         | Subtle hierarchy; not a different tint for every region         |
+| Floating content           | `--overlay`, `--overlay-foreground`                                                 | Menus, popovers, dialogs use the overlay pair                   |
+| Supporting text            | `--muted`; `text-muted`                                                             | De-emphasize metadata; keep required labels readable            |
+| Primary action / selection | `--accent`, `--accent-foreground`                                                   | Draw attention to the current action or selection               |
+| Status                     | `--success`, `--warning`, `--danger` and their `-foreground` pairs                  | Communicate meaning with text/icon as well as color             |
+| Separation / focus         | `--border`, `--separator`, `--focus`                                                | Delineate groups and keep keyboard focus visible                |
+| Fields                     | `--field-background`, `--field-foreground`, `--field-placeholder`, `--field-border` | Preserve legibility in idle, focus, invalid and disabled states |
+
+Use component variants for semantic intent: `Button variant="primary"` for the main action, `secondary` for alternatives, `tertiary`/`ghost` for lower emphasis, `danger`/`danger-soft` for destructive actions. Variant vocabularies differ per component; verify them. Reserve accent for meaningful emphasis; several accent-filled panels compete with the primary action. A white surface hard-coded for light mode will fail in dark mode; use paired semantic tokens.
+
+When customizing a theme, update paired foregrounds and both modes. Changes to `--accent` can also require `--focus` and the derived hover/soft colors. Prefer `themeCss`, `themeVariables`, and the contrast helpers from `@rivetjs/ui/theme` for generated themes; see [implementation](rivet-implementation.md). A computed theme is a candidate, not proof of contrast.
+
+Check actual foreground/background combinations, including hover, selected, focus, invalid and overlay states. Use 4.5:1 for ordinary text, 3:1 for large text (at least 24 CSS px regular or about 18.7 CSS px bold), and 3:1 for essential control boundaries/state indicators. Inspect muted labels on their real surface and transparent colors on the composited background. Color-only status and invisible focus indicators fail even when body text passes. Theme audits cover their listed token pairs; custom elements still need inspection.
+
+## Spacing expresses relationships
+
+Rivet's default style kit uses `--spacing: 0.25rem`. Tailwind spacing utilities multiply that base. Reuse the project's existing scale; if none is established, begin with these **design recommendations**, not new library defaults:
+
+| Relationship                                 | Starting range at a 16px root | Typical utilities      |
+| -------------------------------------------- | ----------------------------- | ---------------------- |
+| Icon and label, tightly related metadata     | 4–8px                         | `gap-1`, `gap-2`       |
+| Label/control/help, controls in a toolbar    | 8–12px                        | `gap-2`, `gap-3`       |
+| Repeated rows and ordinary component content | 12–16px                       | `gap-3`, `gap-4`       |
+| Section padding and related groups           | 16–24px                       | `p-4`, `p-6`, `gap-6`  |
+| Distinct page sections                       | 24–32px                       | `gap-6`, `gap-8`       |
+| Page gutters                                 | 16px narrow, 24–32px wide     | `px-4 sm:px-6 lg:px-8` |
+
+Keep space within a group smaller than space between groups. Align headings, fields, rows, and footer actions to shared edges. Pick compact density for repetitive scanning and comfortable density for reading or touch; shrink gaps before shrinking essential text or hit targets. Change density across a whole region, not individual rows.
+
+Use grid/flex gaps for repeated layout and padding at container boundaries. Avoid stacking wrapper padding, card padding, and child margins into accidental whitespace. Do not change global `--spacing` to fix one page: it changes the kit's component dimensions as well. Use a local layout adjustment.
+
+## Typography establishes hierarchy
+
+Use the app's existing font family and weights. When choosing new typography, select a small set of roles rather than assigning a different size to every element. `Typography.Heading` provides semantic `level`, `Typography.Paragraph` supports `size="base" | "sm" | "xs"`, and `Typography.Code` is for code. Verify the installed props before separating heading semantics from visual size.
+
+| Role                         | Practical starting treatment                  |
+| ---------------------------- | --------------------------------------------- |
+| Page title                   | 24–32px, semibold, tight heading leading      |
+| Section title                | 18–20px, medium/semibold                      |
+| Reading text                 | 16px, about 1.5–1.75 line height              |
+| Dense rows, controls, labels | 14–16px with readable leading                 |
+| Secondary metadata           | 12–14px; retain contrast and zoom readability |
+
+These are starting recommendations. The shipped `Typography` h1–h6 styles use Tailwind `text-4xl` through `text-base`; body styles use `text-base leading-7`, `text-sm leading-6`, and `text-xs leading-5`. Inspect project overrides rather than assuming pixel sizes from utility names.
+
+Use one clear page heading and a logical outline. Increase size/weight for a heading before decorating its container. Keep reading columns around 60–75 characters when practical; dense tables and workspaces need different widths. Use tabular numerals for comparable metrics and amounts. Allow important labels to wrap; truncate only scan-oriented content with a way to inspect the full value. Avoid tiny uppercase gray labels as the main way of identifying fields.
+
+## Surface and density discipline
+
+Use a surface/card to establish a distinct object or section. Related settings rows often need one section with separators, not a card per row. Avoid card-inside-card stacks. Use the theme's `--radius` and `--field-radius` and component defaults; adjust them consistently when the brand calls for it. Prefer boundaries, spacing and typography for hierarchy; reserve elevation for floating content and genuinely elevated controls.
+
+For polish, review the screen in grayscale or with accent usage mentally removed: the task and action hierarchy should remain understandable.

package/templates/starter-minimal/.cursor/rules/rivet-add-route.mdc

@@ -0,0 +1,37 @@
+---
+description: "Add a page or endpoint to a Rivet app with file routes, server data (serverLoad), actions, head and layouts. Use when the user asks for a new page, URL, route, endpoint or loader in a Rivet project."
+globs:
+alwaysApply: false
+---
+
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/add-route.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Add a route to a Rivet app
+
+1. Pick the file under `src/routes/` (URL = path): `about.tsx` → `/about`, `blog/[slug].tsx` → `/blog/:slug`, `docs/[[lang]]/x.tsx` (optional param), `files/[...path].tsx` (rest), `(group)/p.tsx` → `/p` (shares the group's `_layout.tsx`), `api/time.ts` → endpoint (`export const onGet = () => Response.json(…)`). `_layout.tsx` wraps its folder; `_404.tsx` / `_error.tsx` handle misses / errors. Look up details with `get_doc("docs:/guides/routing/file-routes/")`.
+2. Write the page. Server code lives in `server…` exports (stripped from the browser build):
+
+```tsx
+import { notFound, type PageProps, type RequestEvent } from "@rivetjs/router";
+
+export const serverLoad = async ({ params }: RequestEvent<"blog/[slug]">) => {
+  const post = await findPost(params.slug); // server-only: database, files, secrets
+  if (!post) throw notFound();
+  return { post };
+};
+
+export const head = { title: "Post" };
+
+export default function Post({ data }: PageProps<"blog/[slug]">) {
+  return <h1 class="text-2xl">{data.post.title}</h1>;
+}
+```
+
+- Page props `data`, `params`, `url` are plain values; in `_layout.tsx` (`LayoutProps`) they are accessors: `data()`, `params()`, `url()`, plus `children`.
+- Mutations: `export const serverActions = { name: async ({ request }) => … }` + `<form method="post" action="?/name">`; with validation use `@rivetjs/forms` (`action(def, fn)` from `@rivetjs/forms/server`).
+- Access checks: `serverGuard` (throw / return `redirect()`, `deny()`, `notFound()`).
+- Static mode (`rivetRouter({ mode: "static" })`): `serverLoad` runs at build time; dynamic `[param]` pages list their params in `serverEntries`.
+- Server-only helpers go in `*.server.ts` files (browser code cannot import them: RV3008).
+
+3. Link to it: plain `<a href="/blog/hello">` (client navigation), or typed `<Link to="/blog/hello">` from `@rivetjs/router/link`; programmatic `navigate()` from `@rivetjs/router/client`.
+4. Run `npm run check` (`rivet sync` regenerates the typed routes in `.rivet/`, `rivet-check` reports `RV` codes; RV3101 = a link matches no route). Fix every diagnostic (`explain_diagnostic(code)`), then `npm run build`.