solid2-agent-kit 0.9.0 → 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,6 +17,9 @@ 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;
+   - 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
@@ -31,7 +34,22 @@ Steps:
    - 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;
+   - 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 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`.
+- 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,11 +74,14 @@ 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 () => ...)` (or
     `createMemo(() => fetchUser(id()))`) read under `<Loading>` / `<Errored>`.
@@ -99,13 +107,18 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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.
+    `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.
@@ -166,12 +179,18 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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
@@ -191,11 +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` —
-    the sync mutation *is* the prediction (an overlay, discarded on settle); put
+    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. Except reactive clients (e.g. Convex) whose subscriptions already push authoritative
+    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
@@ -205,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
@@ -240,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
@@ -258,8 +291,12 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     (`<meta name="description">`) that Solid Meta should manage.
     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. Cache GET reads with `Cache-Control` on that
-    response, not a hand-rolled Solid cache. HTTP does not enforce TypeScript —
+    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"`
@@ -334,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`) |

package/files/skills/solid-2/SKILL.md

@@ -73,6 +73,7 @@ Most React `useEffect` code should NOT become `createEffect`:
 | Async value used several layers down | Create the memo high; pass `value={memo()}` through intermediates (they do not wait); put `<Loading>` around the leaf read |
 | Nested child with its own fetch | Leave it nested — it runs in parallel. Sequential only when the second call needs the first response (`fetchAuthor(story().authorId)`) |
 | Browser-only widget (charts, maps, `window`) | `clientOnly(() => import("./Chart"))` from `@solidjs/web` (`{ lazy: true }` defers the import until first render) |
+| Browser-only *value* (`localStorage`, viewport size) | `createMemo(..., { ssrSource: "client" })` — per-value policy at the data source, no component split (`"hybrid"` when server data mixes with client signals) |
 | Server vs browser branch | `isServer` / `isDev` from `@solidjs/web` (build-time constants), not `typeof window` |
 | SSR-stable `id` / `for` / `aria-*` pairing | `createUniqueId()` |
 
@@ -223,7 +224,9 @@ createEffect(
 Reads inside `apply` do not track. Extract every needed reactive value in `compute`
 (e.g. `() => ({ name: user.name, role: user.role })`). Passing a store proxy into `apply`
 and reading `user.name` there *runs once* and never retriggers. Compute-phase errors can be
-intercepted with the bundle form `createEffect(compute, { effect, error })`.
+intercepted with the bundle form `createEffect(compute, { effect, error })`. Skip the
+initial run with `{ defer: true }` — the `on(deps, fn, { defer: true })` replacement;
+the effect first runs on the next change.
 
 A two-phase effect whose apply only calls a local signal setter is "state + effect" in
 disguise — formally legal Solid 2, still rule 4 (`solid2-kit check` flags it). The reset
@@ -247,6 +250,10 @@ const [signInError, setSignInError] = createSignal<string | null>(() => {
 });
 ```
 
