solid2-agent-kit 0.14.0 → 0.15.0

package/README.md

@@ -20,7 +20,7 @@ Supported agents: **Cursor** and **Claude Code**.
 | 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` |
-| Project-wiring gate | `solid2-kit doctor` | same | Config drift the source gate cannot see: React / `vite-plugin-solid` / `eslint-plugin-solid` / SolidStart deps in `package.json`, a 1.x `solid-js` range, `jsx` ≠ `preserve` or `jsxImportSource` ≠ `@solidjs/web` in tsconfig, Solid 1.x wiring in root config files, and stale installed guidance (kit updated but `sync` not re-run) |
+| Project-wiring gate | `solid2-kit doctor` | same | Config drift the source gate cannot see: React / `vite-plugin-solid` / `eslint-plugin-solid` / SolidStart deps in `package.json`, a Solid 1.x line of `solid-js` / `@solidjs/router` / `@solidjs/meta` (declared, or installed from the `latest` tag — Solid 2 releases are on `next`), `jsx` ≠ `preserve` or `jsxImportSource` ≠ `@solidjs/web` in tsconfig, Solid 1.x wiring in root config files, and stale installed guidance (kit updated but `sync` not re-run) |
 | Review command | `.cursor/commands/solid2-review.md` | `.claude/commands/solid2-review.md` | `/solid2-review` — on-demand deep review: runs both gates, then walks the diff against the skill checklist targeting the semantic failure classes regexes cannot see (post-`await` reads, effect misuse, unkeyed server rows, boundary placement, context snapshots) |
 
 Managed blocks are delimited with `<!-- solid2-agent-kit:*:start/end -->` markers; everything

package/bin/solid2-kit.mjs

@@ -4,7 +4,7 @@
 //
 //   solid2-kit init  [--cursor] [--claude] [--no-hooks] [--target <dir>]
 //   solid2-kit sync  [--cursor] [--claude] [--no-hooks] [--target <dir>]   (alias of init)
-//   solid2-kit check [--dir <srcdir>] [--target <dir>] [files...]
+//   solid2-kit check [--dir <srcdir>] [--target <dir>] [paths...]
 //   solid2-kit doctor [--target <dir>]
 //   solid2-kit hook (claude|cursor)          (stdin: agent hook JSON payload)
 //
@@ -19,6 +19,7 @@ import {
   readFileSync,
   readdirSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -404,6 +405,27 @@ function actionAsyncFindings(content) {
   }));
 }
 
+// TanStack Router for Solid exports names the Next.js / Solid Router 1.x rules
+// target (`useRouter()`, `notFound()`, `<Navigate>`). A match is exempt only
+// when this file binds that exact local name from one of these modules, so a
+// stray Next or Router 1.x call in the same file is still reported.
+const TANSTACK_ROUTER_MODULE = /^@tanstack\/(?:solid-router|router-core)$/;
+
+// Local names bound by `import [Default,] { a, b as c } from "<module>"`.
+function importedNames(content, moduleName) {
+  const names = new Set();
+  for (const decl of content.matchAll(
+    /\bimport\s+(?:type\s+)?(?:[\w$]+\s*,\s*)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g,
+  )) {
+    if (!moduleName.test(decl[2])) continue;
+    for (const specifier of decl[1].split(',')) {
+      const local = specifier.trim().replace(/^type\s+/, '').split(/\s+as\s+/).pop();
+      if (local) names.add(local);
+    }
+  }
+  return names;
+}
+
 const CHECKS = [
   {
     id: 'props-destructure-param',
@@ -560,6 +582,7 @@ const CHECKS = [
   {
     id: 'solid1-router',
     pattern: /<(?:HashRouter|MemoryRouter|Route|Navigate|A|FileRoutes|StartClient|StartServer)\b/g,
+    exemptImportsFrom: TANSTACK_ROUTER_MODULE,
     message:
       '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).',
   },
@@ -606,6 +629,7 @@ const CHECKS = [
     id: 'next-nav',
     pattern:
       /(?<![.\w])(?:useRouter|usePathname|revalidatePath|revalidateTag|notFound|hydrateRoot)\s*\(/g,
+    exemptImportsFrom: TANSTACK_ROUTER_MODULE,
     message:
       'Next.js / React DOM leftover. In-app navigation is useNavigate / <a href={Router.paths...}>; 404 is httpStatus(404); hydrate is hydrate(() => <App />, root).',
   },
@@ -716,11 +740,16 @@ function stripComments(content) {
   return out;
 }
 
+// Dependencies and dot-directories (.git, build caches, installed agent
+// guidance) are never project sources, so `check .` stays meaningful.
 function* walk(dir) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const path = join(dir, entry.name);
-    if (entry.isDirectory()) yield* walk(path);
-    else if (SOURCE_FILE.test(entry.name)) yield path;
+    if (entry.isDirectory()) {
+      if (entry.name !== 'node_modules' && !entry.name.startsWith('.')) yield* walk(path);
+    } else if (SOURCE_FILE.test(entry.name)) {
+      yield path;
+    }
   }
 }
 
@@ -733,7 +762,9 @@ function fileFindings(file, relativeTo) {
   const lines = raw.split('\n');
   const findings = [];
   for (const rule of CHECKS) {
+    const exempt = rule.exemptImportsFrom ? importedNames(content, rule.exemptImportsFrom) : null;
     for (const match of rule.find ? rule.find(content) : content.matchAll(rule.pattern)) {
+      if (exempt?.has(match[0].match(/[\w$]+/)[0])) continue;
       const lineNumber = content.slice(0, match.index).split('\n').length;
       findings.push(
         `${relative(relativeTo, file) || file}:${lineNumber} [${rule.id}] ${rule.message}\n  > ${lines[lineNumber - 1].trim()}`,
@@ -745,12 +776,30 @@ function fileFindings(file, relativeTo) {
 
 function check() {
   const target = resolve(flagValue('--target', '.'));
-  const fileArgs = positionalArgs();
+  const pathArgs = positionalArgs();
 
   let files;
-  if (fileArgs.length > 0) {
-    // Explicit file mode (used by agent hooks): check only the named sources.
-    files = fileArgs.map((file) => resolve(target, file)).filter((file) => SOURCE_FILE.test(file));
+  let scanned;
+  let walked = true;
+  if (pathArgs.length > 0) {
+    // Explicit path mode: named directories are walked, named files are
+    // checked when they are .ts/.tsx/.jsx sources.
+    files = [];
+    scanned = pathArgs;
+    walked = false;
+    for (const arg of pathArgs) {
+      const path = resolve(target, arg);
+      if (!existsSync(path)) {
+        console.error(`solid2-kit check — path not found: ${path}`);
+        process.exit(2);
+      }
+      if (statSync(path).isDirectory()) {
+        walked = true;
+        files.push(...walk(path));
+      } else if (SOURCE_FILE.test(path)) {
+        files.push(path);
+      }
+    }
   } else {
     const srcDir = resolve(target, flagValue('--dir', 'src'));
     if (!existsSync(srcDir)) {
@@ -758,6 +807,22 @@ function check() {
       process.exit(2);
     }
     files = [...walk(srcDir)];
+    scanned = [relative(target, srcDir) || '.'];
+  }
+
+  // A walk that found no sources points at the wrong tree; passing it would
+  // read as a clean gate in CI and in agent loops. A list of named files with
+  // no sources among them (changed-file pipelines on a docs-only change) has
+  // nothing to gate and passes.
+  if (files.length === 0 && !walked) {
+    console.log('solid2-kit check — OK (no .ts/.tsx/.jsx sources among the named files; nothing to check).');
+    return;
+  }
+  if (files.length === 0) {
+    console.error(
+      `solid2-kit check — no .ts/.tsx/.jsx sources found in ${scanned.join(', ')}; nothing was checked. Point --dir or [paths...] at the source tree.`,
+    );
+    process.exit(2);
   }
 
   let findings = 0;
@@ -1063,6 +1128,33 @@ const BANNED_DEPS = {
   vinxi: 'SolidStart 1.x toolchain. Solid 2 uses @solidjs/vite-plugin directly.',
 };
 
+// Packages whose npm `latest` dist-tag is still the Solid 1.x line (solid-js
+// 1.9, @solidjs/router 1.0, @solidjs/meta 0.29): a bare `pnpm add <name>`
+// installs it. The Solid 2 releases are published under `next`.
+const SOLID2_LINE_PACKAGES = [
+  { name: 'solid-js', id: 'solid-js-version', solid1: /^[\s^~=v]*[01](?:\.|$)/, fix: 'Install solid-js@next (^2).' },
+  {
+    name: '@solidjs/router',
+    id: 'router-version',
+    solid1: /^[\s^~=v]*[01](?:\.|$)/,
+    fix: 'Router 1.x is JSX <Route> with a solid-js ^1 peer; install @solidjs/router@next (2.x, createRouter({ routes })).',
+  },
+  {
+    name: '@solidjs/meta',
+    id: 'meta-version',
+    solid1: /^[\s^~=v]*0(?:\.|$)/,
+    fix: 'Meta 0.x is built for Solid 1 (<MetaProvider> required); install @solidjs/meta@next (1.x).',
+  },
+];
+
+function installedVersion(target, name) {
+  try {
+    return JSON.parse(readFileSync(join(target, 'node_modules', name, 'package.json'), 'utf8')).version;
+  } catch {
+    return undefined;
+  }
+}
+
 const CONFIG_SOURCE = /\.(?:m|c)?[jt]s$/;
 
 // Files installed by this kit that carry a version marker. When the kit
@@ -1079,9 +1171,21 @@ function doctorFindings(target) {
   for (const [name, message] of Object.entries(BANNED_DEPS)) {
     if (name in deps) report(`dep-${name.replace(/[@/]/g, '')}`, `package.json depends on "${name}". ${message}`);
   }
-  const solidRange = deps['solid-js'];
-  if (typeof solidRange === 'string' && /^[\s^~=v]*[01]\./.test(solidRange)) {
-    report('solid-js-version', `package.json pins solid-js "${solidRange}" — this kit teaches Solid 2.x; upgrade to ^2.`);
+  for (const { name, id, solid1, fix } of SOLID2_LINE_PACKAGES) {
+    const range = deps[name];
+    if (typeof range === 'string' && solid1.test(range)) {
+      report(id, `package.json pins ${name} "${range}" — the Solid 1.x line; this kit teaches Solid 2.x. ${fix}`);
+      continue;
+    }
+    // A range such as "latest" or "*" only shows its line once resolved.
+    if (range === undefined) continue;
+    const installed = installedVersion(target, name);
+    if (installed && solid1.test(installed)) {
+      report(
+        id,
+        `node_modules has ${name} ${installed} (package.json: "${range}") — the Solid 1.x line; this kit teaches Solid 2.x. ${fix}`,
+      );
+    }
   }
 
   for (const entry of readdirSync(target, { withFileTypes: true })) {
@@ -1183,7 +1287,7 @@ switch (command) {
         'Usage:',
         '  solid2-kit init  [--cursor] [--claude] [--no-hooks] [--target <dir>]  install/update guidance + edit hooks (default: both tools)',
         '  solid2-kit sync  [--cursor] [--claude] [--no-hooks] [--target <dir>]  alias of init (idempotent)',
-        '  solid2-kit check [--dir <srcdir>] [--target <dir>] [files...]         mechanical React/Solid 1.x pattern gate (default dir: src)',
+        '  solid2-kit check [--dir <srcdir>] [--target <dir>] [paths...]         mechanical React/Solid 1.x pattern gate (default dir: src)',
         '  solid2-kit doctor [--target <dir>]                                    project-wiring gate: deps, tsconfig, root configs',
         '  solid2-kit hook (claude|cursor)                                       edit-time gate for agent hooks (stdin: hook JSON payload)',
       ].join('\n'),

package/files/commands/solid2-review.md

@@ -26,8 +26,26 @@ Steps:
      `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);
