solid2-agent-kit 0.8.1 → 0.11.0

package/README.md

@@ -16,7 +16,7 @@ Supported agents: **Cursor** and **Claude Code**.
 | Always-applied hard rules | `.cursor/rules/solid-2.mdc` (glob-attached to `*.tsx`/`*.jsx`) | managed block in `CLAUDE.md` | 23 hard rules + banned Solid 1.x API table + eslint-plugin-solid lint-heritage table. Injected without the agent having to decide to read anything |
 | Agent skill | `.cursor/skills/solid-2/` | `.claude/skills/solid-2/` | Execution-model primer, decision tables, canonical patterns, a “still runs / write the other form” table, review checklist, official-doc URL index |
 | Shared agent context | managed block in `AGENTS.md` | same (Claude Code users can reference it from `CLAUDE.md`) | Core principles and pointers, always in context |
-| Mechanical gate | `solid2-kit check` | same | Comment-stripped regex guard over `src/**/*.{ts,tsx,jsx}` (or explicit `[files...]`): fails on props destructuring (including multi-line signatures), `{ ...props }` rest copies, `{list().map(...)}` in JSX, React imports/hooks/JSX props/`React.lazy`/`useOptimistic`/`onDoubleClick`, Solid 1.x imports/APIs/components/JSX namespaces, `vite-plugin-solid`, old-router `<Route>`/`<A>`/`<HashRouter>`/`<FileRoutes>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props, `value()!` hand-narrowing, hand-rolled loading signals, `=== undefined` readiness branches, SolidStart leftovers (`@solidjs/start`, `h3`, `createAsync`, `useSubmission`, `"use client"`), Next.js imports/`useRouter`/`typeof window`, `history.pushState`, `render(<App />)` (pass a function), `isPending(user())` / `latest(user())` (pass the accessor), `<Dynamic>` (use `dynamic()`), `import type { JSX } from "solid-js"` (no `JSX` namespace there — `Element` from `solid-js`, DOM `JSX` types from `@solidjs/web`), and two-phase effects whose apply only writes a local signal (use a writable derivation) |
+| Mechanical gate | `solid2-kit check` | same | Comment-stripped regex guard over `src/**/*.{ts,tsx,jsx}` (or explicit `[files...]`): fails on props destructuring (including multi-line signatures), `{ ...props }` rest copies, `{list().map(...)}` in JSX, React imports/hooks/JSX props/`React.lazy`/`useOptimistic`/`onDoubleClick`, Solid 1.x imports/APIs/components/JSX namespaces, `vite-plugin-solid`, old-router `<Route>`/`<A>`/`<HashRouter>`/`<FileRoutes>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props, `value()!` hand-narrowing, hand-rolled loading signals, `=== undefined` readiness branches, SolidStart leftovers (`@solidjs/start`, `h3`, `createAsync`, `useSubmission`, `"use client"`), Next.js imports/`useRouter`/`typeof window`, `history.pushState`, `render(<App />)` (pass a function), `isPending(user())` / `latest(user())` (pass the accessor), `<Dynamic>` (use `dynamic()`), `import type { JSX } from "solid-js"` (no `JSX` namespace there — `Element` from `solid-js`, DOM `JSX` types from `@solidjs/web`), two-phase effects whose apply only writes a local signal (use a writable derivation), and core `action(async ...)` with a plain async function instead of a generator (only `yield` re-enters the transaction) |
 | Edit-time hook | `postToolUse` entry in `.cursor/hooks.json` | `PostToolUse` entry in `.claude/settings.json` (matcher includes `Bash`) | Runs the mechanical gate automatically on **every agent file edit — including edits made through shell commands** (sed, heredocs, codemods; source paths mentioned in the command are checked after it ran) — and feeds findings straight back into the conversation (Cursor: `additional_context`; Claude Code: stderr + exit 2), so enforcement does not depend on the agent remembering to run `check`. Wired only when the kit is a local devDependency; opt out with `--no-hooks` |
 | Turn-end gate | — | `Stop` entry in `.claude/settings.json` | Whole-project `check` + `doctor` when the agent tries to end its turn: with findings in place the stop is blocked (exit 2) and the findings are fed back, so a turn cannot finish with React/Solid 1.x patterns left behind. Loop-safe via `stop_hook_active` (one forced continuation, never an infinite loop) |
 | Pre-execution guard | `preToolUse` + `beforeShellExecution` entries in `.cursor/hooks.json` | `PreToolUse` entry in `.claude/settings.json` | Denies actions **before they run**: edits/deletes of kit-owned guardrail files (an agent blocked by a gate will try to remove the gate), edits that would strip the kit's hook entries or managed blocks, uninspectable shell rewrites of those files, and `npm/pnpm/yarn/bun install` of banned dependencies (`react`, `vite-plugin-solid`, `eslint-plugin-solid`, SolidStart, ...) — caught proactively instead of post-hoc by `doctor` |