+The writable form spells exactly this: derive from the source, allow a local
+override, reset when the source changes. (React needs `useState(props.x)` plus a
+`previousX` comparison reset during render for the same behavior.)
+
 ### Async data — fetch high, block low
 
 Creating and reading an async value are the same as sync. **Consuming** (the
@@ -330,11 +337,18 @@ return <StoryDetail story={story} />;
   (`isPending(() => props.story)`), on a derived memo (`isPending(byline)`), or
   *above* the fetch but below the write (`isPending(selectedId)`), even when the
   fetch lives in a child. You do not need to pass the memo accessor just to ask.
+  Granularity is the expression: `isPending(() => item.quantity)` (paired with
+  `affects(item, "quantity")`) or `isPending(() => todos.length)` dims only what
+  that read depends on. 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()`.
 - Default navigation **holds**. `selectedId()` and the old story stay put until
   the new answer lands, so the highlight never points at the wrong content.
   `latest(selectedId)` is the opt-in when the design wants the highlight to move
   on click. Pair `class={{ pending: isPending(selectedId) }}` with a short CSS
-  `transition-delay` so fast swaps do not flash.
+  `transition-delay` so fast swaps do not flash. Inputs that feed a request follow
+  the same rule: bind `value={latest(query)}` so a controlled search box reflects
+  keystrokes while its write is held (an uncontrolled input needs nothing).
 - Read every reactive input **before the first `await`** in an async computation. A read
   after `await` does not subscribe; production can sit pending with no retry.
 - `<Errored>` function fallbacks receive an error **accessor** and a `reset` callback:
@@ -354,7 +368,12 @@ reflexes that bypass the async model and `solid2-kit check` flags them. If a val
 make it an async computation and read it under boundaries. Refetching is `refresh(source)`
 (typically as the last step of a mutation `action`, or a reload button) — never a
 counter/version signal read inside the computation to force re-runs; input-driven refetch is
-already automatic.
+already automatic. No request counters or `AbortController`s for dedup/cancellation
+either — superseded answers are dropped automatically and settled content holds;
+debounce at the event handler (`onInput={debounce(...)}`), never as an effect copying
+one signal into another. And throw unusable responses instead of returning
+`{ success: false }` objects checked at every read — failures travel to `<Errored>`
+like values.
 
 **Normalize thrown values once.** Thrown values are `unknown` in JavaScript, so define one
 shared `ErrorFallback` component per app — extract the message via `instanceof Error`, wire
@@ -409,6 +428,35 @@ state — it is an overlay the graph discards when the action settles (pass or f
 There is no rollback to write. Put in-flight affordances on the record
 (`pending?: boolean`); they vanish with the overlay.
 
+Minimal shape — the durable value derives from `fn`, optimistic writes overlay it,
+and `refresh` re-runs the derivation so the store reconciles against the server
+(no separate `getMessages()` call):
+
+```tsx
+import { action, createOptimisticStore, refresh } from 'solid-js';
+
+function createMessages() { // call from a component — not module scope (SSR shares modules)
+  const [messages, setMessages] = createOptimisticStore(() => getMessages(), []);
+
+  const addMessage = action(function* (message: Message) {
+    setMessages((m) => { m.push(message); });
+    yield saveMessage(message);
+    refresh(messages);
+  });
+  return [messages, { addMessage }] as const;
+}
+```
+
+Mutate the draft (`m.push(message)`), never spread-rebuild (`[...m, message]`) —
+stores track writes finely, so only the changed part updates. When the action
+settles, the overlay is discarded and the refreshed server data is authoritative;
+if it agrees with the prediction, reconciliation finds no differences and nothing
+re-renders. Derived reconciliation keys by `"id"` by default — pass `{ key: ... }`
+only when the identity field differs.
+
+Layered form, when per-row UI must survive overlay discard (a recoverable error
+with Retry on that row only):
+
 ```tsx
 import { action, createOptimisticStore, refresh } from 'solid-js';
 
@@ -480,6 +528,28 @@ snapshot/restore.
 **`yield`, not a bare `await`, is the transaction boundary.** `await api.save()` then
 `setTodos(...)` *runs*, but the write commits immediately — it is not held as an
 overlay. Either `yield saveTodo(todo)` or, when you need a typed result, `const saved = await api.save(); yield; setTodos(...)`.
+Write the body as a generator — `function*` or `async function*`, never a plain
+`async (...) =>` — because only `yield` re-enters the transaction: the runtime has no
+hook into a plain `await` continuation, so even inside `async function*` an `await`
+leaves the transaction until the next `yield` (`solid2-kit check` flags the
+non-generator form).
+
+When confirmation arrives outside the response — a fire-and-forget transport echoed
+back on a live source — hold the action open with `yield until(predicate, { timeout })`:
+
+```tsx
+const send = action(function* (text: string) {
+  const clientId = crypto.randomUUID();
+  setMessages((m) => { m.push({ clientId, text, pending: true }); });
+  yield socket.send({ clientId, text });
+  yield until(() => messages.some((m) => m.clientId === clientId), { timeout: 10_000 });
+});
+```
+
+The predicate reads authoritative state, so the optimistic row cannot satisfy it;
+only the echo can. Timeout rejects with `TimeoutError` (strongly recommended on
+droppable transports; abort via `signal`). Outside actions, `await until(() => user())`
+waits for a value before continuing.
 
 Navigation-shaped updates do **not** need core `action`. A plain setter is enough:
 reads pull the async, and downstream async computeds hold previous values until the
@@ -632,6 +702,46 @@ do not `return () => cleanup`. Put owned setup in a **directive factory** (like
 `ResizeObserver`, third-party widgets, and native listener options (`capture` /
 `passive`) — Solid event props do not take those options.
 
+### Per-value SSR policy: `ssrSource`
+
+`clientOnly` splits a *component*; `ssrSource` keeps one *value* off the server,
+decided at the data source. `createMemo`, function-form `createSignal`, and derived
+stores (`createStore(fn, seed)`, `createProjection`, `createOptimisticStore(fn, seed)`)
+all accept `ssrSource: "server" | "hybrid" | "client"`:
+
+```tsx
+import { Loading, createMemo } from 'solid-js';
+
+function DraftPreview(props: { documentId: string }) {
+  const draft = createMemo(
+    () => localStorage.getItem(`draft:${props.documentId}`),
+    { ssrSource: 'client' },
+  );
+
+  return (
+    <section>
+      <h2>Saved draft</h2>
+      <Loading fallback={<p>Checking for a saved draft...</p>}>
+        <p>{draft() ?? 'No saved draft.'}</p>
+      </Loading>
+    </section>
+  );
+}
+```
+
+| Policy | Meaning | Use when |
+|---|---|---|
+| `"server"` (default) | Client adopts the serialized server value; compute does not re-run | Compute is deterministic from server-available inputs |
+| `"hybrid"` | Client adopts the serialized value, then re-runs the compute to take over | Server data mixes with client signals (window size, user locale) |
+| `"client"` | Server value skipped; compute runs after hydration as if first-mounted | Serialization is meaningless (`localStorage`, viewport) |
+
+With `"client"`, the bare form suspends on the server and the nearest `<Loading>`
+fallback renders into the HTML; a declared first value (`loadingValue` on
+signal-family sources, `seedLoadingValue: true` on store-family sources) renders
+provisional data with no boundary involvement instead. Filling the value in from
+an `onSettled` callback remains a valid alternative; `NoHydration` / `Hydration`
+split hydration *ownership* instead and do not express this policy.
+
 ## Scheduling and tests
 
 Signal/store writes outside a synchronous flush scope are **staged**; the reactive queue
@@ -648,6 +758,8 @@ Wait for an async expression to settle in tests: `await resolve(() => value())`.
 on a pending resource. `onSettled` is also a **single** fire (untracked): it is not
 `onMount` that re-runs, and it is not an effect. Run tests in dev mode first — Solid 2 emits diagnostics for top-level reactive reads,
 writes from owned scopes, and async reads outside `<Loading>`. Fix them; don't suppress.
+A read at component-body top level reports `[STRICT_READ_UNTRACKED]` naming the
+component — move the read into JSX, a memo, or an effect compute.
 
 Component tests use `@solidjs/testing-library`. Pass a **function** to `render` so
 the tree has an owner, and `flush()` after interactions that stage writes:
@@ -675,6 +787,60 @@ To turn those dev diagnostics into a hard gate, patch `console.warn` in the test
 file to rethrow unexpected warnings — then any top-level reactive read or unowned write
 an agent sneaks in fails the suite instead of scrolling by.
 
+### Dev diagnostics and attribution
+
+Diagnostics come in two tiers, both dev-build only (production strips them and `DEV`
+is `undefined` there). Always-on findings include misplaced reads
+(`[STRICT_READ_UNTRACKED]`, `[PENDING_ASYNC_UNTRACKED_READ]`), misplaced writes
+(`[REACTIVE_WRITE_IN_OWNED_SCOPE]`, `[FLUSH_IN_ACTION]`, `[SERVER_WRITE]`), and
+`[ASYNC_OUTSIDE_LOADING_BOUNDARY]` when a tracked read has no boundary above it.
+Each entry carries a stable `[CODE]`, what the runtime observed, and an owner chain
+(`in <App> › <Cart> › <LineItem>`); never silence a code before understanding it.
+
+Cost and responsiveness findings need the opt-in attribution engine, which records
+every scope that re-ran, what changed to cause it, and how long it took:
+
+```ts
+import { DEV } from 'solid-js';
+
+DEV?.attribution.enable();
+// reproduce the interaction, then ask why a scope ran:
+for (const event of DEV!.attribution.why(total)) {
+  console.log(DEV!.attribution.format(event));
+}
+```
+
+While attribution is enabled, Solid also warns on its own about over-subscription,
+chained async waterfalls (`[ASYNC_WATERFALL]`), memos whose fresh-but-equal output
+never settles (`[UNSTABLE_MEMO_OUTPUT]`), effects that relay state
+(`[EFFECT_RELAY_TEAR]`) or feed their own inputs (`[EFFECT_WRITES_OWN_SOURCE]`),
+immutable updates inside stores (`[IMMUTABLE_UPDATE_IN_STORE]` — mutate the draft),
+row-rebuilding lists (`[UNSTABLE_LIST_IDENTITY]` — key by id or reconcile into a
+store), and silent holds (`[SILENT_HOLD]` — a write held on async work with no
+`isPending()` / `latest()` reader, optimistic value, `affects()` mark, or effect that
+ran while held; reported from 300ms as info, from 500ms as a warning). `DEV.attribution.costs()`,
+`holds()`, and `feedback()` rank the session worst-first. Name the scopes you intend
+to interrogate (`createMemo(..., { name: "total" })`); `DEV.attribution.subscriptions(scope)`
+lists a scope's current dependencies to compare against what it uses.
+
+For regression tests, `@solidjs/diagnostics` turns the same channels into assertions:
+
+```ts
+import { captureArtifact } from '@solidjs/diagnostics';
+
+const { artifact } = await captureArtifact(() => {
+  fireEvent.click(getByRole('button', { name: 'Add' }));
+  flush();
+}, { scenario: 'add-item' });
+
+expect(artifact).toHaveNoDiagnostics();
+expect(artifact).toHaveNoSilentHolds();
+```
+
+`toHaveNoDiagnostics` fails on any coded warning (`info` findings excluded);
+`toStayWithinRerunBudget` / `toHaveNoWaste` catch recompute regressions. See the
+debugging-reactivity guide in [references/official-docs.md](references/official-docs.md).
+
 ## Client mode: no server HTML, no hydration reflexes
 
 The `@solidjs/vite-plugin` default (client mode, the `bare` tier) serves an empty-body
@@ -687,7 +853,7 @@ deferred "safe" initial value is worse than unnecessary: if anything persists th
 (an effect writing `localStorage`), the placeholder **overwrites the user's stored
 preference** before the real value is adopted. Mismatch only becomes a concept in
 start/SSR mode, where `hydrate()` mounts onto server HTML — and the Solid answer there is
-`isServer` / `clientOnly`, still not React-style deferred adoption.
+`isServer` / `clientOnly` / per-value `ssrSource`, still not React-style deferred adoption.
 
 ## App stack (only if the project has these packages)
 
@@ -736,7 +902,7 @@ export default function App() {
     <Router>
       {(props) => (
         <>
-          <a href={Router.paths()}>Home</a>
+          <a href={Router.paths}>Home</a>
           <main>{props.children}</main>
         </>
       )}
@@ -759,6 +925,27 @@ Link warming: `preload="false"` skips that link's *data* preload; `preloadLinks:
 disables automatic link preloading. Intent values are `"initial"` / `"navigate"` /
 `"native"` / `"preload"`. One router per app.
 
+Link state needs no component code: the router sets `aria-current="page"` (exact
+match), `data-active` (exact or descendant — the `/` link is active only on exact
+match), and `data-pending` (in-flight navigation target) on the anchors it handles;
+style them in CSS. For non-anchors, or state needed in JSX, `useLinkState(() => href,
+{ end })` returns the same three as accessors (`active` / `current` / `pending`);
+`useIsRouting()` is the page-level pending flag for progress bars. Hand-rolled
+`location.pathname === ...` comparisons are the wrong tool.
+
+Build URLs from `paths`: static segments are properties (`Router.paths.about`, never
+`Router.paths.about()`), parameterized segments are calls (`paths.products(id)`),
+followed by an optional search object and hash (`paths.search({ q, page }, "results")`).
+Nodes stringify in `href` / `navigate()` / `redirect()`, so call with no arguments
+only when an API insists on a plain string.
+
+Search params are the home for shareable state (filter, sort, page): `const [search,
+setSearch] = useSearchParams()` — the setter merges and navigates without scrolling;
+`""` / `undefined` / `null` removes a key. For typed values, put a synchronous
+Standard Schema on the route's `search` field and pass the path node:
+`useSearchParams(Router.paths.search)` (async schemas throw; a failing schema leaves
+the raw strings rather than throwing).
+
 **Two different `action`s.** Core `action` from `solid-js` is a generator transaction
 (optimistic writes that span an async gap). Router `action` from `@solidjs/router` is
 a URL-addressable POST mutation (`useSubmissions`, `<form action={save} method="post">`).
@@ -783,6 +970,59 @@ Only POST forms are accepted. Bind extra args with `.with(id)` (they go in the
 action URL). `onSubmit={(e) => { e.preventDefault(); fetch(...) }}` *runs* and
 drops the no-JS form fallback. `useAction` is JS-only for the same reason.
 
+Validated forms come in three passes sharing one HTML shape. Pass 1 (above) posts
+uncontrolled inputs with browser `required` / `pattern` — it works with no JavaScript.
+Pass 2 validates on the server, where the user cannot bypass it:
+
+```ts
+import { redirect, respond } from '@solidjs/web';
+import * as v from 'valibot';
+
+const Address = v.object({
+  postalCode: v.pipe(v.string(), v.regex(/^[0-9]{5}$/, 'Enter a five-digit postal code')),
+});
+export type AddressIssues = Partial<Record<'postalCode', string>>;
+
+export async function saveAddress(form: FormData) {
+  'use server';
+  const parsed = v.safeParse(Address, Object.fromEntries(form));
+  if (!parsed.success) {
+    const issues: AddressIssues = {};
+    for (const issue of parsed.issues) {
+      const field = issue.path?.[0]?.key as keyof AddressIssues | undefined;
+      if (field && !issues[field]) issues[field] = issue.message;
+    }
+    throw respond({ issues }, { status: 400 });
+  }
+  await database.addresses.save(parsed.output);
+  return redirect('/checkout/shipping');
+}
+```
+
+Keep server functions in `src/data/`, not under `src/routes` (with method discovery
+on, a `.ts` file there is an API route). `throw respond(...)` is intentional control
+flow — the status and value survive production sanitization, unlike a plain thrown
+`Error`. Pass 3 renders the messages inline from the recorded submission:
+
+```tsx
+import { action, useSubmissions } from '@solidjs/router';
+
+const submitAddress = action(saveAddress);
+const submissions = useSubmissions(submitAddress);
+const issues = () => (submissions.at(-1)?.error as { issues?: AddressIssues } | undefined)?.issues ?? {};
+
+<Show when={issues().postalCode}>{(message) => <p role="alert">{message()}</p>}</Show>
+```
+
+`issues()` is a plain derived function; `aria-invalid` on the input, `role="alert"`
+on the message. Redirect outcomes do not stay in the list; the no-JS outcome arrives
+via flash cookie as the same submission shape. Pending state is CSS on the automatic
+attribute — `form[aria-busy] button[type="submit"] { opacity: .6 }` — no component
+code. `submission.clear()` on dismiss/resubmit only, never from an effect (errors
+would flash and vanish). Live per-keystroke validation is a controlled input plus a
+memo message (`aria-live="polite"`), keeping `name` so `FormData` still works; leave
+the rest uncontrolled.
+
 **`query` is the read cache** (optional, only with the router). Wrap a read,
 give it a stable name, and consume it through a Solid async primitive:
 
@@ -811,7 +1051,8 @@ router mutation, `revalidate(...)` — not core `refresh()`, and not
 refresh cached data: `return reload({ revalidate: "todos" })`). `live()` sources
 update through the open stream; do not `revalidate` them. Replace SolidStart /
 Router 0.x leftovers: no `createAsync`, `useSubmission` (singular), `cache()`,
-router `json()`, or `<FileRoutes />` (`fileRoutes(pageRoutes)` instead).
+router `json()`, or `<FileRoutes />` (`fileRoutes(pageRoutes)` from `@solidjs/router/fs`
+over `pageRoutes` from `virtual:file-routes` instead).
 
 ### Server functions — `"use server"`
 
@@ -836,7 +1077,9 @@ reference runs in-process (no HTTP); in the browser it is HTTP. Anything
 referenced only inside the `"use server"` body (db client, secrets) never
 reaches the client — the directive is the privacy boundary. Mutations that should
 revalidate: `redirect` / `reload` from `@solidjs/web` (see the server-function
-guides). After a router/server mutation do **not** follow with a client `fetch`
+guides). Return or throw a redirect — guards read `if (!session?.userId) throw
+redirect("/sign-in")`. `redirect()` and `respond()` accept the same `revalidate`
+option as `reload()` when the mutation also changes location or returns a value. After a router/server mutation do **not** follow with a client `fetch`
 to "refresh the page" — `reload` / `revalidate` (and the router's single-flight
 response) close that loop. For 404 during SSR: `httpStatus(404)` from `@solidjs/web`.
 `throw new Error("…")` is stripped to `"Internal Server Error"` in production —
@@ -847,7 +1090,13 @@ caller unwraps. JSON-encodable arguments only unless `enableRichArguments()`
 was called once in the client entry (`Date` / `Map` / `Set` throw without it).
 `GET()` is only for idempotent reads (URLs leak into logs/history);
 import it from `@solidjs/web/server-functions`, never `@solidjs/start`.
-Cache GET reads with HTTP, not a hand-rolled Solid cache: the caller still
+Reads are function calls too: `GET(async (id) => { "use server"; ... })` is invoked
+as `await getUser(id)` — Solid owns the endpoint, serialization, and decoding, the
+database access stays on the server, and argument/return types flow to the caller.
+The HTTP method mirrors the operation (reads GET, mutations POST); when encoded
+arguments would exceed the URL limit the client falls back to a read-only POST.
+Cache GET reads with HTTP, not a hand-rolled Solid cache: responses default to
+`Cache-Control: no-store`, so supply the policy via `respond()` — the caller still
 receives the value; headers ride the transport.
 
 ```ts
@@ -943,8 +1192,9 @@ how to reuse. Prefer the form on the right.
 | `const rest = { ...props }` | `const rest = omit(props, "label")` |
 | `const user = createMemo(async () => { await fetch(...); return id(); })` | read `id()` **before** `await` |
 | `action(async function* () { await save(); setX(v); })` | `yield save()` or `await save(); yield; setX(v)` |
+| `action(async (item) => { ... })` with core `action` from `solid-js` | `action(function* (item) { ...; yield ...; ... })` — only a generator re-enters the transaction (`solid2-kit check` flags this). Router `action` from `@solidjs/router` is the one that takes `async (form) => ...` |
 | `todos()` on a store | `todos.length` / `todo.title` (property reads) |
-| `setTodos((t) => t.filter((x) => x.ok))` | mutate the draft, or `reconcile` |
+| `draft.todos = fresh` (wholesale fresh-tree assignment) | `reconcile(fresh, "id")`, or function-form `createStore` / `createProjection` (auto-keyed by `"id"`). Removal via `setTodos((t) => t.filter(...))` is fine — survivors keep identity |
 | `createEffect(() => user, (u) => log(u.name))` | `createEffect(() => user.name, (name) => log(name))` |
 | `<Loading fallback={<PageSkeleton />}>{/* header + data */}</Loading>` | wrap only the data slot; chrome stays outside |
 | `<Loading on={id} fallback={...}>` (the accessor) | `on={id()}` — a value, so identity changes can show fallback |
@@ -962,6 +1212,7 @@ how to reuse. Prefer the form on the right.
 | `<For each={rows.slice(from, from + n)}>` | `<Repeat from={from()} count={n}>` |
 | `{count() && <Badge />}` | `<Show when={count()}>` — `0` must not render as text |
 | `throw new Error("expired")` from a server function (prod) | `throw markSafeError(...)` or `throw respond(body, { status })` |
+| `const r = await api.x(); if (!r.ok) ...` result-object checks at every read | throw unusable responses; contain each region with `<Errored>` |
 | `GET(async (id) => { "use server"; await db.delete(id) })` | mutations stay on POST; `GET()` is for idempotent reads |
 | `live()` yields as an event log to append | each yield **replaces** the current answer; yield current state first |
 | `<article innerHTML={html()}>…children…</article>` | `innerHTML` **or** children, not both |
@@ -975,6 +1226,7 @@ how to reuse. Prefer the form on the right.
 | `renderToString(() => <App />)` for an async or lazy-route tree | `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`). String render emits `<Loading>` fallbacks |
 | `clientOnly(() => import("./Map"))` for a rarely shown widget | same + `{ lazy: true }` so the import waits until first render (default starts at declaration) |
 | `<NoHydration><Chart /></NoHydration>` to skip SSR of a widget | `clientOnly(() => import("./Chart"))` — `NoHydration`/`Hydration` split ownership, they do not choose visible content |
+| `clientOnly` split (or `isServer` branch) for one browser-only *value* | `createMemo(() => localStorage.getItem(k), { ssrSource: "client" })` — `"hybrid"` when server data mixes with client signals |
 | `await flush()` / `flush()` to wait on a pending memo | `await resolve(() => value())` (or Testing Library async queries); `flush()` only drains staged *sync* writes |
 | `action(function* () { setX(v); })` around a navigation-shaped setter | plain setter; async computeds hold previous values. Core `action` only when writes happen *after* async work |
 | `createContext` + a root provider for a true app singleton | module-level signal/store (SSR: shared across requests). Context is subtree scoping |
@@ -990,6 +1242,8 @@ how to reuse. Prefer the form on the right.
 | `const View = tab() ? A : B; return <View />` | `const View = dynamic(() => (tab() ? A : B))` — the ternary at setup freezes the choice |
 | `<For each={resolved()}>` after `children()` | `{resolved.toArray()}` — resolved children are not a reactive data list |
 | `<input onChange={...}>` for keystrokes | `onInput` — native `onChange` is blur/commit |
+| debounce as an effect copying one signal into another | debounce at the handler: `onInput={debounce((e) => setQuery(e.currentTarget.value), 150)}` |
+| `value={query()}` on a search box whose writes feed a request | `value={latest(query)}` so keystrokes show while the write is held (uncontrolled needs nothing) |
 | `createOptimistic` for a local edit draft | writable derivation / plain store. Optimistic is for an in-flight mutation |
 | `createMemo(async fn, { loadingValue })` / `{ seedLoadingValue: true }` as the default first-flight UI | `<Loading>` for first flight; those options are escape hatches (store projections use `seedLoadingValue`) |
 | `setSubmitted(true)` + an effect that watches it | do the work in the handler or an `action` |
@@ -997,6 +1251,9 @@ how to reuse. Prefer the form on the right.
 | `action={"/_server/" + id}` in app JSX | `action={createTodo.url}` or a router `action` |
 | `<form method="get" action={update.url}>` for a mutation | GET forms only for idempotent search; mutations are POST |
 | `window.location.href = ...` / `history.pushState` | `useNavigate()` or `<a href={Router.paths...}>` |
+| `class={{ active: location.pathname === "/about" }}` hand-rolled link state | CSS on automatic `aria-current` / `data-active` / `data-pending`; `useLinkState` in JSX, `useIsRouting()` for progress bars |
+| `new URLSearchParams(location.search)` hand-rolled query parsing | `useSearchParams()` (setter merges, no scroll); typed via a route `search` schema + `useSearchParams(Router.paths.search)` |
+| `Router.paths.about()` / string-concatenated URLs | static nodes are properties (`Router.paths.about`); calls bind params, then search object and hash |
 | `httpStatus(404)` in a click handler | call it bare in the component / error-fallback body (a scope declaration, not a mutation) |
 | `try { user() } catch (e) { /* NotReadyError */ }` | `<Loading>` — app code should not catch `NotReadyError` |
 | `{latest(() => results())}` as the visible list | settled read + `isPending()` for the indicator; `latest` is for previews |
@@ -1015,7 +1272,10 @@ how to reuse. Prefer the form on the right.
 | `Object.assign({}, props)` / expecting `merge` to skip `undefined` like 1.x `mergeProps` | `omit` / `merge` — explicit `undefined` **overrides** (Object.assign) |
 | `isPending(user())` / `latest(user())` | `isPending(user)` / `latest(user)` — pass the accessor (or `() => user()`). Calling it first evaluates the read before the helper runs |
 | `isPending(...)` as the first-load spinner | `<Loading>` owns first flight; `isPending` is the *refetch* indicator after a settled answer exists |
+| a held write with no feedback anywhere | pair it with `isPending()` / `latest()` / an optimistic value / `affects()` — otherwise dev + attribution reports `[SILENT_HOLD]` |
 | `refresh(getUser.key)` / `revalidate(user)` / `return refresh()` from `"use server"` | three APIs: core `refresh(source)` reruns a reactive source; router `revalidate(getUser.key)` invalidates the query cache; `return reload({ revalidate: "todos" })` asks the integration to refresh cached data |
+| `return redirect(...)` as the only redirect shape | guards `throw redirect("/sign-in")`; `redirect()` / `respond()` take `revalidate` too when the mutation also moves or returns a value |
+| `submission.clear()` from an effect | on dismiss/resubmit only — from an effect, errors flash and vanish |
 | `revalidate(liveSource)` | `live()` updates through the open stream; do not revalidate it |
 | `refresh(user)` without `affects` when the reload should look pending | pair `affects(user)` with `refresh(user)` — a bare `refresh` re-asks quietly |
 | `<Dynamic component={tab() ? A : B} />` | `const View = dynamic(() => (tab() ? A : B))` — `<Dynamic>` is a JSX convenience; app code should use `dynamic()` for stable identity |
@@ -1170,14 +1430,17 @@ always-applied rules installed alongside this skill.
       is a writable derivation (`createSignal(() => { source(); return initial; })`), not
       an effect calling the setter.
 - [ ] Event handlers wrap setters (`onClick={() => setX(...)}`), use `currentTarget`,
-      and `onInput` for keystrokes. `innerHTML` is sanitized and not mixed with children.
+      and `onInput` for keystrokes. Debounce at the handler, never as an effect copying
+      signals. `innerHTML` is sanitized and not mixed with children.
 - [ ] Async memos are passed as values (`user={user()}`); JSX props are lazy.
       Types stay `User` — not `Promise<User>` / `Accessor<User>`. `<Loading>` wraps
       the *read*, not the memo, not chrome. Extracting `const u = user()` at the
       parent is the read that throws. Nested child fetches run in parallel
       (components do not suspend); a real waterfall is `fetchB(a().id)`.
       `isPending` is per-expression (`isPending(() => props.story)` works);
-      `latest(selectedId)` is opt-in, not the default highlight.
+      `latest(selectedId)` is opt-in, not the default highlight. Inputs feeding a request
+      bind `latest(query)`; failures throw to `<Errored>`, never `{ success: false }`
+      result objects checked at every read.
 - [ ] Lists via `<For>` (server/refetched rows keyed by stable id), conditionals via
       ternary/`<Show>`; no `{list().map(...)}` in JSX; no `key` props; no `value()!`.
 - [ ] Effects are two-phase and only at imperative boundaries; apply does not read stores.
@@ -1198,8 +1461,8 @@ always-applied rules installed alongside this skill.
       is static `dist/client`. Do not delay `renderToStream` for visual order
       (`<Reveal>` does).
 - [ ] External collections reconcile into stores (function-form `createStore` /
-      `reconcile`), never wholesale draft assignment or `setTodos((t) => t.filter(...))`
-      as the identity-preserving update.
+      `reconcile`), never wholesale draft assignment of a fresh tree
+      (`setTodos((t) => t.filter(...))` for removal is fine — survivors keep identity).
 - [ ] Rest props via `omit`, not `{ ...props }`. Conditional `class` via objects, not string concat.
 - [ ] Input filters write back to the DOM on reject (inputs do not rewind).
 - [ ] No Solid 1.x imports or APIs (`solid-js/store`, `createResource`, `onMount`, `Suspense`, ...).
@@ -1207,12 +1470,25 @@ always-applied rules installed alongside this skill.
       `solid-js`; DOM `JSX` types come from `@solidjs/web`.
 - [ ] Inspect children with `children()`; code-split with `lazy` + `<Loading>`; reactive
       component choice with `dynamic()`. No `React.lazy`, no effects inside ref callbacks.
-- [ ] Browser-only code uses `isServer` / `clientOnly`, not `typeof window`.
+- [ ] Browser-only code uses `isServer` / `clientOnly` (components) / `ssrSource`
+      (values), not `typeof window`.
       Component teardown is `onSettled` (return cleanup), not `onCleanup`.
+- [ ] Dev console shows no diagnostics: reads in tracking scopes (no
+      `[STRICT_READ_UNTRACKED]`), held writes paired with `isPending` / `latest` /
+      optimistic values / `affects()` (no `[SILENT_HOLD]`). Attribution-only costs
+      (`[IMMUTABLE_UPDATE_IN_STORE]`, `[UNSTABLE_LIST_IDENTITY]`, `[EFFECT_*]`)
+      checked via `DEV.attribution` when touching stores, lists, or effects. Name
+      interrogated scopes (`{ name: "total" }`).
 - [ ] If the project has a router: `createRouter({ routes })`, not JSX `<Route>` / `<A>`.
       One instance, no nested `<Router>`. Navigate with `useNavigate` / `<a href>`, not
       `window.location`. Router `action`/`query` come from `@solidjs/router` (POST forms + cache), not
-      core `action`/`refresh`. Forms: `<form action={save} method="post">`.
+      core `action`/`refresh`. Forms: `<form action={save} method="post">`. Core `action`
+      bodies are generators (`function*` / `async function*`) suspending on `yield`,
+      never plain `async` functions. Link state is automatic attributes + CSS
+      (`aria-current` / `data-active` / `data-pending`; `useLinkState` / `useIsRouting`
+      in JSX). Search params via `useSearchParams`. Forms validate on the server
+      (`throw respond({ issues }, { status: 400 })`) with inline errors from
+      `useSubmissions`.
 - [ ] `render(() => <App />, root)` — a function, not `render(<App />)`. `hydrate` when
       HTML already exists. Stream async/lazy trees (`await renderToStream(...)`) with
       exactly one consumer (`pipe` / `pipeTo` / `readable`). Snapshot stores with

package/files/skills/solid-2/references/official-docs.md

@@ -26,6 +26,7 @@ in `llms.txt` rather than guessing from Solid 1.x or React.
 - https://v2-rebuild--solid-docs-v2.netlify.app/concepts/components-and-jsx.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/concepts/async-reactivity.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/concepts/boundaries.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/concepts/mutations.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/concepts/rendering-and-ssr.md
 
 ## Building apps (start mode / fullstack)
@@ -65,6 +66,10 @@ read these before writing route JSX.
 ## Guides and migration
 
 - https://v2-rebuild--solid-docs-v2.netlify.app/guides/avoid-unnecessary-effects.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/guides/debugging-reactivity.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/guides/lists.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/guides/data-fetching-patterns.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/guides/forms.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/guides/testing.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/migration/from-react.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/migration/from-solid-1.md
@@ -108,9 +113,14 @@ verify API names against the reference pages above.
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/lifecycle-actions/affects.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/lifecycle-actions/on-settled.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/lifecycle-actions/refresh.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/lifecycle-actions/until.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/specialized-reactivity/on-cleanup.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/store-advanced/snapshot.md
 
+## Reference: diagnostics (dev builds only)
+
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/diagnostics-dev-hooks/dev.md
+
 ## Reference: components and JSX (solid-js)
 
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/components-jsx/show.md
@@ -160,8 +170,10 @@ verify API names against the reference pages above.
 
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/router-factory.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/routes-and-paths.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/navigation.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/data.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/types.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/history.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/filesystem.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-meta/title.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid2-agent-kit",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Teach AI coding agents (Cursor, Claude Code) to write correct Solid 2.0 instead of React or Solid 1.x — always-applied rules, an agent skill, and a mechanical pattern gate.",
   "type": "module",
   "license": "MIT",