+   - treating `<Errored>` as a terminal ErrorBoundary, or expecting it to catch
+     mutation failures (an error thrown out of an `action` reverts the overlay and
+     rejects the call — catch it in the action / a projection-folded map, or `.catch`
+     the call in the handler);
+   - effect `apply` functions with expression bodies (`(t) => (document.title = t)`,
+     `(v) => setX(v)`) — any return value but a cleanup halts reactivity; `onCleanup`
+     inside `apply` (never runs) or inside `onSettled`, and memos/effects/`flush()`
+     inside an `onSettled` callback (all throw);
+   - writes to a store outside its setter (`todos.push(x)`, `todo.done = ...` — silently
+     ignored) and `Map`/`Set`/`Date` fields mutated in a draft (not tracked);
+   - app-wide state as a module-level signal/store instead of a provider at the root
+     of `App` (shared across SSR requests);
+   - value-form `createOptimisticStore([])` / `createOptimistic(v)` holding durable
+     data (writes vanish on settle) instead of the function form refreshed after `yield`;
+   - route `preload` returning data read as `props.data` (captured once per match)
+     instead of `void getX(params.id)` + `createMemo(() => getX(props.params.id))`;
+   - `throw redirect()` / `return reload()` in server functions called without Solid
+     Router `action`/`query` (the caller gets a raw `Response` or `null`, never its
+     data), and POST forms built on a bare function's `.url` (TS2339) instead of a
+     router `action`;
      error reporting done as a side effect inside `fallback` instead of
      `configureClientErrors` / `configureServerErrors` / `render(..., { onError })`;
    - store setter callbacks that `await` (the draft closes when the callback returns —

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`. 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`. Confirmations on another channel — fire-and-forget sends, and mutations whose result is read through `live()` — wait with `yield until(predicate, {timeout})`, not `refresh()`. Declare `live(GET(fn))` (`live()` outermost). 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, `[ASYNC_STORE_SETTER]` means a store setter callback awaited (the draft is a synchronous transaction — await first, then write), and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or `render(..., { onError })`), not a side effect inside `<Errored fallback>`; the server hook must return a reference or nothing, never the error itself. `<Dynamic>` is deprecated — use `dynamic()`. Observability is on by default in development: whenever a change touches stores, lists, async, actions, or effects, keep the dev console free of `[CODE]` findings and run an attribution session (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end` with `@solidjs/diagnostics` installed, otherwise `isDev`-guarded `attribution.enable({ log: false })` + `why()` / `costs()`) before finishing. `vite dev` is always the dev build; `solid({ observe: true })` is a production opt-in.
+- 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` — return the cleanup; `onCleanup`, memo/effect creation, and `flush()` throw inside the `onSettled` callback in dev. Effect `apply` functions use block bodies (`(t) => { document.title = t; }`): any return value other than a cleanup function halts reactivity. Stores are written only through the setter's draft — writes to the store itself are silently ignored, and `Map`/`Set`/`Date` inside a store are not tracked. Shared state, app-wide included, is created in a provider at the root of `App` (`createContext<T>()` + `useX()`), never a module-level signal/store (one instance serves every SSR request). Errors thrown out of an `action` never reach `<Errored>` — catch them in the action or `.catch` the call. 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`. Confirmations on another channel — fire-and-forget sends, and mutations whose result is read through `live()` — wait with `yield until(predicate, {timeout})`, not `refresh()`. Declare `live(GET(fn))` (`live()` outermost). 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, `[ASYNC_STORE_SETTER]` means a store setter callback awaited (the draft is a synchronous transaction — await first, then write), and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or `render(..., { onError })`), not a side effect inside `<Errored fallback>`; the server hook must return a reference or nothing, never the error itself. `<Dynamic>` is deprecated — use `dynamic()`. Observability is on by default in development: whenever a change touches stores, lists, async, actions, or effects, keep the dev console free of `[CODE]` findings and run an attribution session (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end` with `@solidjs/diagnostics` installed, otherwise `isDev`-guarded `attribution.enable({ log: false })` + `why()` / `costs()`) before finishing. `vite dev` is always the dev build; `solid({ observe: true })` is a production opt-in.

package/files/shared/rules-body.md

@@ -75,7 +75,14 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     fed to `<For>` (that rebuilds the window array every time).
 8. **Effects have two phases**: `createEffect(compute, apply)`. All reactive reads go in
     `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
+    cleanup. `apply` returns a cleanup function or nothing — **write it with a block body**:
+    `(t) => { document.title = t; }`, never `(t) => (document.title = t)` or
+    `(v) => setX(v)` (an assignment or setter returns its value; dev throws
+    `invalid cleanup value`, production fails on the next run, and either halts the whole
+    reactive system). An `apply` that only calls a local setter is still rule 4 with a
+    block body — make it a derivation. Register an effect's cleanup by returning it
+    from `apply` — `onCleanup` there never runs (`[NO_OWNER_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. 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" })`.
@@ -86,6 +93,12 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    `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()`.
+   The store itself is read-only: `todos.push(x)`, `state.count++`, or
+   `todo.done = !todo.done` outside a setter is **silently ignored** (no throw, no
+   warning, and TypeScript accepts it) — every write goes through the setter's draft.
+   `Map`, `Set`, and `Date` are stored as-is, not proxied: `draft.selected.add(id)`
+   changes the object but notifies nobody. Model sets as `Record<id, true>` (or an
+   array), or assign a new instance in the setter (`draft.tags = new Set([...draft.tags, t])`).
    The setter callback is a **synchronous** transaction: `setStore(async (draft) => …)`
    throws `[ASYNC_STORE_SETTER]` in dev (writes after the first `await` were silently
    lost before). `await` first, then call the setter (inside an `action`, `yield` first).
@@ -143,9 +156,16 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `createContext<T>()` without a default throws when read outside a provider (good) — use
     that for any reactive payload. `createContext("light")` is only for a primitive static
     fallback; a dummy default on a store/signal context *runs* and then silently no-ops
-    without a provider. Truly app-wide singletons (theme, session, locale) are a
-    **module-level** signal/store — Context is subtree scoping, not a React-style
-    app store. Module state is shared across SSR requests.
+    without a provider. **Shared state lives in a provider, including app-wide state**
+    (theme, session, cart, locale): a factory such as `createCart()` called by a provider
+    component placed at the root of `App`, read through `createContext<T>()` (no default)
+    and a `useCart()` hook. Module scope is for constants and the `createContext` call itself —
+    never `export const [session, setSession] = createStore(...)`. Module state has no
+    owner, and under `ssr: true` one module instance serves every request, so one
+    visitor's state renders into another's HTML (`[SERVER_WRITE]`); a module-level
+    store derived from a server function throws `Cannot call server function outside
+    of a request` at import. A client-only build happens to work, until the day SSR is
+    turned on.
 12. Refs: `let el!: HTMLDivElement` + `ref={el}` or `ref={(node) => (el = node)}`, or forward
     `props.ref`. Compose with arrays: `ref={[props.ref, (node) => (el = node)]}`. No
     `useRef`/`.current`. Ref callbacks run untracked and **without an owner**; their
@@ -155,12 +175,18 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `onSettled(() => { ...; return cleanup })` — `onCleanup` is for custom
     primitives and captured owners, not component bodies. Each `onSettled`
     registers a **single** fire (reads inside are untracked); ongoing
-    imperative work is `createEffect`.
+    imperative work is `createEffect`, created in the component body — not inside
+    the callback. The `onSettled` callback is a restricted scope: `onCleanup`
+    (`[CLEANUP_IN_FORBIDDEN_SCOPE]`), creating a memo or effect
+    (`[PRIMITIVE_IN_FORBIDDEN_SCOPE]`), and `flush()` all throw there in dev and halt
+    the reactive system. A 1.x `onMount(() => { …; onCleanup(…) })` becomes
+    `onSettled(() => { const id = setInterval(tick, 1000); return () => clearInterval(id); })`.
 13. **Writes are staged** and commit on the next microtask. Event handlers need nothing
     special; tests and imperative integration code must call `flush()` before observing
     updated *synchronous* state or DOM. Waiting on an async memo is
     `await resolve(() => value())` (or Testing Library async queries), not `flush()`.
-    Never call `flush()` inside an `action`.
+    Never call `flush()` inside an `action`, an `onSettled` callback (throws in dev), or an
+    effect callback (a no-op, `[FLUSH_IN_EFFECT_CALLBACK]`).
 14. Do not port these React tools — they have no Solid equivalent because the problems they
     solve don't exist: `useCallback`, `React.memo`, `forwardRef`, `useSyncExternalStore`,
     dependency arrays, `startTransition`/`useTransition` (updates are held and coordinated
@@ -190,8 +216,12 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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.
+    remount. `<Errored>` catches failing *reads* and renders, never a mutation: an
+    error that escapes an `action` discards its optimistic writes and rejects the
+    promise the call returned — no boundary sees it, and uncaught it is an unhandled
+    rejection with the UI silently reverted. Catch expected failures inside the action
+    (per-row: an errors map the projection folds in, which survives the optimistic
+    overlay; otherwise a toast), and `.catch` the call in the handler for the rest.
     Error monitoring is a hook, not a side effect in the fallback: the boundary-caught
     failures no global handler sees reach `configureClientErrors({ onError })` from
     `solid-js` (or `render(..., { onError })` per root) and `configureServerErrors({ onError })`
@@ -200,7 +230,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     nothing or a reference id, never the error itself (message/stack/secrets would
     reach the browser).
     Making a client store "real" is additive: same setters, wrap mutations in
-    `action`, swap `createOptimisticStore` and a file of server functions — do
+    `action`, swap in the **function form** `createOptimisticStore(() => api.list(), [])`
+    (with `refresh` after the `yield`) 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 }`
@@ -233,7 +264,12 @@ 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); write the
+    the sync mutation *is* the prediction (an overlay, discarded on settle). Durable data
+    therefore lives in the function form (`createOptimisticStore(() => api.list(), [])`,
+    or one that reads a separate `createStore`); the value form
+    `createOptimisticStore([])` / `createOptimistic(false)` is a pure overlay with no
+    durable layer — action writes vanish on settle (a saved row disappears) and writes
+    outside an action do not stick — so use it only for in-flight flags. Write the
     body as a generator (`function*` / `async function*`) suspending on `yield`, never a
     plain `async` function (`solid2-kit check` flags that). After a bare `await`, put a
     bare `yield` before the next write **and** before anything that creates a reader
@@ -309,15 +345,25 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `revalidate(getUser.key)`. Do not wrap mutations in `query` (an undeclared server
     function becomes GET). `Router.paths` is not the current location (`useLocation` /
     `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 —
+    `search` schema + path node). A route `preload` *starts* reads and returns nothing —
+    `preload: ({ params }) => void getProduct(params.id)` (wrap the route in `defineRoute`
+    to type `params`) — and the page reads the same query in a memo:
+    `createMemo(() => getProduct(props.params.id))`. `props.data` is whatever `preload`
+    returned when the route first matched: it does not follow param changes (and an async
+    `preload` makes it a Promise), so return a value only for data that stays fixed while
+    the route is matched. 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`. 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
+    `getRequestEvent()`, never a caller-supplied user id. Unscripted (no-JS) POST
+    forms use a router `action` over a `(form: FormData)` server function (the post
+    arrives as one `FormData`; other signatures make `action={save}` TS2322) —
+    `<form action={save} method="post">` — not the
+    function's `.url` and not a hand-built `/_server/` path: a bare `"use server"`
+    function has no typed `.url` (TS2339). `.url` is typed only on `GET()` / `live()`
+    references, for `method="get"` search forms. Client history adapters do not select the SSR URL — pass
     `<Router url={request.url}>` (or rely on the request event). Secrets belong in
     `virtual:env/server`, never the `client` env map / `import.meta.env`. Document head is
     `<Title>` / `<Meta>` from `@solidjs/meta` with **no** `MetaProvider`. A static
@@ -330,8 +376,15 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     fallback printing `err().message` shows `"Internal Server Error"` in a production
     server render) — so intentional client-facing failures are `markSafeError(...)` or
     `throw respond(body, { status })`. 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()` /
+    on a `GET()`-declared read; the method mirrors the operation). `redirect()` /
+    `reload()` are signals for an integration: Solid Router's `action` / `query` and the
+    no-JS form post apply them. A direct caller — a core `action`, a handler, a plain
+    memo — never gets your data: it receives the raw `Response` as the resolved value
+    (typed as your data, no navigation); only when a mounted router's single-flight
+    hook intercepts a direct POST call does it navigate, and the call then resolves to
+    `null`. So guards `throw redirect("/sign-in")` only when router `action` /
+    `query` call the function; without the router, `throw respond(null, { status: 401 })`
+    (the call rejects) or return a value and navigate in the caller. `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 —
@@ -395,7 +448,7 @@ directory (default `src/`).
 | `import type { JSX } from "solid-js"` / `JSX.Element` as the children type | `solid-js` exports no `JSX` namespace: children/returns are `Element` from `"solid-js"`; DOM-specific `JSX` types (`JSX.IntrinsicElements`, `JSX.CSSProperties`) from `"@solidjs/web"` |
 | `createResource` | async `createMemo` + `<Loading>`/`<Errored>`; `refresh()`, `latest()`, `isPending()` |
 | `createEffect(fn)` (one arg), `on(...)` | `createEffect(compute, apply)`; deps belong in `compute` |
-| `onMount` | `onSettled` (return cleanup from its callback) |
+| `onMount` | `onSettled(() => { ...; return cleanup })` — return the cleanup; `onCleanup`, memo/effect creation, and `flush()` throw inside the callback |
 | `batch(...)` | delete it — writes auto-batch; `flush()` only to observe synchronously |
 | `<Suspense>`, `<ErrorBoundary>`, `<SuspenseList>` | `<Loading>`, `<Errored>` (fallback gets an error *accessor*), `<Reveal>` |
 | `<Index>` | `<For keyed={false}>` |
@@ -403,7 +456,7 @@ directory (default `src/`).
 | `setState("a", "b", value)` path setters, `produce(...)` | draft setter: `setState(draft => { ... })` |
 | `mergeProps` / `splitProps` / `unwrap` | `merge` / `omit` / `snapshot` |
 | `classList={...}` | `class` object/array form |
-| `createMutable`, `modifyMutable` | `createStore` + draft setters |
+| `createMutable`, `modifyMutable` | `createStore` + draft setters (direct writes to the store are silently ignored) |
 | `createComputed`, `createSelector`, `createDeferred` | `createMemo`, `createProjection`, external scheduling |
 | `startTransition`, `useTransition` | automatic held updates + `isPending` |
 | `onError` / `catchError` | `<Errored>` or effect bundle `{ effect, error }` |

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

@@ -41,7 +41,8 @@ Practical consequences:
 | Expensive derivation, multiple consumers, or equality boundary needed | `createMemo(() => ...)` |
 | Follows a prop but user can locally override; prop change resets | writable derivation: `createSignal(() => props.value)` / `createStore(() => props.value, fallback)` |
 | Shared by a subtree, independent per provider instance | signal/store created inside a provider component, passed via context |
-| Truly app-wide singleton (theme, session, locale) | module-level signal/store (beware SSR: module state is shared across requests) |
+| App-wide state (theme, session, cart, locale) | the same provider, placed at the root of `App` — not a module-level signal/store (under SSR one module instance serves every request) |
+| Constants (a category list, a formatter, the `createContext` call) | module scope |
 | Tentative value during a mutation | `createOptimistic` / `createOptimisticStore` + `action` |
 | Values pushed by an external subscription (websocket, reactive client) | async iterable returned from a memo (or function-form `createStore` for keyed reconciliation) — never `{ data, error }` signal pairs |
 
@@ -158,6 +159,32 @@ at component-body top level is a write in an owned scope — dev throws
 `[REACTIVE_WRITE_IN_OWNED_SCOPE]` (rc.9 closed the exemption store writes had) — so
 seed the shape through the `createStore` argument or a derivation.
 
+**The store itself is read-only; only the draft writes.** An assignment or mutating
+call on the store proxy outside a setter is *ignored* — no throw, no dev warning, the
+value does not change, and TypeScript accepts it (`Store<T>` is `T`). This is the
+MobX / Vue / Solid 1 `createMutable` reflex:
+
+```tsx
+// WRONG — all silently ignored
+todos.push(todo);
+state.count++;
+todo.done = !todo.done;
+
+// CORRECT
+setTodos((draft) => { draft.push(todo); });
+setState((draft) => { draft.count++; });
+setTodos((draft) => {
+  const row = draft.find((t) => t.id === id);
+  if (row) row.done = !row.done;
+});
+```
+
+Plain objects and arrays are proxied; `Map`, `Set`, and `Date` are stored as they are.
+`draft.selected.add(id)` inside a setter mutates the `Set` but notifies nobody. Keep a
+set of ids as `Record<string, true>` (`draft.selected[id] = true` /
+`delete draft.selected[id]`, both tracked) or an array, or assign a new instance
+(`draft.tags = new Set([...draft.tags, tag])`) so the property itself changes.
+
 **External collections enter stores through reconciliation, never wholesale assignment.**
 `draft.todos = serverTodos` renders correctly but replaces every object identity — all
 subscribers under the path re-run and row identity is lost. In order of preference:
@@ -248,6 +275,25 @@ createEffect(
 );
 ```
 