@@ -127,8 +127,8 @@ Run both gates on every PR so nothing an agent (or human) merges can reintroduce
 Solid 1.x patterns:
 
 ```yaml
-- uses: actions/setup-node@v4
-  with: { node-version: 22 }
+- uses: actions/setup-node@v7
+  with: { node-version: 26 }
 - run: npm ci
 - run: npx solid2-agent-kit check && npx solid2-agent-kit doctor
 ```

package/bin/solid2-kit.mjs

@@ -354,6 +354,18 @@ function effectSyncFindings(content) {
   return matches;
 }
 
+// Core `action` (solid-js) takes a generator (`function*` / `async function*`)
+// so `yield` can re-enter the transaction; router `action` (@solidjs/router)
+// legitimately takes `async (form) => ...`. Only flag `action(async` when this
+// file's `action` comes from "solid-js" — a router import (or none) stays silent.
+function actionAsyncFindings(content) {
+  if (!/import\s*\{[^}]*\baction\b[^}]*\}\s*from\s*['"]solid-js['"]/.test(content)) return [];
+  if (/import\s*\{[^}]*\baction\b[^}]*\}\s*from\s*['"]@solidjs\/router['"]/.test(content)) return [];
+  return [...content.matchAll(/\baction\s*\(\s*async(?!\s+function\s*\*)/g)].map((match) => ({
+    index: match.index,
+  }));
+}
+
 const CHECKS = [
   {
     id: 'props-destructure-param',
@@ -511,7 +523,7 @@ const CHECKS = [
     id: 'solid1-router',
     pattern: /<(?:HashRouter|MemoryRouter|Route|Navigate|A|FileRoutes|StartClient|StartServer)\b/g,
     message:
-      'Solid Router 0.x/1.x or SolidStart JSX. Define routes with createRouter({ routes }) / fileRoutes(pageRoutes) and plain <a href={Router.paths...}>.',
+      'Solid Router 0.x/1.x or SolidStart JSX. Define routes with createRouter({ routes }) / fileRoutes(pageRoutes) and plain <a href={Router.paths...}> (link state: automatic aria-current/data-active/data-pending + CSS, or useLinkState).',
   },
   {
     id: 'meta-provider',
@@ -593,6 +605,14 @@ const CHECKS = [
     message:
       '`<Dynamic>` is a JSX convenience wrapper. Application code should use dynamic(() => ...) from "@solidjs/web" so the component identity stays stable.',
   },
+  {
+    // `action(async (item) => ...)` with core `action` never re-enters the
+    // transaction — `action(async function* ...)` does not match.
+    id: 'action-plain-async',
+    find: actionAsyncFindings,
+    message:
+      'Core `action` takes a generator (`function*` / `async function*`), not a plain async function — only `yield` re-enters the transaction, so writes after a bare `await` commit immediately. (Router `action` from "@solidjs/router" is the one that takes `async (form) => ...`.)',
+  },
 ];
 
 // .ts / .tsx / .jsx sources, excluding .d.ts declaration files.

package/files/commands/solid2-review.md

@@ -17,9 +17,39 @@ Steps:
    - async computations reading reactive inputs **after** the first `await`;
    - effects that copy state instead of deriving it, or reading stores in the apply phase;
    - `<For>` over server/refetched rows without a stable-id key function;
-   - `<Loading>`/`<Errored>` wrapping page chrome instead of the data slot, or async memos
-     passed as values (`user={user()}`) instead of accessors;
-   - store updates that rebuild objects/arrays instead of mutating the draft or reconciling;
+   - core `action` bodies that are not generators (plain `async` functions) or that write
+     after a bare `await` without re-entering on `yield` (router `action` from
+     `@solidjs/router` is the one that takes `async (form) => ...`);
+   - `<Loading>`/`<Errored>` wrapping page chrome instead of the data slot, or
+     `const u = user()` extracted then passed (a real parent-side read). Passing
+     `user={user()}` is the colorless form — do not "fix" it into accessors or
+     `Promise<User>` props;
+   - `latest(selectedId)` as the default highlight (hold is the default);
+     `isPending` treated as a global spinner instead of a per-expression question;
+   - treating `<Errored>` as a terminal ErrorBoundary, or routing per-row mutation
+     failures through it (those belong in the action / a projection-folded map);
+   - nested fetches assumed to waterfall, or `<Loading>` lifted along with a lifted fetch;
+   - rewriting App with loading/error branches, or snapshot/restore, when wrapping
+     a client store in server functions; disabling optimistic rows until ack;
+   - tRPC / type-gen around `"use server"`, a client `fetch` after a mutation,
+     refetch in `hydrate`/`onSettled`, a custom Worker/Express adapter, or
+     delaying `renderToStream` for visual order (`<Reveal>` owns display);
+   - store updates that rebuild objects/arrays instead of mutating the draft or reconciling
+     (`filter` for removal is fine — survivors keep identity; only fresh-tree wholesale
+     replacement needs `reconcile` / the derived form);
+   - hand-rolled link-active comparisons (`location.pathname === ...`) instead of the
+     automatic `aria-current` / `data-active` / `data-pending` attributes (+ CSS) or
+     `useLinkState` / `useIsRouting`; hand-rolled query parsing instead of
+     `useSearchParams`;
+   - search inputs bound to a held value without `latest`, effect-based debounce, fully
+     controlled forms without `name`s, `{ success: false }` result objects instead of
+     thrown failures, or router forms without server-side validation (`throw respond(...)`)
+     and `useSubmissions` inline errors;
+   - browser-only *values* handled with a `clientOnly` component split or an `isServer`
+     branch instead of `ssrSource: "client"` / `"hybrid"` on the memo/signal/derived store;
+   - held writes with no feedback (`isPending` / `latest` / optimistic value / `affects()`)
+     — the `[SILENT_HOLD]` shape — and dev-console diagnostics (`[STRICT_READ_UNTRACKED]`,
+     attribution-only store/list/effect costs) left unaddressed;
    - context values passed as snapshots instead of accessors/setters/stores;
    - components with conditional/early returns on reactive values.
 5. Verify any API you are not certain about against the official docs mirror

package/files/shared/agents-section.md

@@ -5,4 +5,4 @@
 - After editing TSX, run the `solid2-kit check` mechanical gate — it fails on React/Solid 1.x tokens and props destructuring. Use the project's `lint:solid` script if one exists; otherwise `npx solid2-agent-kit check` (with the kit as a devDependency) or `npx github:lightsound/solid2-agent-kit check`. An edit-time hook may also run this gate automatically after each file edit — treat its findings as errors to fix immediately, not warnings. Do not install `eslint-plugin-solid` (built for Solid 1.x; misreads Solid 2 idioms).
 - After editing `package.json`, `tsconfig*.json`, or root config files (Vite, ESLint), run `solid2-kit doctor` — it fails on React/Solid 1.x wiring: `react`/`vite-plugin-solid`/`eslint-plugin-solid`/SolidStart dependencies, 1.x `solid-js` ranges, and `jsx`/`jsxImportSource` values other than `preserve`/`@solidjs/web`.
 - The kit's guidance and gate files (`.cursor/rules/solid-2.mdc`, the `solid-2` skill directories, hook entries, managed blocks in this file and `CLAUDE.md`) are guardrails, not obstacles. Never edit, weaken, bypass, or delete them to make a failure go away — fix the flagged code. If a guardrail seems wrong, stop and tell the user.
-- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup`. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — children/return types are `Element` from `solid-js`; DOM `JSX` types come from `@solidjs/web`. Reset-a-signal-on-change is a writable derivation (`createSignal(() => { source(); return initial; })`), never an effect calling the setter. Client mode mounts with `render()` into an empty body — no hydration mismatch exists, so never defer initial values to post-mount React-style (that can overwrite persisted state).
+- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass async values as values (`user={user()}`) — JSX props are lazy; types stay `User`, not `Promise<User>`. `<Loading>` wraps the read, not the memo. Nested fetches run in parallel (components do not suspend). `isPending` is a per-expression question (`isPending(() => props.story)` / `isPending(selectedId)`), not a global spinner; `latest(selectedId)` is opt-in so highlight and content stay consistent by default. `<Errored>` heals when the source succeeds. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup`. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — children/return types are `Element` from `solid-js`; DOM `JSX` types come from `@solidjs/web`. Reset-a-signal-on-change is a writable derivation (`createSignal(() => { source(); return initial; })`), never an effect calling the setter. Client mode mounts with `render()` into an empty body — no hydration mismatch exists, so never defer initial values to post-mount React-style (that can overwrite persisted state). Client → server is additive (same setters + `action` + server functions): do not rewrite App with loading/error branches, disable optimistic rows until ack, invent tRPC, or refetch in `hydrate`/`onSettled`. The graph continues across the wire (`live()` owns the client connection; `<Reveal>` not a delayed stream). A server bundle uses `handleRequest` / Fetchable `fetch`; client-only start is static `dist/client`. One browser-only value takes `ssrSource` on the memo/signal/derived store (`client`/`hybrid`), not a `clientOnly` component split. Router link state is automatic (`aria-current`/`data-active`/`data-pending` + CSS; `useLinkState`/`useIsRouting` in JSX); search params via `useSearchParams`; router forms validate on the server (`throw respond({issues},{400})`) with inline errors from `useSubmissions`. Fire-and-forget confirmations wait with `yield until(predicate, {timeout})`. Debounce at the handler; inputs feeding a request bind `latest(query)`. Dev diagnostics are errors: `[STRICT_READ_UNTRACKED]` means a read outside a tracking scope, and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`.

package/files/shared/rules-body.md

@@ -21,7 +21,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    functions (`() => props.x`, `omit(props, ...)`, `children(() => props.children)`) are fine.
    Mechanically enforced by `solid2-kit check` — run it after editing TSX.
 2. **Never read reactive values at component-body top level.** The body runs once, untracked;
-   `const v = count()` there is a frozen snapshot (Solid warns in dev). Carry the accessor
+   `const v = count()` there is a frozen snapshot (Solid reports `[STRICT_READ_UNTRACKED]`
+   in dev, naming the component). Carry the accessor
    (the function itself) into JSX and call it there.
 3. Signals are read by **calling** them: `{count()}` in JSX, not `{count}`.
 4. **Derived state is a function, not state + effect.** `const full = () => a() + b()`.
@@ -30,6 +31,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    `createSignal(() => { source(); return initial; })` (re-runs when `source()` changes;
    the setter still works) — never a `createEffect` whose apply calls the setter. The
    derivation also moves the `source()` read to the read site, under its boundaries.
+   (React needs `useState(props.x)` plus a `previousX` comparison reset for the same
+   derive-override-reset behavior.)
    Mechanically enforced by `solid2-kit check` (effects whose apply only writes a local
    signal). Use `createMemo` only for expensive
    computations, multiple consumers, or an equality boundary. When several writes can land
@@ -52,13 +55,15 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `event.currentTarget` (the element that owns the handler), not `event.target`
     (a nested child). Never pass a setter as the handler (`onClick={setCount}`) —
     that writes the event object; wrap it: `onClick={() => setCount((c) => c + 1)}`.
+    Debounce at the handler (`onInput={debounce(...)}`), never as an effect copying
+    one signal into another.
 7. **Lists use `<For>`**, never `{list().map(...)}` in reactive JSX and never `key` props.
     `{todos().map((t) => <Row todo={t} />)}` *renders*, then recreates every row on each
     update. Row identity: default = item reference; `keyed={(item) => item.id}` = key function
     (child receives item as an accessor); `keyed={false}` = positional. **Rows from
     server/refetched data (fresh object references on every update — fetch results,
     subscription payloads) must use a key function on a stable id**, or every update
-    recreates every row. Reference keying is for local arrays whose item identities are
+    recreates every row (dev + attribution flags the rebuilds as `[UNSTABLE_LIST_IDENTITY]`). Reference keying is for local arrays whose item identities are
     stable (e.g. store rows). Match the child signature to the mode: default item is the
     **raw** value (`todo.title`); `keyed={(t) => t.id}` / `keyed={false}` pass an
     **accessor** (`todo().title`). Mixing those still “runs” (you render a function, or
@@ -69,28 +74,51 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `compute`; its return value feeds `apply`, which does imperative work and may return a
     cleanup. Single-argument `createEffect(fn)` is an error in Solid 2. Do not substitute
     `createTrackedEffect` for that — it is an advanced one-callback form that cannot nest
-    primitives. Most React `useEffect` code should not become an effect at all — see the skill.
+    primitives. Skip the initial run with `{ defer: true }`. Most React `useEffect` code should not become an effect at all — see the skill.
 9. **Stores update by mutating a draft**: `setStore(draft => { draft.user.name = "Ada" })`.
-   Never rebuild with spreads — that destroys property-level subscriptions. Returning a new
-   array from the setter (`setTodos((t) => t.filter(...))`) *renders* but is unkeyed — same
-   identity loss as wholesale assignment; mutate the draft or `reconcile`. Stores are
+   Never rebuild with spreads — that destroys property-level subscriptions. The return
+   form is for shapes where mutation is awkward — most commonly removal
+   (`setTodos((t) => t.filter(...))` is fine; survivors keep identity). Replacing an
+   array with a fresh tree replaces rows by index — that is the identity loss; use
+   `reconcile` or the derived form (dev + attribution flags the store-level waste as
+   `[IMMUTABLE_UPDATE_IN_STORE]`). Stores are
    **property reads** (`todos.length`, `todo.title`), not accessors — never `todos()`.
-10. **Async data is an async computation**: `createMemo(async () => ...)` read under
-    `<Loading>` / `<Errored>` boundaries. Read every reactive input **before the first
+10. **Async data is an async computation**: `createMemo(async () => ...)` (or
+    `createMemo(() => fetchUser(id()))`) read under `<Loading>` / `<Errored>`.
+    **Fetch high, block low** — creating/reading are like sync; consuming (await)
+    and blocking (the boundary) are independent. Create the memo early, wrap only
+    the read with `<Loading>`. Do not glue the boundary to the memo, and do not
+    retarget intermediate props to `Promise<User>` / `Accessor<User>` — types stay
+    `User`. Nested trees do not suspend: they fetch in parallel; a real waterfall
+    looks like `fetchB(a().id)`. JSX component props are lazy (passing isn't reading):
+    `<Child user={user()} />` then `{props.user.name}` under the child's
+    `<Loading>` is the colorless form. `const u = user()` at the parent *is* a
+    read and throws/snapshots there. Pass the memo itself only when the child
+    must `refresh()` that source — `isPending(() => props.user)` works on the
+    value. Read every reactive input **before the first
     `await`** — post-`await` reads do not subscribe, and in production the computation can
     sit pending with no retry. No `useEffect` + `setState` fetching, no `createResource`.
     `<Loading>` wraps the data slot, not page chrome. After first paint it keeps content
     during refetch (`isPending` for the indicator). Use `on={id()}` (the *value*, not the
-    accessor) only when that identity change should show the fallback again. Pass an async
-    memo to a child as the **accessor** (`user={user}`), and read `props.user()` under that
-    child's `<Loading>` — `user={user()}` throws not-ready at the parent, so the child's
-    boundary never sees it. Do not start `fetch` (or any request) at component-body top
+    accessor) only when that identity change should show the fallback again. Do not start `fetch` (or any request) at component-body top
     level — that runs once at mount and is not a reactive source. Do not `try/catch` `NotReadyError` around a read, and do not
     use `loadingValue` / `seedLoadingValue` as the default first-flight UI — those skip
-    `<Loading>`. `{latest(() => x())}` is a preview, not the visible answer. `isPending`
-    is the *refetch* indicator after a settled answer exists — do not use it as the
+    `<Loading>`. `{latest(() => x())}` is a preview, not the visible answer.
+    Default navigation holds: keep `selectedId()` so highlight and content stay
+    consistent; `latest(selectedId)` only when the highlight should move first.
+    Pair `class={{ pending: isPending(selectedId) }}` with a short CSS
+    `transition-delay` so fast swaps do not flash. Inputs feeding a request bind
+    `value={latest(query)}` so keystrokes show while the write is held.
+    `isPending` is a per-expression question, not a global spinner: ask it of the
+    async source, a derived prop (`isPending(() => props.story)`), or the write
+    (`isPending(selectedId)`), even when the fetch lives in a child. It is
+    the *refetch* indicator after a settled answer exists — do not use it as the
     first-load spinner (`<Loading>` owns that). Pass the accessor: `isPending(user)`,
     not `isPending(user())` (that evaluates the read before `isPending` runs).
+    Granularity is the expression (`isPending(() => item.quantity)` with
+    `affects(item, "quantity")`). A hold with no feedback at all is `[SILENT_HOLD]`
+    under attribution — always pair a held write with one of these questions, an
+    optimistic value, or `affects()`.
     "Prop with local edits" = writable derivation:
     `createSignal(() => props.value)` or `createStore(() => props.value, fallback)`.
     `createOptimistic` is for an in-flight mutation, not a local editing session.
@@ -143,13 +171,26 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     integration layers. Model async as a computation (return a promise or async iterable
     from a memo/store) and let the framework own the states: first load = `<Loading>`
     fallback; refetch indicator = `isPending()`; errors = thrown into the graph and caught
-    by `<Errored>`; speculative value = `latest()`. Mechanically enforced by
-    `solid2-kit check` (loading-signal naming, zero-arg-call undefined checks).
+    by `<Errored>`; speculative value = `latest()`. `<Errored>` is graph status, not a
+    terminal React ErrorBoundary: it heals when the source succeeds again (refresh,
+    live reconnect, input change). `reset` retries the collected *sources*, not a UI
+    remount. Per-row mutation failures belong in an errors map the projection folds
+    in (survives the optimistic overlay), not in `<Errored>` around the whole list.
+    Making a client store "real" is additive: same setters, wrap mutations in
+    `action`, swap `createOptimisticStore` and a file of server functions — do
+    not rewrite `App.tsx` with loading/error branches.
+    No request counters or `AbortController`s for dedup/cancellation — superseded
+    answers drop automatically. Throw unusable responses; never `{ success: false }`
+    result objects checked at every read.
+    Mechanically enforced by `solid2-kit check` (loading-signal naming, zero-arg-call undefined checks).
 19. **Refetch is `refresh(source)`** — rarely needed, but when it is, never fake it with a
     counter/version signal read inside the computation. Input-driven refetch is automatic
     (tracked inputs re-run the computation) and subscriptions push. Legit uses: after a
     mutation inside an `action`, and explicit reload buttons. Pair with `affects(source)`
     when the reload should present as pending — a bare `refresh()` re-asks quietly.
+    On a derived store, `refresh(store)` re-runs the derivation (`fn`); refreshing a
+    plain signal accessor is a no-op. `refresh` returns a promise for the target's next
+    settled state (`await refresh(user)`, or `yield refresh(x)` inside an action).
     These are three different APIs: core `refresh(source)` reruns a reactive source;
     router `revalidate(getUser.key)` invalidates the query cache; server-function
     `return reload({ revalidate: "todos" })` asks the integration to refresh cached
@@ -169,7 +210,14 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `postMessage` / logs via `snapshot(store)` (proxies fail or leak reactivity); render
     modals/tooltips/overlays through `<Portal>` from `@solidjs/web`; mutations whose writes
     cross an async gap default to `action` + `createOptimistic`/`createOptimisticStore` —
-    except reactive clients (e.g. Convex) whose subscriptions already push authoritative
+    the sync mutation *is* the prediction (an overlay, discarded on settle); write the
+    body as a generator (`function*` / `async function*`) suspending on `yield`, never a
+    plain `async` function (`solid2-kit check` flags that); put
+    `pending` on the record rather than a second copy of state. Do not snapshot
+    and restore, disable optimistic rows until ack, mutex rapid clicks, or freeze
+    unrelated writes because one action is in flight; failed-action replay is
+    optional. Fire-and-forget confirmations wait with `yield until(predicate,
+    { timeout })` — the predicate reads authoritative state. Except reactive clients (e.g. Convex) whose subscriptions already push authoritative
     state after mutations. Compiler: `"jsxImportSource": "@solidjs/web"` (not `"solid-js"`);
     Vite plugin is `@solidjs/vite-plugin` (not `vite-plugin-solid`) — run `solid2-kit doctor`
     after touching `package.json` / tsconfig / root configs; it fails on React and Solid 1.x
@@ -179,6 +227,11 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `clientOnly` starts loading at declaration; `{ lazy: true }` defers until first
     render. `NoHydration` / `Hydration` split hydration *ownership*; they do not choose
     visible content — `clientOnly` is for components that must never run on the server.
+    A single browser-only *value* takes `ssrSource` on the memo/signal/derived store
+    (`"client"` skips the server value and computes after hydration, e.g. `localStorage`;
+    `"hybrid"` re-runs after adopting the serialized value, e.g. window size mixed with
+    server data) — do not split a component via `clientOnly` for one value. An
+    `onSettled` fill-in remains a valid alternative.
     Pass a **function** to `render` / `hydrate` / `renderToString` / `renderToStream`
     (`render(() => <App />, root)`), never `render(<App />, root)`. `hydrate` when the
     container already holds SSR HTML; `render` for an empty mount. Client mode (the
@@ -214,14 +267,20 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     at module scope — not JSX `<Route>` / `<A>` / `<HashRouter>`. That package's `action` /
     `query` are URL-addressable POST forms and a read cache — not core `action` /
     `refresh` from `solid-js`. Router mutations: `<form action={save} method="post">`
-    (POST only; `.with(id)` binds args into the URL). `useAction` is JS-only. Cache
+    (POST only; `.with(id)` binds args into the URL). Validate on the server
+    (`throw respond({ issues }, { status: 400 })`); inline errors from `useSubmissions`,
+    pending via `form[aria-busy]` CSS. Keep server functions in `src/data/`, not under
+    `src/routes` (a `.ts` file there is an API route). `useAction` is JS-only. Cache
     reads: `query(fn, "name")` then `createMemo(() => getUser(id()))`; after a mutation
     `revalidate(getUser.key)`. Do not wrap mutations in `query` (an undeclared server
     function becomes GET). `Router.paths` is not the current location (`useLocation` /
-    `useParams`); a route `preload` result is `props.data`. One router instance —
+    `useParams`); search params via `useSearchParams` (merging setter; typed with a route
+    `search` schema + path node). A route `preload` result is `props.data`. One router instance —
     Solid Router does not support nested `<Router>` / nested `createRouter`.
     In-app navigation is `useNavigate` or `<a href={Router.paths...}>`, not
-    `window.location` / `history.pushState`. Trusted identity is
+    `window.location` / `history.pushState`. Link state is automatic
+    (`aria-current` / `data-active` / `data-pending` + CSS; `useLinkState` /
+    `useIsRouting` in JSX) — never hand-rolled `location.pathname` comparisons. Trusted identity is
     `getRequestEvent()`, never a caller-supplied user id. Unscripted forms use
     the function `.url` (or a router `action`), not a hand-built `/_server/`
     path. Client history adapters do not select the SSR URL — pass
@@ -230,11 +289,36 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `<Title>` / `<Meta>` from `@solidjs/meta` with **no** `MetaProvider`. A static
     `<title>` in the document shell is the fallback; do not hardcode other tags
     (`<meta name="description">`) that Solid Meta should manage.
-    Return `respond(value, { status })` from a `"use server"` function, not
+    Return `respond(value, { status, headers })` from a `"use server"` function, not
     `Response.json` — a raw `Response` is HTTP-handler control flow; scripted
-    callers should receive the value. JSON-encodable server-function arguments
+    callers should receive the value. Reads are function calls too (`await getUser(id)`
+    on a `GET()`-declared read; the method mirrors the operation). Return or throw a
+    redirect (`if (!session?.userId) throw redirect("/sign-in")`); `redirect()` /
+    `respond()` take `revalidate` like `reload()`. Cache GET reads with
+    `Cache-Control` on that response (the default is `no-store`), not a hand-rolled
+    Solid cache. HTTP does not enforce TypeScript —
+    validate inside the function; do not invent tRPC / RPC type-gen.
+    Locals only the `"use server"` body reads (db, secrets) stay off the client.
+    Do not add an API-route file just to wrap a database call — `"use server"`
+    is the RPC. During SSR the call is in-process (no HTTP). After a mutation, `reload` /
+    `revalidate` / single-flight — never a client `fetch` or an `onSettled` /
+    `hydrate` refetch to "refresh the page". In-flight Promises serialize as
+    Promises; `live()` embeds the first value in HTML and continues the stream on
+    the client. Do not delay `renderToStream` for visual order (`<Reveal>` owns
+    display). Do not write subscribe/unsubscribe in the component around `live()`.
+    When the app has a server bundle (`ssr` or server functions), production is
+    `handleRequest(request)` from the built `dist/server/server.js` (or its
+    Fetchable `fetch`); platform Vite plugins adopt that handler (Node: the
+    template `server.js`). Client-only start mode is static `dist/client` —
+    there is no handler to wrap. Request middleware is
+    `start: { middleware: "./src/middleware.ts" }`, not Express `app.use`. Do not return
+    components from `"use server"` unless the project already enabled the
+    experimental `serverFunctions.components` flag. JSON-encodable server-function arguments
     only, unless `enableRichArguments()` was called once in the client entry
-    (`Date` / `Map` / `Set` throw without it).
+    (`Date` / `Map` / `Set` throw without it). `live()` connection state is
+    `source.onstatus` (`"connected"` / `"reconnecting"` / `"closed"`), never a
+    field in the yielded value. Sibling `<Loading>` reveal order is `<Reveal>`
+    (`collapsed` suppresses tail skeletons under sequential order).
 
 ## Lint heritage: eslint-plugin-solid (Solid 1.x) intents carried into this file
 
@@ -287,7 +371,7 @@ directory (default `src/`).
 | `renderToStringAsync(...)` | `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`) |
 | `clearDelegatedEvents` | delete — delegated listeners are scoped to each render root |
 | `vite-plugin-solid` / `jsxImportSource: "solid-js"` | `@solidjs/vite-plugin` / `"jsxImportSource": "@solidjs/web"` |
-| JSX `<Route>` / `<A>` / `<HashRouter>` / `<Navigate>` / `<FileRoutes>` | `createRouter({ routes })`, `fileRoutes(pageRoutes)`, plain `<a href={Router.paths...}>`, `hashHistory()` |
+| JSX `<Route>` / `<A>` / `<HashRouter>` / `<Navigate>` / `<FileRoutes>` | `createRouter({ routes })`, `fileRoutes(pageRoutes)` (`fileRoutes` from `@solidjs/router/fs`, `pageRoutes` from `virtual:file-routes`), plain `<a href={Router.paths...}>`, `hashHistory()`; link state via automatic `aria-current` / `data-active` / `data-pending` + CSS (`useLinkState` in JSX) |
 | `createAsync` / `createAsyncStore` / `useSubmission` / router `json()` / `cache()` | `createMemo(() => getUser(id()))`, `useSubmissions`, `respond()` from `@solidjs/web`, `query` |
 | `import ... from "@solidjs/start"` / `vinxi` / `h3` / `"use client"` | `GET` from `@solidjs/web/server-functions`; Solid has no `"use client"` |
 | `render(<App />, root)` | `render(() => <App />, root)` (same for `hydrate` / `renderToString` / `renderToStream`) |