+`apply` returns a cleanup function or nothing — write it with a **block body**. An
+expression-bodied arrow returns whatever the expression evaluates to: an assignment
+(`(t) => (document.title = t)`) returns the string, and a setter (`(v) => setDraft(v)`)
+returns the value it set. Dev throws `effect callback returned an invalid cleanup value`,
+production throws a `TypeError` on the next run, and both halt the whole
+reactive system (`[REACTIVITY_HALTED]`). TypeScript reports it as TS2345; a JS project
+gets no warning. The cleanup of an effect is the `apply` return value — `onCleanup`
+inside `apply` has no owner and never runs (`[NO_OWNER_CLEANUP]`).
+
+```tsx
+// WRONG — returns the assigned string; halts reactivity (dev: first run, prod: next run)
+createEffect(() => title(), (t) => (document.title = t));
+
+// CORRECT
+createEffect(() => title(), (t) => {
+  document.title = t;
+});
+```
+
 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
@@ -572,12 +618,28 @@ function createTodos() { // call from a component — not module scope (SSR shar
 Three layers, in this order: durable source → ephemeral UI that must survive
 overlay discard (the `errors` map, folded in the projection) → optimistic overlay
 (`pending`, the predicted `completed`). Consumers read one store. Catch
-*expected* mutation failures in the action so a toggle error does not blank the
-list through `<Errored>`; unhandled projection/render errors still reach the
-boundary.
+*expected* mutation failures in the action, because nothing else will show them:
+an error that escapes an action discards its optimistic writes and rejects the
+promise the call returned — it never reaches `<Errored>`, which catches failing
+reads and renders only (projection and render errors still reach the boundary).
+Uncaught, the UI silently reverts and the rejection is unhandled. Put expected
+failures in the errors map or a toast inside the action, and `.catch` the call in
+the handler for the rest:
+
+```tsx
+<button
+  type="button"
+  onClick={() => {
+    removeTodo(todo.id).catch(() => showToast('Could not delete'));
+  }}
+>
+  Delete
+</button>
+```
 
 Going from a client store to the server is **additive**: same `setTodos`
-calls, wrap each mutation in `action`, swap in `createOptimisticStore` and a
+calls, wrap each mutation in `action`, swap in the **function form**
+`createOptimisticStore(() => api.list(), [])` (with `refresh` after the `yield`) and a
 file of server functions. Do not rewrite `App.tsx` with loading/error branches,
 and do not snapshot-the-cache / write-a-prediction / restore-on-error. A cache
 library is not the productionizing step — the sync mutation already was the
@@ -594,6 +656,16 @@ Ordinary signal/store writes inside an action are held until it settles. Never c
 Do not set a `submitted` signal and watch it from an effect — that work belongs in the
 handler or the `action`.
 
+**The value form has no durable layer.** `createOptimisticStore([])` (or
+`createOptimistic(value)`) is a pure overlay: writes inside an action vanish when it
+settles, and writes outside an action do not stick. Copying the reference example
+`createOptimisticStore<Todo[]>([])` and writing the saved row after the `yield`
+leaves an empty list once the action settles, with no warning. Durable data comes
+from the function form — `createOptimisticStore(() => api.list(), [])` refreshed
+after the `yield`, or `createOptimisticStore(() => base.todos, [])` over a separate
+`createStore` that the action writes the confirmed value into. Keep the value form for
+in-flight flags.
+
 `createOptimistic` / `createOptimisticStore` are for a tentative value during an
 active mutation, not a local editing session (use a writable derivation or a plain
 store for that). A whole-form `createOptimistic(false)` saving flag is fine; prefer
@@ -772,9 +844,47 @@ function ThemeButton() {
 
 Pass accessors/setters/stores through context — never `value={theme()}` (a dead snapshot).
 No `useMemo` for the value object, no context splitting: the object is created once and
-fine-grained updates flow through the signals inside it. Context is **subtree scoping**.
-A true app-wide singleton (theme, session, locale) is a module-level signal/store —
-do not invent a root provider for that. Module state is shared across SSR requests.
+fine-grained updates flow through the signals inside it.
+
+**App-wide state is the same provider, placed at the root of `App`** — not a
+module-level signal or store. Module scope is for constants and the `createContext`
+call itself:
+
+```tsx
+import { createContext, createStore, useContext, type ParentProps } from 'solid-js';
+
+type CartItem = { id: string; quantity: number };
+
+// WRONG under SSR — one store for every request the server ever handles
+// export const [cart, setCart] = createStore({ items: [] as CartItem[] });
+
+// CORRECT — one store per provider instance: per tab in the browser, per request on the server
+function createCart() {
+  const [cart, setCart] = createStore({ items: [] as CartItem[] });
+  return { cart, setCart };
+}
+
+const CartContext = createContext<ReturnType<typeof createCart>>();
+
+export function CartProvider(props: ParentProps) {
+  return <CartContext value={createCart()}>{props.children}</CartContext>;
+}
+
+export function useCart() {
+  return useContext(CartContext); // throws ContextNotFoundError outside CartProvider
+}
+
+// App: <CartProvider><ThemeProvider>{/* router / pages */}</ThemeProvider></CartProvider>
+```
+
+Module state has no owner (nothing disposes it), and under `ssr: true` the server
+loads the module once and serves every request from it: `createStore(value)` on the
+server is the plain object, so one visitor's writes render into the next visitor's
+HTML (`[SERVER_WRITE]`). A module-level store derived from a server function fails
+sooner — `Cannot call server function outside of a request` while the module loads.
+In a client-only build a module-level store is one per tab and works, which is why it
+looks fine until `ssr: true` is turned on; the provider costs nothing extra and
+survives that change.
 
 ### Refs
 
@@ -815,6 +925,32 @@ 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.
 
+### `onSettled` — one-time setup, restricted scope
+
+`onSettled` is the `onMount` replacement, and its callback is a **restricted scope**:
+`onCleanup` throws there (`[CLEANUP_IN_FORBIDDEN_SCOPE]`), creating a memo or effect
+throws (`[PRIMITIVE_IN_FORBIDDEN_SCOPE]`), and so does `flush()` — each halts the
+reactive system in dev. Return the cleanup; create effects and memos in the component
+body, next to the `onSettled` call, not inside it.
+
+```tsx
+// WRONG — the mechanical 1.x port of onMount + onCleanup
+onSettled(() => {
+  const id = setInterval(tick, 1000);
+  onCleanup(() => clearInterval(id));
+});
+
+// CORRECT
+onSettled(() => {
+  const id = setInterval(tick, 1000);
+  return () => clearInterval(id);
+});
+```
+
+Effect callbacks follow the same shape: return the cleanup from `apply` (an
+`onCleanup` there never runs), and `flush()` inside one is a no-op
+(`[FLUSH_IN_EFFECT_CALLBACK]`).
+
 ### Per-value SSR policy: `ssrSource`
 
 `clientOnly` splits a *component*; `ssrSource` keeps one *value* off the server,
@@ -1200,8 +1336,57 @@ plain `<a href={Router.paths.about}>` (or `useNavigate`); there is no `<A>` /
 `<Navigate>` / `<HashRouter>` / `<FileRoutes />`. Do not assign
 `window.location.href` or call `history.pushState` for in-app navigation.
 Session location is `useLocation` / `useParams`,
-not `Router.paths`. A route `preload` result is `props.data` on the matched
-component (and the factory `preload` result is the root render prop's `props.data`).
+not `Router.paths`.
+
+**Route `preload` starts reads; the page reads them in a memo.** `preload` runs when
+the route matches (and on link hover), so it should kick off the query and return
+nothing; the component reads the same query through a memo that tracks the params:
+
+```tsx
+// src/data/products.ts
+import { query } from '@solidjs/router';
+
+export const getProduct = query(async (id: string) => {
+  const response = await fetch(`/api/products/${id}`);
+  return (await response.json()) as Product;
+}, 'product');
+
+// src/router.ts — defineRoute types params from the path (params.id: string)
+import { lazy } from 'solid-js';
+import { createRouter, defineRoute } from '@solidjs/router';
+import { getProduct } from './data/products';
+
+export const Router = createRouter({
+  routes: [
+    defineRoute({
+      path: '/products/:id',
+      preload: ({ params }) => void getProduct(params.id),
+      component: lazy(() => import('./pages/Product')),
+    }),
+  ],
+});
+
+// src/pages/Product.tsx
+import { createMemo } from 'solid-js';
+import type { RouteProps } from '@solidjs/router';
+import { getProduct } from '../data/products';
+
+export default function ProductPage(props: RouteProps<'/products/:id'>) {
+  const product = createMemo(() => getProduct(props.params.id));
+  return <h1>{product().name}</h1>;
+}
+```
+
+Do not return the data from `preload` and render `props.data` (the Remix-loader
+shape): `props.data` is whatever `preload` returned when the route first matched, so
+navigating `/products/mug` → `/products/bowl` keeps showing the mug, and an `async`
+preload makes it a Promise (`props.data.name` is TS2339). Return a value only for
+data that stays fixed while the route is matched. The factory `preload` on
+`createRouter` runs once per mount/request; its result is the root render prop's
+`props.data`. Plain route objects type `params` as an open record (`string |
+undefined` per key) — wrap a route in `defineRoute` when `preload` or the component
+needs `params.id: string`.
+
 Link warming: `preload="false"` skips that link's *data* preload; `preloadLinks: false`
 disables automatic link preloading. Intent values are `"initial"` / `"navigate"` /
 `"native"` / `"preload"`. One router per app.
@@ -1358,8 +1543,42 @@ 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). Return or throw a redirect — guards read `if (!session?.userId) throw
-redirect("/sign-in")`. `redirect()` and `respond()` accept the same `revalidate`
+guides).
+
+**`redirect()` / `reload()` are signals for an integration, not navigation.** Solid
+Router's `action` / `query` apply them (navigate, revalidate), and a no-JS form post
+follows the 302. Any other caller — a core `action`, an event handler, a plain
+`createMemo(() => listOrders())` — receives the raw `Response` as the resolved value:
+no navigation happens, and the type still claims your data. (When a mounted router's
+single-flight hook intercepts a direct POST call, it does navigate, but the call
+resolves to `null`; a direct `GET()` read always gets the `Response`.) Either way the
+caller never gets its data, so the redirect guard belongs to functions called through
+the router:
+
+```ts
+import { getRequestEvent, redirect, respond } from '@solidjs/web';
+
+// called through a router action/query: the router navigates to /sign-in
+export async function listOrders() {
+  'use server';
+  const userId = getRequestEvent()?.locals.userId;
+  if (!userId) throw redirect('/sign-in');
+  return database.orders.forUser(userId);
+}
+
+// no router in the project (core action + server functions): reject instead
+export async function listMyOrders() {
+  'use server';
+  const userId = getRequestEvent()?.locals.userId;
+  if (!userId) throw respond(null, { status: 401 });
+  return database.orders.forUser(userId);
+}
+```
+
+Without the router, fail with `throw respond(..., { status })` (the call rejects and
+`<Errored>` / the action's `catch` sees it), or return a value and navigate in the
+caller. Return a redirect when it is the successful outcome, throw it for an early
+exit. `redirect()` and `respond()` accept the same `revalidate`
 option as `reload()` when the mutation also changes location or returns a value;
 `revalidate: REVALIDATE_ALL` (`"*"`, from `@solidjs/web`) declares every cache entry
 stale, distinct from omitting it (the host's default) and from `[]` (nothing). After a router/server mutation do **not** follow with a client `fetch`
@@ -1476,10 +1695,22 @@ Express `app.use`. Server functions that return components
 (`serverFunctions: { components: true }`) are experimental preview — do not use
 them unless the project already has that flag on.
 
-Unscripted forms: `<form method="post" action={createTodo.url}>` (the reference
-`.url`), not a client `preventDefault` + `fetch`, and not a hand-built
-`/_server/` URL. GET forms (`method="get" action={search.url}`) are only for
-idempotent search — do not use a GET form for a mutation.
+Unscripted (no-JS) POST forms go through a router action —
+`const save = action(createTodo, "create-todo")` from `@solidjs/router`, then
+`<form action={save} method="post">` — not a client `preventDefault` + `fetch`, not a
+hand-built `/_server/` URL, and not `action={createTodo.url}`: a bare `"use server"`
+function keeps its declared function type, so `.url` is a type error (TS2339) even
+though it exists at runtime (and `serverFunctionActionUrl(createTodo)` is TS2345).
+The post arrives as one `FormData` argument, so the function behind `action={save}`
+takes `(form: FormData)` and parses and validates the fields inside; any other
+signature makes `action={save}` a type error (TS2322). Bind leading JSON-safe
+arguments with `action={save.with(id)}` for `(id: string, form: FormData)`; a function
+that already has a typed signature gets a separate `FormData` server function that
+parses and calls it.
+`.url` is typed only on `GET()` / `live()` references, which makes it the address of a
+`method="get"` search form (`action={searchProducts.url}`; the function receives the
+fields as `URLSearchParams`). GET forms are only for idempotent search — do not use a
+GET form for a mutation.
 
 ### Document head — no MetaProvider
 
@@ -1515,8 +1746,11 @@ how to reuse. Prefer the form on the right.
 | `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) |
+| `todos.push(x)` / `state.count++` / `todo.done = !todo.done` on the store itself | `setTodos((draft) => { draft.push(x); })` — writes to the store proxy outside a setter are silently ignored (no error, no warning, tsc passes) |
+| `createStore({ selected: new Set<string>() })` + `draft.selected.add(id)` | `selected: {} as Record<string, true>` + `draft.selected[id] = true` / `delete draft.selected[id]`, or `draft.selected = new Set([...draft.selected, id])` — `Map` / `Set` / `Date` are stored as-is, not tracked |
 | `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))` |
+| `createEffect(() => user, (u) => { log(u.name); })` | `createEffect(() => user.name, (name) => { log(name); })` |
+| `createEffect(() => title(), (t) => (document.title = t))` / `(v) => setX(v)` | `(t) => { document.title = t; }` — apply returns a cleanup or nothing; any other return value halts reactivity. An apply that only calls a local setter is rule 4 even with braces (`solid2-kit check` flags it): use a (writable) derivation |
 | `<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 |
 | `setCount(count() + 1)` when writes can batch | `setCount((c) => c + 1)` |
@@ -1553,15 +1787,17 @@ how to reuse. Prefer the form on the right.
 | `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 |
+| `export const [cart, setCart] = createStore(...)` for app-wide state | `createCart()` called by a `CartProvider` at the root of `App`, read with `useCart()` over `createContext<T>()` — module state has no owner and, under SSR, one instance serves every request (`[SERVER_WRITE]`). Module scope is for constants and `createContext` |
 | `import { GET } from "@solidjs/start"` / `createAsync` / `useSubmission` / `<FileRoutes />` / `"use client"` | `GET` from `@solidjs/web/server-functions`; `createMemo(() => getUser(id()))`; `useSubmissions`; `fileRoutes(pageRoutes)`; Solid has no `"use client"` |
 | `<Show keyed when={user()}>` by default | default `Show` (keeps children mounted); `keyed` only when internal state must reset |
 | overlapping truthy `<Match>`es all expected to render | first truthy `<Match>` wins; later matches are skipped |
 | missing `<HydrationScript />` / one script for many roots | once, before app markup, when the app owns the document; distinct `renderId` per extra root |
-| `Router.paths` as the current URL; calling `preload()` and using the return as props | `useLocation` / `useParams`; factory/route `preload` result is `props.data` |
+| `Router.paths` as the current URL | `useLocation` / `useParams` |
+| `preload: async ({ params }) => getProduct(params.id)` + `props.data.name` in the page | `preload: ({ params }) => void getProduct(params.id)` + `createMemo(() => getProduct(props.params.id))` — `props.data` is captured once when the route matches (stale on param change; a Promise for async preloads) |
 | `query.get(key)` with no guaranteed entry; `query.set(key, promise)` | `query.get` throws if missing; `query.set` does not accept a promise |
 | `onCleanup(() => ...)` in a component body | `onSettled(() => { ...; return cleanup })` — `onCleanup` is for custom primitives |
-| `onSettled` with reactive reads expecting re-runs | each call is a **single** fire; reads are untracked. Ongoing work is `createEffect` |
+| `onSettled` with reactive reads expecting re-runs | each call is a **single** fire; reads are untracked. Ongoing work is `createEffect`, created in the component body |
+| `onSettled(() => { const id = setInterval(tick, 1000); onCleanup(() => clearInterval(id)); })` | `onSettled(() => { const id = setInterval(tick, 1000); return () => clearInterval(id); })` — `onCleanup`, `createMemo` / `createEffect`, and `flush()` throw inside the callback |
 | `<Router>` nested inside `<Router>` | one instance; nest `children` arrays (or a lazy children thunk) |
 | `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 |
@@ -1572,7 +1808,7 @@ how to reuse. Prefer the form on the right.
 | `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` |
 | `findUser(userId)` with the id from the client as identity | `getRequestEvent()!.locals.userId` |
-| `action={"/_server/" + id}` in app JSX | `action={createTodo.url}` or a router `action` |
+| `action={"/_server/" + id}` / `action={createTodo.url}` on a POST form | a router action: `const save = action(createTodo, "create-todo")` + `<form action={save} method="post">` over a `(form: FormData)` server function (other signatures are TS2322) — `.url` on a bare `"use server"` function is TS2339; it is typed only on `GET()` / `live()` references (GET search forms) |
 | `<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 |
@@ -1587,7 +1823,7 @@ how to reuse. Prefer the form on the right.
 | `class={{ pending: isPending(id) }}` flashing on every navigation | same class + a short CSS `transition-delay` so only slow swaps show |
 | `<Comments />` nested under `{story().title}` assumed to waterfall | both mount immediately and fetch in parallel if the child reads an already-known id; a real waterfall is `createMemo(() => fetchAuthor(story().authorId))` or `storyId={props.story.id}` |
 | `<Errored>` as a terminal ErrorBoundary; `reset={() => location.reload()}` | the boundary heals when the source succeeds again; `reset` retries collected *sources*, not a UI remount |
-| `<Errored>` around a list catching a toggle/save failure | catch expected mutation failures in the `action`; keep row errors in a map the projection folds in (survives overlay discard) |
+| `<Errored>` around a list expected to catch a toggle/save failure | an error thrown out of an `action` never reaches `<Errored>` — it reverts the overlay and rejects the call's promise. Catch expected failures in the `action` (row errors in a map the projection folds in, which survives overlay discard; otherwise a toast) and `.catch` the call in the handler |
 | `yield { ...tick, connected: true }` from `live()` | yield the value; wire status is `source.onstatus` (`"connected"` / `"reconnecting"` / `"closed"`) |
 | sibling `<Loading>` fallbacks stacking as popcorn | `<Reveal collapsed>` (sequential default) suppresses tail skeletons past the frontier |
 | in-memory cache around a GET server function | `return respond(value, { headers: { "cache-control": "..." } })` — metadata rides HTTP, the value rides the graph |
@@ -1599,6 +1835,7 @@ how to reuse. Prefer the form on the right.
 | 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 |
+| `throw redirect("/sign-in")` / `return reload(...)` in a function called directly (core `action`, handler, plain memo) | only Solid Router `action` / `query` (and no-JS form posts) apply them — a direct caller resolves to the raw `Response` (or `null` when the router's single-flight hook intercepts a POST call), typed as your data. Without the router: `throw respond(null, { status: 401 })` or return a value and navigate in the caller |
 | `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 |
@@ -1633,7 +1870,8 @@ how to reuse. Prefer the form on the right.
 | `createRenderEffect` / `createTrackedEffect` as the default effect | two-phase `createEffect(compute, apply)` |
 | `createEffect(() => source(), () => setError(null))` to reset a signal | `createSignal(() => { source(); return null; })` — the writable derivation resets on change; a sole-setter apply is rule 4 |
 | a "server-safe" initial value adopted after mount (React hydration-mismatch fix) | client mode mounts with `render()` into an empty body — no hydration, no mismatch; read `localStorage` / `matchMedia` directly at signal creation |
-| rewrite `App.tsx` with loading/error branches, or snapshot/restore, when the list moves to the server | same `setTodos`; wrap mutations in `action`; swap `createOptimisticStore` + a server-functions file. The overlay is discarded; the confirmed store is the truth |
+| rewrite `App.tsx` with loading/error branches, or snapshot/restore, when the list moves to the server | same `setTodos`; wrap mutations in `action`; swap in function-form `createOptimisticStore(() => api.list(), [])` + a server-functions file. The overlay is discarded; the confirmed store is the truth |
+| `createOptimisticStore<Todo[]>([])` holding the list, saved rows written after `yield` | `createOptimisticStore(() => api.list(), [])` + `refresh(todos)` (or a function form over a separate `createStore`) — the value form is a pure overlay: action writes vanish on settle |
 | disable an optimistic row until ack, or mutex rapid clicks / freeze unrelated writes | keep the control enabled; `action` is the transaction. An in-flight action does not freeze other writes. Failed-action replay is optional |
 | tRPC / RPC type-gen around `"use server"` | TypeScript does not cross HTTP — validate inside the function. Locals only the body reads (db, secrets) stay off the client |
 | `src/routes/api/todos.ts` (or a Next `route.ts`) wrapping `db.todos.insert` | `"use server"` *is* the RPC. API routes are for real HTTP endpoints (webhooks), not the app's own mutations |
@@ -1786,9 +2024,10 @@ always-applied rules installed alongside this skill.
       `loading`/`error` signals or `=== undefined` readiness branches. First load is
       `<Loading>`; refetch indicator is `isPending(user)` (the accessor, not `user()`)
       or `isPending(selectedId)` when the write is the question. `<Errored>` heals
-      when the source succeeds; `reset` retries sources, not a UI remount. Per-row
-      mutation failures stay in the action/projection, not in `<Errored>` around
-      the list. Error monitoring goes through `configureClientErrors` /
+      when the source succeeds; `reset` retries sources, not a UI remount. Mutation
+      failures never reach `<Errored>` (an escaping error reverts the overlay and
+      rejects the call): catch them in the action/projection, and `.catch` the call
+      in the handler. Error monitoring goes through `configureClientErrors` /
       `configureServerErrors` (or `render(..., { onError })`), never a side effect in
       the fallback. Core `refresh(source)`, router `revalidate(key)`, and `return reload(...)` are
       different APIs — do not mix them. Client → server is additive (same
@@ -1813,7 +2052,10 @@ always-applied rules installed alongside this skill.
       component choice with `dynamic()`. No `React.lazy`, no effects inside ref callbacks.
 - [ ] Browser-only code uses `isServer` / `clientOnly` (components) / `ssrSource`
       (values), not `typeof window`.
-      Component teardown is `onSettled` (return cleanup), not `onCleanup`.
+      Component teardown is `onSettled` (return cleanup), not `onCleanup`; nothing
+      inside the `onSettled` callback calls `onCleanup`, `flush()`, or creates a
+      memo/effect. Effect `apply` functions have block bodies and return only a
+      cleanup or nothing.
 - [ ] Dev console shows no diagnostics: reads in tracking scopes (no
       `[STRICT_READ_UNTRACKED]`), store setters synchronous and never called at
       body level (no `[ASYNC_STORE_SETTER]` / `[REACTIVE_WRITE_IN_OWNED_SCOPE]`), held

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

@@ -66,6 +66,7 @@ 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/state-management.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/guides/debugging-reactivity.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/guides/performance.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/guides/observability.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid2-agent-kit",
-  "version": "0.14.0",
+  "version": "0.15.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",